2.7 Callback functions (Extending LilyPond)

### 2.7 Callback functions

Properties (like `thickness`, `direction`, etc.) can be set at fixed values with `\override`, e.g.

    \override Stem.thickness = #2.0

Properties can also be set to a Scheme procedure:

>     \override Stem.thickness = #(lambda (grob)
>         (if (= UP (ly:grob-property grob 'direction))
>             2.0
>             7.0))
>     \relative { c'' b a g b a g b }

In this case, the procedure is executed as soon as the value of the property is requested during the formatting process.

Most of the typesetting engine is driven by such callbacks. Properties that typically use callbacks include

`stencil`

  The printing routine, that constructs a drawing for the symbol

`X-offset`

  The routine that sets the horizontal position

`X-extent`

  The routine that computes the width of an object

The procedure always takes a single argument, being the grob.

That procedure may access the usual value of the property, by first calling the function that is the usual callback for that property, which can by found in the Internals Reference or the file ’define-grobs.scm’:

    \relative {
      \override Flag.X-offset = #(lambda (flag)
        (let ((default (ly:flag::calc-x-offset flag)))
          (* default 4.0)))
      c''4. d8 a4. g8
    }

It is also possible to get the value of the existing default by employing the function `grob-transformer`:

>     \relative {
>       \override Flag.X-offset = #(grob-transformer 'X-offset
>         (lambda (flag default) (* default 4.0)))
>       c''4. d8 a4. g8
>     }

From within a callback, the easiest method for evaluating a markup is to use grob-interpret-markup. For example:

    my-callback = #(lambda (grob)
                     (grob-interpret-markup grob (markup "foo")))

#### Extending LilyPond v2.26.0 (stable-branch).

- 1 Scheme tutorial
  - 1.1 Introduction to Scheme
    - 1.1.1 Scheme sandbox
    - 1.1.2 Scheme variables
    - 1.1.3 Scheme simple data types
    - 1.1.4 Scheme compound data types
      - Pairs
      - Lists
      - Association lists (alists)
      - Hash tables
    - 1.1.5 Calculations in Scheme
    - 1.1.6 Scheme procedures
      - Defining procedures
      - Predicates
      - Return values
    - 1.1.7 Scheme conditionals
      - if
      - cond
  - 1.2 Scheme in LilyPond
    - 1.2.1 LilyPond Scheme syntax
    - 1.2.2 LilyPond variables
    - 1.2.3 Debugging Scheme code
    - 1.2.4 Input variables and Scheme
    - 1.2.5 Importing Scheme in LilyPond
    - 1.2.6 Object properties
    - 1.2.7 LilyPond compound variables
      - Offsets
      - Fractions
      - Extents
      - Property alists
      - Alist chains
    - 1.2.8 LilyPond’s box model
    - 1.2.9 Internal music representation
  - 1.3 Building complicated functions
    - 1.3.1 A first approach (example)
    - 1.3.2 Displaying music expressions
    - 1.3.3 Music properties
    - 1.3.4 Doubling a note with slurs (example)
    - 1.3.5 Adding articulation to notes (example)
- 2 Interfaces for programmers
  - 2.1 LilyPond code blocks
  - 2.2 Scheme functions
    - 2.2.1 Scheme function definitions
    - 2.2.2 Scheme function usage
    - 2.2.3 Void Scheme functions
  - 2.3 Music functions
    - 2.3.1 Music function definitions
    - 2.3.2 Music function usage
    - 2.3.3 Simple substitution functions
    - 2.3.4 Intermediate substitution functions
    - 2.3.5 Mathematics in functions
    - 2.3.6 Functions without arguments
    - 2.3.7 Void music functions
  - 2.4 Event functions
  - 2.5 Markup functions
    - 2.5.1 Markup construction in Scheme
    - 2.5.2 How markups work internally
    - 2.5.3 New markup command definition
      - Markup command definition syntax
      - On properties
      - A complete example
      - Adapting builtin commands
      - Converting markups to strings
    - 2.5.4 New markup list command definition
  - 2.6 Contexts for programmers
    - 2.6.1 Context evaluation
    - 2.6.2 Running a function on all layout objects
  - 2.7 Callback functions
  - 2.8 Unpure-pure containers
  - 2.9 Difficult tweaks
- 3 LilyPond Scheme interfaces
- Appendix A GNU Free Documentation License
- Appendix B Index