+@node La instrucción offset
+@subsection La instrucción @code{\offset}
+@translationof The offset command
+
+@funindex \offset
+@cindex desplazamiento
+@cindex valores predeterminados, desplazar
+
+Aunque es posible fijar propiedades de grob a valores nuevos con
+las instrucciones @code{\override}, @code{\tweak} y
+@code{\overrideProperty}, muchas veces conviene más modificar
+dichas propiedades en una cantidad relativa al valor
+predeterminado. La instrucción @code{\offset} se encuentra
+disponible para este fin.
+
+La sintaxis de @code{\offset} es
+
+@example
+[-]\offset @var{propiedad} @var{incrementos} @var{elemento}
+@end example
+
+La instrucción funciona añadiendo el contenido de
+@var{incrementos} al ajuste predeterminado de la @var{propiedad}
+del grob indicado por @var{elemento}.
+
+Dependiendo de la formulación de la instrucción, @code{\offset}
+puede actuar como un @code{\tweak} (trucaje) o como un
+@code{\override} (sobreescritura). Las variaciones en su uso se
+explicarán después de haber examinado las propiedades de grob que
+se pueden usar con @code{\offset}.
+
+@subsubsubheading{Propiedades que admiten el desplazamiento}
+
+Muchas, pero no todas, las propiedades de grob admiten la
+aplicación de un desplazamiento. Si @var{propiedad} no se puede
+desplazar, el objeto permanece sin cambios y se emite una
+advertencia. En estos casos se deben usar en su lugar
+@code{\override} o @code{\tweak} para modificar el objeto.
+
+Se puede trabajar por ensayo y error y dejar que las advertencias
+nos sirvan de guía para saber lo que puede o no puede ser
+desplazado. Sin embargo, es posible un enfoque más sistemático.
+
+Los criterios siguientes determinan si una propiedad se puede
+modificar con @code{\offset}:
+
+@itemize
+
+@item
+La propiedad tiene un @q{ajuste predeterminado} en la descripción
+del grob. Tales propiedades aparecen listadas para cada grob en
+@rinternals{All layout objects} (y también están en
+@file{scm/define-grobs.scm}).
+
+@item
+La propiedad admite un valor numérico. Entre los valores
+numéricos se encuentran @code{number}, una lista de
+@code{number}s, @code{number-pair}, y @code{number-pair-list}.
+Las páginas de @rinternals{All layout objects} contienen una lista
+de los tipos de datos característicos de cada propiedad. No
+importa si el ajuste predeterminado es una función.
+
+@item
+La propiedad no puede ser una @q{subpropiedad} (una propiedad que
+reside dentro de otra propiedad).
+
+@item
+Las propiedades establecidas a valores infinitos no se pueden
+desplazar. No hay ninguna forma sensata de incrementar los valores
+infinitos positivos o negativos.
+@end itemize
+
+Los ejemplos siguientes tratan diversas propiedades de grob frente
+a los criterios que se han expuesto.
+
+@itemize
+
+@item Propiedades que se pueden desplazar
+
+@table @asis
+
+@item @code{Hairpin.height}
+
+Esta propiedad no es una subpropiedad, y está en la lista que
+aparece en @rinternals{Hairpin}. En cuanto a su valor, admite
+@q{dimension, in staff space} (dimensión, en espacios de
+pentagrama) fijado a @code{0.6666} (que claramente es un
+@code{number} no infinito).
+
+@item @code{Arpeggio.positions}
+
+En la lista de la página que describe @rinternals{Arpeggio}
+aparece una propiedad @code{positions} que admite una @q{pareja de
+números}. Su valor predeterminado es
+@code{ly:arpeggio::positions}, que es un @q{callback} que se
+evalúa durante la fase de tipografiado para dar como resultado una
+pareja de números para cualguier objeto @code{Arpeggio} dado.
+
+@end table
+
+@item Propiedades que no admiten el desplazamiento
+
+@table @asis
+
+@item @code{Hairpin.color}
+
+No hay un listado para @code{color} en @rinternals{Hairpin}.
+
+@item @code{Hairpin.circled-tip}
+
+La lista de @code{Hairpin.circled-tip} en la página de
+@rinternals{Hairpin} muestra que admite un valor @code{boolean}.
+Los valores booleanos so no numéricos.
+
+@item @code{Stem.details.lengths}
+
+Aunque está listado en @rinternals{Stem} y su valor por omisión es
+una lista de @code{number}s, es una @q{subpropiedad}. Por el
+momento no se contemplan las @q{propiedades anidadas}.
+
+@end table
+
+@end itemize
+
+@subsubsubheading{@bs{}offset como sobreescritura}
+
+Si @var{elemento} es un nombre de grob como @code{Arpeggio} o
+@code{Staff.OttavaBracket}, el resultado es un @code{\override} o
+sobreescritura de el tipo de grob especificado.
+
+@example
+\offset @var{propiedad} @var{incremento} [@var{contexto}.]@var{NombreDeGrob}
+@end example
+
+Observe que el guión precedente @emph{nunca} se utiliza con la
+forma @q{override}, de igual manera que nunca se usa con la propia
+instrucción @code{\override}.
+
+El ejemplo siguiente usa la forma @q{override}, de sobreescritura,
+para alargar los arpegios predeterminados que aparecen en el
+primer compás para que cubran todo el tamaño de los acordes. Los
+arpegios se amplían en medio espacio de pentagrama hacia arriba y
+hacia abajo. También se muestra la misma operación efectuada
+sobre el primer acorde con una sobreescritura normal de la
+propiedad the @code{positions}. Este método no es en absoluto
+expresivo de la acción de @q{ampliar en medio espacio de
+pentagrama}, porque los extremos se tienen que especificar
+mediante coordenadas absolutas, no relativas. Además, se
+necesitarían sobreescrituras individuales para los otros acordes,
+ya que varían en tamaño y posición.
+
+@lilypond[quote,verbatim]
+arpeggioMusic = {
+ <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
+ <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
+}
+
+{
+ \arpeggioMusic
+ \bar "||"
+ \offset positions #'(-0.5 . 0.5) Arpeggio
+ \arpeggioMusic
+ \bar "||"
+ \once \override Arpeggio.positions = #'(-3.5 . -0.5)
+ <c' e' g'>1\arpeggio
+ \bar "||"
+}
+@end lilypond
+
+En su uso como @q{override}, @code{\offset} se puede hacer
+preceder por @code{\once} o por @code{\temporary} y revertirse
+mediante @code{\revert} con la @var{propiedad}. Esto se sigue a
+partir del hecho de que @code{\offset} en realidad crea un
+@code{\override} para la @var{propiedad}.
+
+@lilypond[quote,verbatim]
+music = { c'8\< d' e' f'\! }
+
+{
+ \music
+ \offset height 1 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+ \once \offset height 1 Hairpin
+ \music \music
+ \bar "||"
+ \override Hairpin.height = 0.2
+ \music
+ \temporary \offset height 2 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+}
+@end lilypond
+
+Así como @code{\override}, la forma @q{override} de @code{\offset}
+se puede usar con @code{\undo} y con @code{\single}.
+
+@lilypond[quote,verbatim]
+longStem = \offset length 6 Stem
+
+{
+ \longStem c'4 c''' c' c''
+ \bar "||"
+ \undo \longStem c'4 c''' c' c''
+ \bar "||"
+ \single \longStem c'4 c''' c' c''
+ \bar "||"
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset como trucaje}
+
+Si @var{elemento} es una expresión musical como @code{(} o
+@code{\arpeggio}, el resultado es la misma expresión musical con
+un trucaje aplicado.
+
+@example
+[-]\offset [@var{NombreDeGrob}.]@var{propiedad} @var{incrementos} @var{expresión-musical}
+@end example
+
+La sintaxis de @code{\offset} en forma de @q{tweak} es análoga a
+la propia instrucción @code{\tweak}, tanto en orden como en cuanto
+a la presencia o ausencia del guión inicial.
+
+El ejemplo siguiente usa la forma @q{tweak} para ajustar la
+posición vertical del objeto @code{BreathingSign}. Compárelo con
+la instrucción @code{\tweak} normal que también aparece. La
+sintaxis es equivalente; sin embargo, la salida de @code{\tweak}
+es menos intuitiva, ya que @code{BreathingSign.Y-offset} se
+calcula a partir de la tercera línea del pentagrama. No es
+necesario saber cómo se calcula @code{Y-offset}, al usar
+@code{\offset}.
+
+@lilypond[quote,verbatim]
+{
+ c''4
+ \breathe
+ c''4
+ \offset Y-offset 2 \breathe
+ c''2
+ \tweak Y-offset 3 \breathe
+}
+@end lilypond
+
+En el ejemplo anterior, los objetos trucados se crearon
+directamente a partir de la entrada del usuario: la instrucción
+@code{\breathe} era una instrucción explícita para devolver un
+objeto @code{BreathingSign}. Dado que el objeto de la instrucción
+no es ambiguo, no había necesidad de especificar el nombre del
+objeto. Sin embargo, cuando un objeto se crea
+@emph{indirectamente}, es necesario incluir el nombre del grob.
+Es lo mismo que para la instrucción @code{\tweak}.
+
+En el ejemplo siguiente, el objeto @code{Beam} se baja en dos
+espacios de pentagrama aplicando @code{\offset} a la propiedad
+@code{positions}.
+
+La primera aplicación de @code{\offset} exige que se incluya el
+nombre del grob, porque nada en el código de entrada crea
+explícitamente la barra. En la segunda aplicación, la barra se
+crea manualmente con la expresión musical @code{[}; por tanto, el
+nombre del grob no es necesario (también aparece en la ilustración
+una abreviatura: un solo número se aplica a los dos miembros de
+una pareja).
+
+@lilypond[quote,verbatim]
+{
+ c''8 g'' e'' d''
+ \offset Beam.positions #'(-2 . -2)
+ c''8 g'' e'' d''
+ c''8 g'' e'' d''
+ c''8-\offset positions #-2 [ g'' e'' d'']
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset con objetos extensos divididos}
+
+También es posible modificar segmentos de un objeto que se
+extiende sobre un salto o saltos de línea. En este caso,
+@var{offsets} admite una lista de valores del tipo de datos
+requerido por la propiedad.
+
+La instrucción @code{\offset} usada de esta forma es similar a la
+instrucción @code{\alterBroken}
+(véase @ref{Modificación de objetos de extensión divididos}). Sin
+embargo, a diferencia de @code{\alterBroken}, los valores que se
+le dan a @code{\offset} son relativos, no absolutos.
+
+El ejemplo siguiente desplaza el objeto @q{dividido}
+@code{OttavaBracket} a través de su propiedad
+@code{staff-padding}. Dado que la propiedad toma un
+@code{number}, se le proporciona a @var{incrementos} una lista de
+números para aplicarlos a los dos segmentos creados por el salto
+de línea. La parte de ligadura de la primera línea queda, en
+realidad, inalterada, ya que se añade @code{0} a su valor por
+omisión. El segmento que está en la segunda línea se eleva dos
+espacios de pentagrama a partir de su altura por omisión. La
+altura predeterminada resulta ser @code{2}, aunque no es necesario
+saberlo.
+
+@lilypond[quote,verbatim]
+{
+ \offset staff-padding #'(0 3) Staff.OttavaBracket
+ \ottava #1
+ c'''2 c'''
+ \break
+ c'''2 c'''
+}
+@end lilypond
+
+El ejemplo siguiente copia el efecto de la instrucción
+@code{\shape} mediante el incremento de la propiedad
+@code{control-points} del objeto @code{Slur}. Aquí,
+@var{incrementos} es una lista de parejas de números, una por cada
+segmento de la ligadura. Este ejemplo produce un resultado
+idéntico a la ilustración correspondiente que aparece en
+@ref{Modificación de las formas}.
+
+@lilypond[quote,verbatim]
+{
+ c'4-\offset control-points #'(
+ ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) ( f'4 g' c''
+ \break
+ d'4 c'' f' c')
+}
+@end lilypond
+
+
projects / lilypond.git / commitdiff