[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Note names ]	[ Up : Outside the staff ]	[ Grid lines > ]

---

Balloon help

Elements of notation can be marked and named with the help of a square balloon. The primary purpose of this feature is to explain notation.

\new Voice \with { \consists Balloon_engraver }
\relative c'' {
  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
  a8
  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
  r
  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}

There are two music functions, balloonText and balloonGrobText; the former is used like \tweak, but only within chords, to attach text to an individual note of the chord; the latter is used like \once \override to attach text to any grob anywhere.

Balloon text does not influence note spacing, but this can be altered:

\new Voice \with { \consists Balloon_engraver }
\relative c'' {
  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
  a8
  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
  r
  \balloonLengthOn
  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}

The default behavior for the attachment point of the line on the frame and the alignment of the balloon text is demonstrated below.

The default calculation of the attachment point can be overruled using the X-attachment and Y-attachment properties, which take values between -1 and 1, with the limits corresponding to the left (resp. bottom) and right (resp. top) of the frame. Alignment of the text is controlled by text-alignment-X and text-alignment-Y, which have a similar form.

\new Voice \with {
  \consists Balloon_engraver
}
{
  \once \override BalloonText.Y-attachment = -0.5
  \once \override BalloonText.text-alignment-X = 0.0
  \balloonGrobText Rest #'(1 . 3.5) "rest"
  r4
}

Predefined commands

\balloonLengthOn, \balloonLengthOff.

See also

Snippets: Editorial annotations.

Internals Reference: AnnotateOutputEvent, Balloon_engraver, BalloonText, balloon-interface.