Documentation/nl/notation/programming-interface.itely

   1 \input texinfo @c -*- coding: utf-8; mode: texinfo; documentlanguage: nl -*-
   2 @c This file is part of notation.tely
   3 @ignore
   4     Translation of GIT committish: 1b3da70d81938d19a2b107382bbe25a267cf130b
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10
  11 @c -*- coding: utf-8; mode: texinfo; -*-
  12 @c \version "2.12.0"
  13 @node Interfaces for programmers
  14 @chapter Interfaces for programmers
  15
  16 @untranslated
  17
  18
  19 @menu
  20 * Music functions::
  21 * Programmer interfaces::
  22 * Building complicated functions::
  23 * Markup programmer interface::
  24 * Contexts for programmers::
  25 * Scheme procedures as properties::
  26 * Using Scheme code instead of \tweak::
  27 * Difficult tweaks::
  28 @end menu
  29
  30 @node Music functions
  31 @section Music functions
  32
  33 @untranslated
  34
  35
  36 @menu
  37 * Overview of music functions::
  38 * Simple substitution functions::
  39 * Paired substitution functions::
  40 * Mathematics in functions::
  41 * Void functions::
  42 * Functions without arguments::
  43 * Overview of available music functions::
  44 @end menu
  45
  46 @node Overview of music functions
  47 @subsection Overview of music functions
  48
  49 @untranslated
  50
  51
  52 @node Simple substitution functions
  53 @subsection Simple substitution functions
  54
  55 @untranslated
  56
  57
  58 @node Paired substitution functions
  59 @subsection Paired substitution functions
  60
  61 @untranslated
  62
  63
  64 @quotation
  65 @end quotation
  66 @node Mathematics in functions
  67 @subsection Mathematics in functions
  68
  69 @untranslated
  70
  71
  72 @node Void functions
  73 @subsection Void functions
  74
  75 @untranslated
  76
  77
  78 @c ode{'void} property set to @code{#t}, the parser is told to
  79 @node Functions without arguments
  80 @subsection Functions without arguments
  81
  82 @untranslated
  83
  84
  85 @node Overview of available music functions
  86 @subsection Overview of available music functions
  87
  88 @untranslated
  89
  90
  91 @c fixme ; this should be move somewhere else?
  92 @include identifiers.tely
  93 @node Programmer interfaces
  94 @section Programmer interfaces
  95
  96 @untranslated
  97
  98
  99 @menu
 100 * Input variables and Scheme::
 101 * Internal music representation::
 102 @end menu
 103
 104 @node Input variables and Scheme
 105 @subsection Input variables and Scheme
 106
 107 @untranslated
 108
 109
 110 @c ode{traLaLa}.
 111 @c ode{\layout} block also contains a @code{traLaLa} variable, which is
 112 @c
 113 @c ode{\midi}, and @code{\layout} blocks are scopes nested inside that
 114 @c ode{twice}:
 115 @c Due to parser lookahead
 116 @ref{Void functions}, or
 117 @c ode{--safe} option.
 118 @node Internal music representation
 119 @subsection Internal music representation
 120
 121 @untranslated
 122
 123
 124 @c ode{note-event}, a @code{rhythmic-event}, and a
 125 @c ode{melodic-event}.  All classes of music are listed in the
 126 @c ode{duration} properties that store the pitch and duration of that
 127 @c ode{element}.  The body of a repeat is stored in the @code{element}
 128 @c ode{elements}.
 129 @node Building complicated functions
 130 @section Building complicated functions
 131
 132 @untranslated
 133
 134
 135 @menu
 136 * Displaying music expressions::
 137 * Music properties::
 138 * Doubling a note with slurs (example)::
 139 * Adding articulation to notes (example)::
 140 @end menu
 141
 142 @node Displaying music expressions
 143 @subsection Displaying music expressions
 144
 145 @untranslated
 146
 147
 148 @c index internal storage
 149 @c index displaying music expressions
 150 @c index internal representation, displaying
 151 @c index displayMusic
 152 @c ode{AbsoluteDynamicEvent} with a @code{"f"} text property.
 153 @node Music properties
 154 @subsection Music properties
 155
 156 @untranslated
 157
 158
 159 @c ode{'elements} property of @code{someNote}.
 160 @c ode{\displayMusic} to display the Scheme representation of a music
 161 @node Doubling a note with slurs (example)
 162 @subsection Doubling a note with slurs (example)
 163
 164 @untranslated
 165
 166
 167 @c ode{'elements} property of each one, and finally make a
 168 @c ode{SequentialMusic} with the two @code{EventChords}.
 169 @node Adding articulation to notes (example)
 170 @subsection Adding articulation to notes (example)
 171
 172 @untranslated
 173
 174
 175 @ref{Creating contexts}.  However, suppose that we want to write
 176 @c ode{event-chord}.  In Scheme, the type of variable is often clear
 177 @c ode{let} is used to declare local variables.  Here we use one local
 178 @c ode{(ly:music-deep-copy event-chord)}.  @code{ly:music-deep-copy} is
 179 @c ode{ly:}.  It is use to make a copy of a music
 180 @c ode{EventChord} expression.  It is better to not modify the
 181 @c ode{EventChord} which was given as an argument, because it may be
 182 @c ode{NoteEventChord} expression and is a copy of @code{event-chord}.  We
 183 @c ode{result-event-chord} expression.
 184 @c ode{ly:music-property} is the function used to access music properties
 185 @c ode{ArticulationEvent} expression, which we copy from the
 186 @c ode{\displayMusic} output,
 187 @c ode{cons} is used to add an element to a list without modifying the
 188 @node Markup programmer interface
 189 @section Markup programmer interface
 190
 191 @untranslated
 192
 193
 194 @menu
 195 * Markup construction in Scheme::
 196 * How markups work internally::
 197 * New markup command definition::
 198 * New markup list command definition::
 199 @end menu
 200
 201 @node Markup construction in Scheme
 202 @subsection Markup construction in Scheme
 203
 204 @untranslated
 205
 206
 207 @c index defining markup commands
 208 @quotation
 209 @end quotation
 210 @c ode{markup} macro.  For example, You may use function calls inside
 211 @c ode{markup} in order to manipulate character strings.  This is
 212 @ref{New markup command definition}).
 213 @c ode{#:center}, and @code{#:column} cannot be a variable or
 214 @c ode{make-center-markup}, or @code{make-column-markup} functions
 215 @node How markups work internally
 216 @subsection How markups work internally
 217
 218 @untranslated
 219
 220
 221 @c ode{\raise} is actually represented by the @code{raise-markup}
 222 @c ode{raise-markup} function is called as
 223 @c ode{text example} string, and then it raises that Stencil by 0.5
 224 @node New markup command definition
 225 @subsection New markup command definition
 226
 227 @untranslated
 228
 229
 230 @c ode{#'caps} for interpreting @code{Text-in-caps}.
 231 @c ode{padding} property) from the staff and the notes.  To make sure
 232 @c ode{#:translate}, we add an empty string (@code{#:hspace 0}) before the
 233 @c ode{name} is moved in relation to that empty string.  The net effect is
 234 @c ode{(make-line-markup ...)}.  Finally, the resulting markup is passed
 235 @c ode{props} arguments.
 236 @ref{Text markup commands}, for details.
 237 @c ode{define-markup-command} are limited as follows.
 238 @c index Scheme signature
 239 @c index signature, Scheme
 240 @c ommand{lilypond} complains that it cannot parse @code{foo} due to its
 241 @node New markup list command definition
 242 @subsection New markup list command definition
 243
 244 @untranslated
 245
 246
 247 @c ode{define-markup-list-command} Scheme macro, which is similar to the
 248 @c ode{define-markup-command} macro described in
 249 @ref{New markup command definition}, except that where the latter returns
 250 @c ode{paragraph} markup list command takes a markup list argument, named
 251 @c ode{args}.  The predicate for markup lists is @code{markup-list?}.
 252 @c ode{par-indent}, from the property list @code{props} If the property
 253 @node Contexts for programmers
 254 @section Contexts for programmers
 255
 256 @untranslated
 257
 258
 259 @menu
 260 * Context evaluation::
 261 * Running a function on all layout objects::
 262 @end menu
 263
 264 @node Context evaluation
 265 @subsection Context evaluation
 266
 267 @untranslated
 268
 269
 270 @c index calling code during interpreting
 271 @node Running a function on all layout objects
 272 @subsection Running a function on all layout objects
 273
 274 @untranslated
 275
 276
 277 @c index calling code on layout objects
 278 @node Scheme procedures as properties
 279 @section Scheme procedures as properties
 280
 281 @untranslated
 282
 283
 284 @c ode{AccidentalSuggestion},
 285 @c ode{ly:self-alignment-interface::centered-on-x-parent} are called
 286 @node Using Scheme code instead of \tweak
 287 @section Using Scheme code instead of @code{\tweak}
 288
 289 @untranslated
 290
 291
 292 @c ode{^} and @code{_}.
 293 @c ode{m} (created with @code{make-music}) are extracted with
 294 @c ode{ly:music-property}, a new key-value pair to change the
 295 @c ode{acons} Scheme function, and the result is finally
 296 @c ode{let} block is the return value, @code{m} itself.
 297 @node Difficult tweaks
 298 @section Difficult tweaks
 299
 300 @untranslated
 301
 302
 303 @c ode{after-line-breaking} callback contains the Scheme procedure that
 304 @c ode{my-callback}.  This procedure
 305 @c ode{ly:hairpin::after-line-breaking} should also be called.
 306 @c ode{\overrideProperty} function, which works similar to @code{\once
 307 @c ode{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
 308
 309 @c -- SKELETON FILE --