Left: | ||
Right: |
OLD | NEW |
---|---|
1 @c -*- coding: utf-8; mode: texinfo; -*- | 1 @c -*- coding: utf-8; mode: texinfo; -*- |
2 | 2 |
3 @ignore | 3 @ignore |
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH | 4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH |
5 | 5 |
6 When revising a translation, copy the HEAD committish of the | 6 When revising a translation, copy the HEAD committish of the |
7 version that you are working on. For details, see the Contributors' | 7 version that you are working on. For details, see the Contributors' |
8 Guide, node Updating translation committishes.. | 8 Guide, node Updating translation committishes.. |
9 @end ignore | 9 @end ignore |
10 | 10 |
(...skipping 1807 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1818 @c backslash once the new macro to handle the refs | 1818 @c backslash once the new macro to handle the refs |
1819 @c is available. Need to find and change all refs at | 1819 @c is available. Need to find and change all refs at |
1820 @c the same time. -td | 1820 @c the same time. -td |
1821 | 1821 |
1822 @menu | 1822 @menu |
1823 * Overview of modifying properties:: | 1823 * Overview of modifying properties:: |
1824 * The set command:: | 1824 * The set command:: |
1825 * The override command:: | 1825 * The override command:: |
1826 * The tweak command:: | 1826 * The tweak command:: |
1827 * set versus override:: | 1827 * set versus override:: |
1828 * The offset command:: | |
1828 * Modifying alists:: | 1829 * Modifying alists:: |
1829 @end menu | 1830 @end menu |
1830 | 1831 |
1831 | 1832 |
1832 @node Overview of modifying properties | 1833 @node Overview of modifying properties |
1833 @subsection Overview of modifying properties | 1834 @subsection Overview of modifying properties |
1834 | 1835 |
1835 Each context is responsible for creating certain types of graphical | 1836 Each context is responsible for creating certain types of graphical |
1836 objects. The settings used for printing these objects are also stored by | 1837 objects. The settings used for printing these objects are also stored by |
1837 context. By changing these settings, the appearance of objects can be | 1838 context. By changing these settings, the appearance of objects can be |
(...skipping 659 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
2497 @funindex \tweak | 2498 @funindex \tweak |
2498 @funindex \overrideProperty | 2499 @funindex \overrideProperty |
2499 | 2500 |
2500 The commands @code{\tweak} and @code{\overrideProperty} change grob | 2501 The commands @code{\tweak} and @code{\overrideProperty} change grob |
2501 properties by bypassing all context properties completely and, instead, | 2502 properties by bypassing all context properties completely and, instead, |
2502 catch grobs as they are being created, setting properties on them for | 2503 catch grobs as they are being created, setting properties on them for |
2503 a music event (@code{\tweak}) or, in the case of | 2504 a music event (@code{\tweak}) or, in the case of |
2504 @code{\overrideProperty} for a specific override. | 2505 @code{\overrideProperty} for a specific override. |
2505 | 2506 |
2506 | 2507 |
2508 @node The offset command | |
2509 @subsection The @code{\offset} command | |
2510 | |
2511 @funindex \offset | |
2512 @cindex offsetting | |
2513 @cindex defaults, offsetting | |
2514 | |
2515 While it is possible to set grob properties to new values with the | |
2516 @code{\override}, @code{\tweak}, and @code{\overrideProperty} commands, | |
2517 it is often more convenient to modify such properties relative to a | |
2518 default value. The @code{\offset} command is available for this | |
2519 purpose. | |
2520 | |
2521 The syntax for @code{\offset} is | |
2522 | |
2523 @example | |
2524 [-]\offset @var{property} @var{offsets} @var{item} | |
2525 @end example | |
2526 | |
2527 The command works by adding the contents of @var{offsets} to the | |
2528 default setting of the property @var{property} of the grob indicated by | |
2529 @var{item}. | |
2530 | |
2531 Depending on the formulation of the command, @code{\offset} may act | |
2532 as either a @code{\tweak} or @code{\override}. The variations in | |
2533 usage are discussed after consideration is given to grob properties | |
2534 that may be used with @code{\offset}. | |
2535 | |
2536 @subsubsubheading{Properties which may be offset} | |
2537 | |
2538 Many, but not all, grob properties may be offset. If @var{property} | |
2539 cannot be offset, the object will remain unchanged and a warning will | |
2540 be issued. In such cases, @code{\override} or @code{\tweak} should be | |
2541 used to modify the object instead. | |
2542 | |
2543 One can work by trial and error and let the warnings be the guide to | |
2544 what may or may not be offset. A more systematic approach is possible, | |
2545 however. | |
2546 | |
2547 The following criteria determine whether a property can be modified with | |
2548 @code{\offset}: | |
2549 | |
2550 @itemize | |
2551 | |
2552 @item | |
2553 The property has a @q{default setting} in the grob's description. Such | |
2554 properties are listed for each grob in @rinternals{All layout objects}. | |
2555 (They are also found in @file{scm/define-grobs.scm}.) | |
2556 | |
2557 @item | |
2558 The property takes a numerical value. Numerical values include | |
2559 @code{number}, list of @code{number}s, @code{number-pair}, and | |
2560 @code{number-pair-list}. The pages at @rinternals{All layout objects} | |
2561 list the type of data characteristic to each property. It is immaterial | |
2562 whether the default setting is a function. | |
2563 | |
2564 @item | |
2565 The property cannot be a @q{subproperty}---a property residing within | |
2566 another property. | |
2567 | |
2568 @item | |
2569 Properties set to infinite values cannot be offset. There is no | |
2570 sensible way to offset positive and negative infinity. | |
2571 @end itemize | |
2572 | |
2573 The following examples consider several grob properties against the | |
2574 criteria outlined above. | |
2575 | |
2576 @itemize | |
2577 | |
2578 @item Properties that may be offset | |
2579 | |
2580 @table @asis | |
2581 | |
2582 @item @code{Hairpin.height} | |
2583 | |
2584 This property is not a subproperty, and it is listed at | |
2585 @rinternals{Hairpin}. For a value, it takes @q{dimension, in staff | |
2586 space} set to @code{0.6666}---clearly a non-infinite @code{number}. | |
2587 | |
2588 @item @code{Arpeggio.positions} | |
2589 | |
2590 The page @rinternals{Arpeggio} lists a @code{positions} property which | |
2591 accepts a @q{pair of numbers}. It defaults to | |
2592 @code{ly:arpeggio::positions}---a callback which will be evaluated | |
2593 during the typesetting phase to yield a pair of numbers for any given | |
2594 @code{Arpeggio} object. | |
2595 | |
2596 @end table | |
2597 | |
2598 @item Properties that may not be offset | |
2599 | |
2600 @table @asis | |
2601 | |
2602 @item @code{Hairpin.color} | |
2603 | |
2604 There is no listing for @code{color} at @rinternals{Hairpin}. | |
2605 | |
2606 @item @code{Hairpin.circled-tip} | |
2607 | |
2608 The listing for @code{Hairpin.circled-tip} at @rinternals{Hairpin} shows | |
2609 that it takes a @code{boolean} value. Booleans are non-numerical. | |
2610 | |
2611 @item @code{Stem.details.lengths} | |
2612 | |
2613 Though listed at @rinternals{Stem} and defaulting to a list of | |
2614 @code{number}s, this is a @q{subproperty}. There is currently no | |
2615 support for @q{nested properties}. | |
2616 | |
2617 @end table | |
2618 | |
2619 @end itemize | |
2620 | |
2621 @subsubsubheading{@bs{}offset as an override} | |
2622 | |
2623 If @var{item} is a grob name like @code{Arpeggio} or | |
2624 @code{Staff.OttavaBracket}, the result is an @code{\override} of the | |
2625 specified grob-type. | |
2626 | |
2627 @example | |
2628 \offset @var{property} @var{offsets} [@var{context}.]@var{GrobName} | |
2629 @end example | |
2630 | |
2631 Note that the leading hyphen is @emph{never} used with the @q{override} | |
2632 form, just as it is never used with the @code{\override} command itself. | |
2633 | |
2634 The following example uses the @q{override} form to lengthen the | |
2635 default arpeggios shown in the first measure to cover the extent of | |
2636 the chords more fully. The arpeggios are stretched by a half | |
2637 staff-space to top and bottom. Also shown is the same operation done on | |
2638 the first chord with an ordinary override of the @code{positions} | |
2639 property. This method is not at all expressive of the task of | |
2640 @q{stretching by a half staff-space}, as the endpoints must be specified | |
2641 with absolute rather than relative coordinates. Furthermore, individual | |
2642 overrides would be needed for the other chords, as they vary in size and | |
2643 position. | |
2644 | |
2645 @lilypond[quote,verbatim] | |
2646 arpeggioMusic = { | |
2647 <c' e' g'>\arpeggio <a' c'' e''>\arpeggio | |
2648 <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio | |
2649 } | |
2650 | |
2651 { | |
2652 \arpeggioMusic | |
2653 \bar "||" | |
2654 \offset positions #'(-0.5 . 0.5) Arpeggio | |
2655 \arpeggioMusic | |
2656 \bar "||" | |
2657 \once \override Arpeggio.positions = #'(-3.5 . -0.5) | |
2658 <c' e' g'>1\arpeggio | |
2659 \bar "||" | |
2660 } | |
2661 @end lilypond | |
2662 | |
2663 In its @q{override} usage, @code{\offset} may be prefaced with | |
2664 @code{\once} or @code{\temporary} and reverted using @code{\revert} with | |
2665 @var{property}. This follows from the fact that @code{\offset} actually | |
2666 creates an @code{\override} of @var{property}. | |
2667 | |
2668 @lilypond[quote,verbatim] | |
2669 music = { c'8\< d' e' f'\! } | |
2670 | |
2671 { | |
2672 \music | |
2673 \offset height 1 Hairpin | |
2674 \music | |
2675 \music | |
2676 \revert Hairpin.height | |
2677 \music | |
2678 \bar "||" | |
2679 \once \offset height 1 Hairpin | |
2680 \music \music | |
2681 \bar "||" | |
2682 \override Hairpin.height = 0.2 | |
2683 \music | |
2684 \temporary \offset height 2 Hairpin | |
2685 \music | |
2686 \music | |
2687 \revert Hairpin.height | |
2688 \music | |
2689 \bar "||" | |
2690 } | |
2691 @end lilypond | |
2692 | |
2693 Also like @code{\override}, the @q{override} form of @code{\offset} may | |
2694 be used with @code{\undo} and @code{\single}. | |
2695 | |
2696 @lilypond[quote,verbatim] | |
2697 longStem = \offset length 6 Stem | |
2698 | |
2699 { | |
2700 \longStem c'4 c''' c' c'' | |
2701 \bar "||" | |
2702 \undo \longStem c'4 c''' c' c'' | |
2703 \bar "||" | |
2704 \single \longStem c'4 c''' c' c'' | |
2705 \bar "||" | |
2706 } | |
2707 @end lilypond | |
2708 | |
2709 @subsubsubheading{@bs{}offset as a tweak} | |
2710 | |
2711 If @var{item} is a music expression such as @code{(} or | |
2712 @code{\arpeggio}, the result is the same music expression with a tweak | |
2713 applied. | |
2714 | |
2715 @example | |
2716 [-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression} | |
2717 @end example | |
2718 | |
2719 The syntax of @code{\offset} in its @q{tweak} form is analogous to the | |
2720 @code{\tweak} command itself, both in ordering and in the presence or | |
2721 absence of the leading hyphen. | |
2722 | |
2723 The following example uses the @q{tweak} form to adjust the vertical | |
2724 position of the @code{BreathingSign} object. Compare this with the | |
2725 ordinary @code{\tweak} command also demonstrated. The syntax is | |
2726 equivalent; however, the output of @code{\tweak} is less intuitive, | |
2727 since @code{BreathingSign.Y-offset} is calculated from the middle | |
2728 staff-line. It is not necessary to know how @code{Y-offset} is | |
2729 calculated when using @code{\offset}. | |
2730 | |
2731 @lilypond[quote,verbatim] | |
2732 { | |
2733 c''4 | |
2734 \breathe | |
2735 c''4 | |
2736 \offset Y-offset 2 \breathe | |
2737 c''2 | |
2738 \tweak Y-offset 3 \breathe | |
2739 } | |
2740 @end lilypond | |
2741 | |
2742 In the previous example, the tweaked objects were created directly from | |
2743 the user input: the @code{\breathe} command was an explicit instruction | |
2744 to return a @code{BreathingSign} object. Since the focus of the command | |
2745 was unambiguous, there was no need to specify the object's name. When | |
2746 an object is @emph{indirectly} created, however, it is necessary to | |
2747 include the grob's name. This is the same as for the @code{\tweak} | |
2748 command. | |
2749 | |
2750 In the following example, the @code{Beam} object is lowered two | |
2751 staff-spaces by applying @code{\offset} to the @code{positions} | |
2752 property. | |
2753 | |
2754 The first application of @code{\offset} requires that the grob's name | |
2755 be included, because nothing in the input explicitly creates the | |
2756 beam. In the second application, the beam is created manually with the | |
2757 music expression @code{[}; therefore, the grob's name is not needed. | |
2758 (Also illustrated is a shorthand: a single @code{number} will be applied | |
2759 to both members of a @code{number-pair}.) | |
2760 | |
2761 @lilypond[quote,verbatim] | |
2762 { | |
2763 c''8 g'' e'' d'' | |
2764 \offset Beam.positions #'(-2 . -2) | |
2765 c''8 g'' e'' d'' | |
2766 c''8 g'' e'' d'' | |
2767 c''8-\offset positions #-2 [ g'' e'' d''] | |
2768 } | |
2769 @end lilypond | |
2770 | |
2771 @subsubsubheading{@bs{}offset with broken spanners} | |
2772 | |
2773 Independently modifying segments of a spanner extending over a line | |
2774 break or breaks is also possible. In this case, @var{offsets} | |
2775 takes a list of values of the property's required data type. | |
2776 | |
2777 The @code{\offset} command used in this manner is similiar to the | |
simon.albrecht
2017/01/25 22:33:32
s/similiar/similar
david.nalesnik
2017/01/26 14:33:18
Yup--thanks. Will bundle that with whatever chang
| |
2778 @code{\alterBroken} command. (See @ref{Modifying broken spanners}.) | |
2779 In contrast with @code{\alterBroken}, however, the values given to | |
2780 @code{\offset} are relative, not absolute. | |
2781 | |
2782 The following example displaces the @q{broken} @code{OttavaBracket} | |
2783 object through its @code{staff-padding} property. Since the property | |
2784 takes a @code{number}, @var{offsets} is provided with a list of | |
2785 @code{number}s to account for the two segments created by the line | |
2786 break. The slur piece on the first line is effectively untouched since | |
2787 @code{0} is added to its default value. The segment on the second | |
2788 line is raised two staff-spaces from its default height. The default | |
2789 height happens to be @code{2}, though it is not necesssary to know this. | |
2790 | |
2791 @lilypond[quote,verbatim] | |
2792 { | |
2793 \offset staff-padding #'(0 3) Staff.OttavaBracket | |
2794 \ottava #1 | |
2795 c'''2 c''' | |
2796 \break | |
2797 c'''2 c''' | |
2798 } | |
2799 @end lilypond | |
2800 | |
2801 The following example mimics the effect of the @code{\shape} command by | |
2802 offsetting the @code{control-points} property of the @code{Slur} object. | |
2803 Here, @var{offsets} is a list of @code{number-pair-list}s, one for each | |
2804 slur segment. This example achieves a result identical to the | |
2805 corresponding illustration at @ref{Modifying shapes}. | |
2806 | |
2807 @lilypond[quote,verbatim] | |
2808 { | |
2809 c'4-\offset control-points #'( | |
2810 ((0 . 0) (0 . 0) (0 . 0) (0 . 1)) | |
2811 ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5)) | |
2812 ) ( f'4 g' c'' | |
2813 \break | |
2814 d'4 c'' f' c') | |
2815 } | |
2816 @end lilypond | |
2817 | |
2818 | |
2507 @node Modifying alists | 2819 @node Modifying alists |
2508 @subsection Modifying alists | 2820 @subsection Modifying alists |
2509 | 2821 |
2510 Some user-configurable properties are internally represented as | 2822 Some user-configurable properties are internally represented as |
2511 @emph{alists} (association lists), which store pairs of | 2823 @emph{alists} (association lists), which store pairs of |
2512 @emph{keys} and @emph{values}. The structure of an alist is: | 2824 @emph{keys} and @emph{values}. The structure of an alist is: |
2513 | 2825 |
2514 @example | 2826 @example |
2515 '((@var{key1} . @var{value1}) | 2827 '((@var{key1} . @var{value1}) |
2516 (@var{key2} . @var{value2}) | 2828 (@var{key2} . @var{value2}) |
(...skipping 2351 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
4868 | 5180 |
4869 \relative { | 5181 \relative { |
4870 \tempo \markup { "Low tempo" } | 5182 \tempo \markup { "Low tempo" } |
4871 c''4 d e f g1 | 5183 c''4 d e f g1 |
4872 \tempoPadded #4.0 "High tempo" | 5184 \tempoPadded #4.0 "High tempo" |
4873 g4 f e d c1 | 5185 g4 f e d c1 |
4874 } | 5186 } |
4875 @end lilypond | 5187 @end lilypond |
4876 | 5188 |
4877 @c TODO: add appropriate @@ref's here. | 5189 @c TODO: add appropriate @@ref's here. |
OLD | NEW |