]> git.donarmstrong.com Git - lilypond.git/blobdiff - scm/define-grob-properties.scm
Doc: IR - Improve grob 'size' description
[lilypond.git] / scm / define-grob-properties.scm
index a81eed50092532ff51f15dac177a062e2edc8386..db5b2e1d7bec55f5dc93a7d0183144327481ddd2 100644 (file)
@@ -1,6 +1,6 @@
 ;;;; This file is part of LilyPond, the GNU music typesetter.
 ;;;;
 ;;;; This file is part of LilyPond, the GNU music typesetter.
 ;;;;
-;;;; Copyright (C) 1998--2014  Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;; Copyright (C) 1998--2015  Han-Wen Nienhuys <hanwen@xs4all.nl>
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 ;;;;
 ;;;; LilyPond is free software: you can redistribute it and/or modify
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 ;;;;
 ;;;; LilyPond is free software: you can redistribute it and/or modify
@@ -199,7 +199,7 @@ measure of the closeness of the inner stems.  It is used for damping
 the slope of the beam.")
      (connect-to-neighbor ,pair? "Pair of booleans, indicating whether
 this grob looks as a continued break.")
 the slope of the beam.")
      (connect-to-neighbor ,pair? "Pair of booleans, indicating whether
 this grob looks as a continued break.")
-     (control-points ,list? "List of offsets (number pairs) that form
+     (control-points ,number-pair-list? "List of offsets (number pairs) that form
 control points for the tie, slur, or bracket shape.  For B@'eziers,
 this should list the control points of a third-order B@'ezier curve.")
      (count-from ,integer? "The first measure in a measure count
 control points for the tie, slur, or bracket shape.  For B@'eziers,
 this should list the control points of a third-order B@'ezier curve.")
      (count-from ,integer? "The first measure in a measure count
@@ -214,8 +214,9 @@ increments from this initial value.")
 dash structure.  Each @code{dash-element} has a starting t value,
 an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.")
      (dash-fraction ,number? "Size of the dashes, relative to
 dash structure.  Each @code{dash-element} has a starting t value,
 an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.")
      (dash-fraction ,number? "Size of the dashes, relative to
-@code{dash-period}.  Should be between @code{0.0} (no line) and
-@code{1.0} (continuous line).")
+@code{dash-period}.  Should be between @code{0.1} and
+@code{1.0} (continuous line).  If set to @code{0.0}, a dotted line is
+produced")
      (dash-period ,number? "The length of one dash together with
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head
      (dash-period ,number? "The length of one dash together with
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head
@@ -530,6 +531,8 @@ the string will be assigned to the @code{id} attribute of a group (<g>)
 that encloses the stencils that comprise the grob.  In the Postscript
 backend, as there is no way to group items, the setting of the id property
 will have no effect.")
 that encloses the stencils that comprise the grob.  In the Postscript
 backend, as there is no way to group items, the setting of the id property
 will have no effect.")
+     (ignore-ambitus ,boolean? "If set, don't consider this notehead
+for ambitus calculation.")
      (ignore-collision ,boolean? "If set, don't do note collision
 resolution on this @code{NoteColumn}.")
      (implicit ,boolean? "Is this an implicit bass figure?")
      (ignore-collision ,boolean? "If set, don't do note collision
 resolution on this @code{NoteColumn}.")
      (implicit ,boolean? "Is this an implicit bass figure?")
@@ -637,6 +640,11 @@ this long, normally in the horizontal direction.  This requires an
 appropriate callback for the @code{springs-and-rods} property.  If
 added to a @code{Tie}, this sets the minimum distance between
 noteheads.")
 appropriate callback for the @code{springs-and-rods} property.  If
 added to a @code{Tie}, this sets the minimum distance between
 noteheads.")
+     (minimum-length-after-break ,ly:dimension? "If set, try to make
+a broken spanner starting a line this long.  This requires an
+appropriate callback for the @code{springs-and-rods} property.  If
+added to a @code{Tie}, this sets the minimum distance to the
+notehead.")
      (minimum-length-fraction ,number? "Minimum length of ledger line
 as fraction of note head size.")
      (minimum-space ,ly:dimension? "Minimum distance that the victim
      (minimum-length-fraction ,number? "Minimum length of ledger line
 as fraction of note head size.")
      (minimum-space ,ly:dimension? "Minimum distance that the victim
@@ -698,6 +706,8 @@ over the total spanner, where the width of the spanner is normalized
 between 0 and 1.")
      (note-names ,vector? "Vector of strings containing names for
 easy-notation note heads.")
 between 0 and 1.")
      (note-names ,vector? "Vector of strings containing names for
 easy-notation note heads.")
+     (number-type ,symbol? "Numbering style. Choices include
+@code{roman-lower}, @code{roman-upper} and @code{arabic}.")
 
 
 ;;;
 
 
 ;;;
@@ -767,6 +777,10 @@ If unset, the value from @code{self-alignment-X} property will be
 used.")
      (parent-alignment-Y ,number? "Like @code{parent-alignment-X}
 but for the Y@tie{}axis.")
 used.")
      (parent-alignment-Y ,number? "Like @code{parent-alignment-X}
 but for the Y@tie{}axis.")
+     (parenthesis-friends ,list? "A list of Grob types, as symbols.
+When parentheses enclose a Grob that has 'parenthesis-friends, the
+parentheses widen to include any child Grobs with type among
+'parenthesis-friends.")
      (parenthesized ,boolean? "Parenthesize this grob.")
      (positions ,number-pair? "Pair of staff coordinates
 @code{(@var{left} . @var{right})}, where both @var{left} and
      (parenthesized ,boolean? "Parenthesize this grob.")
      (positions ,number-pair? "Pair of staff coordinates
 @code{(@var{left} . @var{right})}, where both @var{left} and
@@ -837,6 +851,9 @@ value @w{@code{-1}} means left aligned, @code{0}@tie{}centered, and
 values may also be specified - the unit is half the object width.")
      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")
 values may also be specified - the unit is half the object width.")
      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")
+     (shape ,symbol? "This setting determines what shape a grob
+has.  Valid choices depend on the @code{stencil} callback reading
+this property.")
      (sharp-positions ,list? "Sharps in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order
      (sharp-positions ,list? "Sharps in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order
@@ -864,7 +881,8 @@ placed vertically.")
 object.")
      (simple-Y ,boolean? "Should the Y placement of a spanner
 disregard changes in system heights?")
 object.")
      (simple-Y ,boolean? "Should the Y placement of a spanner
 disregard changes in system heights?")
-     (size ,number? "Size of object, relative to standard size.")
+     (size ,number? "The ratio of the size of the object to its default
+size.")
      (skip-quanting ,boolean? "Should beam quanting be skipped?")
      (skyline-horizontal-padding ,number? "For determining the
 vertical distance between two staves, it is possible to have a
      (skip-quanting ,boolean? "Should beam quanting be skipped?")
      (skyline-horizontal-padding ,number? "For determining the
 vertical distance between two staves, it is possible to have a
@@ -902,7 +920,8 @@ Standard choices for @w{@code{@var{break-align-symbol}}} are listed in
 used when the grob is just left of the first note on a line
 
 @item next-note
 used when the grob is just left of the first note on a line
 
 @item next-note
-used when the grob is just left of any other note
+used when the grob is just left of any other note;
+if not set, the value of @code{first-note} gets used
 
 @item right-edge
 used when the grob is the last item on the line (only compatible with
 
 @item right-edge
 used when the grob is the last item on the line (only compatible with
@@ -1085,9 +1104,15 @@ automatically.")
 line just before it would otherwise stop.")
      (toward-stem-shift ,number? "Amount by which scripts are shifted
 toward the stem if their direction coincides with the stem direction.
 line just before it would otherwise stop.")
      (toward-stem-shift ,number? "Amount by which scripts are shifted
 toward the stem if their direction coincides with the stem direction.
-@code{0.0} means keep the default position (centered on the note
-head), @code{1.0} means centered on the stem.  Interpolated values are
-possible.")
+@code{0.0} means centered on the note head (the default position of
+most scripts); @code{1.0} means centered on the stem.  Interpolated
+values are possible.")
+     (toward-stem-shift-in-column ,number? "Amount by which a script
+is shifted toward the stem if its direction coincides with the stem
+direction and it is associated with a @code{ScriptColumn} object.
+@code{0.0} means centered on the note head (the default position of
+most scripts); @code{1.0} means centered on the stem.  Interpolated
+values are possible.")
      (transparent ,boolean? "This makes the grob invisible.")
 
 
      (transparent ,boolean? "This makes the grob invisible.")
 
 
@@ -1109,15 +1134,22 @@ positioning?")
 ;;;
      (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and
 one below this grob.")
 ;;;
      (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and
 one below this grob.")
+     (voiced-position ,number? "The staff-position of a voiced
+@code{Rest}, negative if the rest has @code{direction} @code{DOWN}.")
 
 ;;;
 ;;; w
 ;;;
 
 ;;;
 ;;; w
 ;;;
-     (when ,ly:moment? "Global time step associated with this column
-happen?")
-     (whiteout ,boolean? "If true, the grob is printed over a white
-background to white-out underlying material, if the grob is visible.
- Usually #f by default.")
+     (when ,ly:moment? "Global time step associated with this column.")
+     (whiteout ,boolean-or-number? "If a number or true, the grob is
+printed over a white background to white-out underlying material, if
+the grob is visible.  A number indicates how far the white background
+extends beyond the bounding box of the grob as a multiple of the
+staff-line thickness.  The shape of the background is determined by
+@code{whiteout-style}.  Usually @code{#f} by default.")
+     (whiteout-style ,symbol? "Determines the shape of the
+@code{whiteout} background.  Available are @code{'outline} and the
+default @code{'box}.")
      (width ,ly:dimension? "The width of a grob measured in staff
 space.")
      (word-space ,ly:dimension? "Space to insert between words in
      (width ,ly:dimension? "The width of a grob measured in staff
 space.")
      (word-space ,ly:dimension? "Space to insert between words in
@@ -1243,7 +1275,8 @@ empty in a particular staff, then that staff is erased.")
      (keep-alive-with ,ly:grob-array? "An array of other
 @code{VerticalAxisGroup}s.  If any of them are alive, then we will stay alive.")
 
      (keep-alive-with ,ly:grob-array? "An array of other
 @code{VerticalAxisGroup}s.  If any of them are alive, then we will stay alive.")
 
-     (left-items ,ly:grob-array? "DOCME")
+     (left-items ,ly:grob-array? "Grobs organized on the left by a spacing
+object.")
      (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish
 for this column.")
 
      (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish
 for this column.")
 
@@ -1274,13 +1307,18 @@ relevant for finding the @code{pure-Y-extent}.")
      (rest ,ly:grob? "A pointer to a @code{Rest} object.")
      (rest-collision ,ly:grob? "A rest collision that a rest is in.")
      (rests ,ly:grob-array? "An array of rest objects.")
      (rest ,ly:grob? "A pointer to a @code{Rest} object.")
      (rest-collision ,ly:grob? "A rest collision that a rest is in.")
      (rests ,ly:grob-array? "An array of rest objects.")
-     (right-items ,ly:grob-array? "DOCME")
+     (right-items ,ly:grob-array? "Grobs organized on the right by
+a spacing object.")
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 
+     (scripts ,ly:grob-array? "An array of @code{Script} objects.")
      (side-support-elements ,ly:grob-array? "The side support, an array of
 grobs.")
      (slur ,ly:grob? "A pointer to a @code{Slur} object.")
      (spacing ,ly:grob? "The spacing spanner governing this section.")
      (side-support-elements ,ly:grob-array? "The side support, an array of
 grobs.")
      (slur ,ly:grob? "A pointer to a @code{Slur} object.")
      (spacing ,ly:grob? "The spacing spanner governing this section.")
+     (space-increment ,ly:dimension? "The amount by which the total duration
+of a multimeasure rest affects horizontal spacing.  Each doubling of the
+duration adds @code{space-increment} to the length of the bar.")
      (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing
 objects.")
      (span-start ,boolean? "Is the note head at the start of a spanner?")
      (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing
 objects.")
      (span-start ,boolean? "Is the note head at the start of a spanner?")
@@ -1371,7 +1409,8 @@ to be within staff spaces.")
      (quantized-positions ,number-pair? "The beam positions after
 quanting.")
 
      (quantized-positions ,number-pair? "The beam positions after
 quanting.")
 
-
+     (script-column ,ly:grob? "A @code{ScriptColumn} associated with a
+@code{Script} object.")
      (script-stencil ,pair? "A pair @code{(@var{type} . @var{arg})} which
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.
      (script-stencil ,pair? "A pair @code{(@var{type} . @var{arg})} which
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.