| 1 | <HTML> |
| 2 | <HEAD><TITLE> |
| 3 | Location Tags |
| 4 | </TITLE></HEAD> |
| 5 | <BODY> |
| 6 | <P> |
| 7 | <A HREF="roll.html"><-- previous page</A> |
| 8 | |
| 9 | <A HREF="index.html">Table of Contents</A> <A HREF="prnttext.html">next page --></A> |
| 10 | </P> |
| 11 | |
| 12 | <H2> |
| 13 | Location tags |
| 14 | </H2> |
| 15 | <P> |
| 16 | A location tag is associated with a |
| 17 | <A HREF="noteattr.html#ntag">note,</A> |
| 18 | <A HREF="chrdattr.html#ctag">chord,</A> |
| 19 | or |
| 20 | <A HREF="bars.html#btag">barline.</A> |
| 21 | It can then be referenced in order to place a second object, like a comment |
| 22 | or dotted line, relative to the first object. |
| 23 | </P> |
| 24 | <P> |
| 25 | A tag name can be either a single lower case letter, or an underscore |
| 26 | folowed by one or more letters, digits, or underscores. |
| 27 | Each location tag is really a collection of six values, |
| 28 | namely the north, south, east, |
| 29 | west, x, and y values of the tagged object. These are referenced by giving |
| 30 | the tag name followed by a dot, followed by the letter n, s, e, w, x, or y. |
| 31 | For example: |
| 32 | <BR><PRE> |
| 33 | c.n // north of tag c |
| 34 | _xyz.e // east of tag _xyz |
| 35 | x.x // x coordinate of tag x |
| 36 | </PRE><BR> |
| 37 | </P> |
| 38 | <P> |
| 39 | The n, s, e, and w values describe the smallest rectangle that will |
| 40 | completely enclose the object being tagged. |
| 41 | The north refers to the top of the object, the south to the bottom, the |
| 42 | west to the left edge, and the east the right edge. The x and y values |
| 43 | correspond to the "center" coordinate of the object. This is not necessarily |
| 44 | the geometric center, but more of a "logical center." In the case of a tag |
| 45 | associated with an individual note, it is the geometric center of the note head. |
| 46 | However, on tags associated with a chord, the x is at the center line of |
| 47 | note heads that are on the "normal" side of the stem. (Normally, when a stem |
| 48 | is up, notes are put on the left side of the stem, and when the stem is |
| 49 | down they are placed on the right side. However, when two notes adjacent |
| 50 | on the staff have to be printed in a single chord, one has to be moved to the |
| 51 | opposite side.) The y of a chord is always the middle line of the staff |
| 52 | containing the chord. The x of a bar line is its geometric center. The y |
| 53 | of a bar line is the center line of the top visible staff. |
| 54 | </P> |
| 55 | <P> |
| 56 | Tag names can be re-used. The value of a tag will always be its most |
| 57 | recent definition. |
| 58 | </P> |
| 59 | <P> |
| 60 | There are also several "pre-defined" tags. They are: |
| 61 | <DL> |
| 62 | <DT> |
| 63 | _page |
| 64 | <DD> |
| 65 | the entire page |
| 66 | <DT> |
| 67 | _win |
| 68 | <DD> |
| 69 | the available part of the page |
| 70 | <DT> |
| 71 | _cur |
| 72 | <DD> |
| 73 | the current location |
| 74 | </DL> |
| 75 | </P> |
| 76 | <P> |
| 77 | The _page tag refers to the entire page. |
| 78 | The x and y values of _page are at the geometric center of the page. |
| 79 | This tag is |
| 80 | seldom useful, but is provided in case you want to force something to |
| 81 | a specific place on a page. |
| 82 | </P> |
| 83 | <P> |
| 84 | <A NAME="wintag">The _win tag</A> |
| 85 | refers to the area of the page available for printing. |
| 86 | The name comes from the idea that it provides a view, as if through a window, |
| 87 | of a portion of the page. Its precise meaning depends upon the current |
| 88 | context. |
| 89 | In header, footer, top, bottom, |
| 90 | header2, footer2, top2, bottom2, and block contexts, |
| 91 | it refers to the area of the |
| 92 | page taken up by the corresponding element. In music context, it refers |
| 93 | to the area of the page that remains after excluding the margins and the |
| 94 | header, footer, top and bottom for the page. |
| 95 | There is no way to access location tags in any other |
| 96 | contexts, so _win (and all other location tags) |
| 97 | are meaningless in other contexts. |
| 98 | </P> |
| 99 | <P> |
| 100 | The _cur tag refers to the current location on the page. This is a single |
| 101 | point, such that east and west values are the same as x, and north and |
| 102 | south values are the same as y. It is only useful immediately |
| 103 | after a command that explicitly sets the current location, that is, after |
| 104 | a printing command or line or curve command. Since Mup places musical |
| 105 | data in an arbitrary order, trying to use _cur at other times is likely |
| 106 | to cause output at a seemingly random place. |
| 107 | </P> |
| 108 | <P> |
| 109 | Location tags can be referenced by a number of commands, including those |
| 110 | for |
| 111 | <A HREF="prnttext.html">printing text,</A> |
| 112 | or |
| 113 | <A HREF="linecurv.html">drawing lines or curves.</A> |
| 114 | In the simplest case, two |
| 115 | tag references are given in parentheses. The first tag |
| 116 | must refer to a horizontal direction (the "x" direction for mathematicians), |
| 117 | namely a tag with a w, e, or x after the dot. The second tag is then a |
| 118 | vertical tag, having n, s, or y. For example: |
| 119 | <BR><PRE> |
| 120 | (g.x, g.y) // x and y of tag "g" |
| 121 | (_tag.w, _item.n) // west of tag "_tag" and |
| 122 | // north of tag "_item" |
| 123 | </PRE><BR> |
| 124 | The first example refers to the x,y coordinate of tag "g". The second item |
| 125 | refers to two different tags. The point referenced has its horizontal |
| 126 | location aligned with |
| 127 | the west side of the object having the tag "_tag," while its vertical |
| 128 | position is in line with the north side of the object having the tag "_item". |
| 129 | In other words, if a line were drawn along the west side of the object |
| 130 | tagged with "_tag" and another line were drawn along the top edge of the |
| 131 | object with tag "_item", the point where those two lines crossed would be |
| 132 | the point referenced. |
| 133 | </P> |
| 134 | <P> |
| 135 | Frequently, you may want to place something relative to a tagged object. |
| 136 | You can add offsets in both the x and y dimensions. These offsets are given |
| 137 | in stepsizes. |
| 138 | As was mentioned earlier, a stepsize is half the distance between two staff |
| 139 | lines. |
| 140 | <BR><PRE> |
| 141 | (g.x + 4.5, g.y + 4.5) |
| 142 | </PRE><BR> |
| 143 | refers to the point 4.5 stepsizes to the right and above the point (g.x, g.y). |
| 144 | Adding an offset moves to the right in the horizontal direction and |
| 145 | upward in the vertical direction. You can also subtract an offset: |
| 146 | <BR><PRE> |
| 147 | (k.w - 1.3, m.n - 2) |
| 148 | </PRE><BR> |
| 149 | refers to a point 1.3 stepsizes to the left of the |
| 150 | west edge of k and 2 stepsizes below the top of m. |
| 151 | </P> |
| 152 | <P> |
| 153 | In the horizontal direction, offsets can be given in terms of "time". This |
| 154 | is specified by using the keyword "time" followed by a number of beats. |
| 155 | As an example, suppose we have the tag reference: |
| 156 | <BR><PRE> |
| 157 | (q.x + time 1, q.y + 2) |
| 158 | </PRE><BR> |
| 159 | If the |
| 160 | <A HREF="param.html#time">time signature</A> |
| 161 | is 4/4 and tag "q" happens |
| 162 | to be associated with a half note, this tag reference |
| 163 | would refer to a point halfway between that note and the following chord, |
| 164 | since it includes an offset of a quarter note. If "q" had been associated |
| 165 | with a whole note, the point would be only 1/4 of the way between the |
| 166 | note and the following chord. Since notes are placed based on various |
| 167 | constraints and aesthetic considerations, the actual distance will vary |
| 168 | depending on which tag is referenced. |
| 169 | </P> |
| 170 | <P> |
| 171 | In the case of a |
| 172 | <A HREF="bars.html#btag">tag associated with a bar line,</A> |
| 173 | the time to distance mapping |
| 174 | is done based on the distance between the bar (at count "0") and the first |
| 175 | chord in the measure (at count "1"). So, for example, in 4/4 time, a reference |
| 176 | to a bar line tag + time 0.5 would indicate a place halfway between the bar |
| 177 | line and the first chord, whereas tag + time 0.25 would be one fourth of the |
| 178 | way. |
| 179 | </P> |
| 180 | <P> |
| 181 | The mapping of time to distance is done based only on the note, rest, or bar |
| 182 | line associated with the tag. For example, if the tag is associated with a |
| 183 | quarter note, and the distance between that note and the next was 0.5 inches, |
| 184 | specifying "+ time 2" (a half note) would mean 1.0 inch to the right, or |
| 185 | specifying "- time 2" would mean 1.0 inch to the left, even if the notes to |
| 186 | the left or right happened to be spread somewhat differently than 0.5 inches |
| 187 | per quarter note. Thus it is usually advisable not to specify a time offset |
| 188 | greater than the time value of the note or rest associated with the tag, |
| 189 | nor to subtract a time value. Stated another way, when specifying the X |
| 190 | portion of a coordinate using a time offset, it is best to use a location tag |
| 191 | based on whichever note, rest, or bar is immediately to the left of the |
| 192 | X location you are trying to specify. |
| 193 | </P> |
| 194 | <P> |
| 195 | The various kinds of offsets can be combined. |
| 196 | <BR><PRE> |
| 197 | ( _pp + 1.2 - time 3.5, _zz + 2) |
| 198 | </PRE><BR> |
| 199 | </P> |
| 200 | <P> |
| 201 | At least one of the three possible items--tag, stepsize offset, or |
| 202 | time offset--must be specified for each direction. Only one |
| 203 | tag is allowed for each direction. If no tag is specified, the reference |
| 204 | becomes an absolute reference, giving an exact page location. For example: |
| 205 | <BR><PRE> |
| 206 | (10, 20) |
| 207 | </PRE><BR> |
| 208 | is 10 stepsizes from the left edge and 20 stepsizes |
| 209 | above the bottom of the page. |
| 210 | Time offsets are not allowed on absolute references, and must follow the tag |
| 211 | reference. |
| 212 | </P> |
| 213 | <P> |
| 214 | It is possible to specify multiple offsets of the same type, although |
| 215 | this is rarely, if ever, useful. Thus the following are equivalent: |
| 216 | <BR><PRE> |
| 217 | ( f.x + 1 - 0.5 + time 1 - time 0.5, f.s + .3 - .1) |
| 218 | ( f.x + 0.5 + time 0.5, f.s + .2) |
| 219 | </PRE><BR> |
| 220 | </P> |
| 221 | <HR><P> |
| 222 | <A HREF="roll.html"><-- previous page</A> <A HREF="index.html">Table of Contents</A> <A HREF="prnttext.html">next page --></A> |
| 223 | </P> |
| 224 | </BODY></HTML> |