<-- previous page      Table of Contents    next page -->

Location tags

A location tag is associated with a note, chord, or barline. It can then be referenced in order to place a second object, like a comment or dotted line, relative to the first object.

A tag name can be either a single lower case letter, or an underscore folowed by one or more letters, digits, or underscores. Each location tag is really a collection of six values, namely the north, south, east, west, x, and y values of the tagged object. These are referenced by giving the tag name followed by a dot, followed by the letter n, s, e, w, x, or y. For example: 

c.n	// north of tag c
_xyz.e	// east of tag _xyz
x.x	// x coordinate of tag x

The n, s, e, and w values describe the smallest rectangle that will completely enclose the object being tagged. The north refers to the top of the object, the south to the bottom, the west to the left edge, and the east the right edge. The x and y values correspond to the "center" coordinate of the object. This is not necessarily the geometric center, but more of a "logical center." In the case of a tag associated with an individual note, it is the geometric center of the note head. However, on tags associated with a chord, the x is at the center line of note heads that are on the "normal" side of the stem. (Normally, when a stem is up, notes are put on the left side of the stem, and when the stem is down they are placed on the right side. However, when two notes adjacent on the staff have to be printed in a single chord, one has to be moved to the opposite side.) The y of a chord is always the middle line of the staff containing the chord. The x of a bar line is its geometric center. The y of a bar line is the center line of the top visible staff.

Tag names can be re-used. The value of a tag will always be its most recent definition.

There are also several "pre-defined" tags. They are:

_page
the entire page
_win
the available part of the page
_cur
the current location

The _page tag refers to the entire page. The x and y values of _page are at the geometric center of the page. This tag is seldom useful, but is provided in case you want to force something to a specific place on a page.

The _win tag refers to the area of the page available for printing. The name comes from the idea that it provides a view, as if through a window, of a portion of the page. Its precise meaning depends upon the current context. In header, footer, top, bottom, header2, footer2, top2, bottom2, and block contexts, it refers to the area of the page taken up by the corresponding element. In music context, it refers to the area of the page that remains after excluding the margins and the header, footer, top and bottom for the page. There is no way to access location tags in any other contexts, so _win (and all other location tags) are meaningless in other contexts.

The _cur tag refers to the current location on the page. This is a single point, such that east and west values are the same as x, and north and south values are the same as y. It is only useful immediately after a command that explicitly sets the current location, that is, after a printing command or line or curve command. Since Mup places musical data in an arbitrary order, trying to use _cur at other times is likely to cause output at a seemingly random place.

Location tags can be referenced by a number of commands, including those for printing text, or drawing lines or curves. In the simplest case, two tag references are given in parentheses. The first tag must refer to a horizontal direction (the "x" direction for mathematicians), namely a tag with a w, e, or x after the dot. The second tag is then a vertical tag, having n, s, or y. For example: 

(g.x, g.y)	// x and y of tag "g"
(_tag.w, _item.n)   // west of tag "_tag" and
                   // north of tag "_item"

The first example refers to the x,y coordinate of tag "g". The second item refers to two different tags. The point referenced has its horizontal location aligned with the west side of the object having the tag "_tag," while its vertical position is in line with the north side of the object having the tag "_item". In other words, if a line were drawn along the west side of the object tagged with "_tag" and another line were drawn along the top edge of the object with tag "_item", the point where those two lines crossed would be the point referenced.

Frequently, you may want to place something relative to a tagged object. You can add offsets in both the x and y dimensions. These offsets are given in stepsizes. As was mentioned earlier, a stepsize is half the distance between two staff lines. 

(g.x + 4.5, g.y + 4.5)

refers to the point 4.5 stepsizes to the right and above the point (g.x, g.y). Adding an offset moves to the right in the horizontal direction and upward in the vertical direction. You can also subtract an offset: 
(k.w - 1.3, m.n - 2)

refers to a point 1.3 stepsizes to the left of the west edge of k and 2 stepsizes below the top of m.

In the horizontal direction, offsets can be given in terms of "time". This is specified by using the keyword "time" followed by a number of beats. As an example, suppose we have the tag reference: 

(q.x + time 1, q.y + 2)

If the time signature is 4/4 and tag "q" happens to be associated with a half note, this tag reference would refer to a point halfway between that note and the following chord, since it includes an offset of a quarter note. If "q" had been associated with a whole note, the point would be only 1/4 of the way between the note and the following chord. Since notes are placed based on various constraints and aesthetic considerations, the actual distance will vary depending on which tag is referenced.

In the case of a tag associated with a bar line, the time to distance mapping is done based on the distance between the bar (at count "0") and the first chord in the measure (at count "1"). So, for example, in 4/4 time, a reference to a bar line tag + time 0.5 would indicate a place halfway between the bar line and the first chord, whereas tag + time 0.25 would be one fourth of the way.

The mapping of time to distance is done based only on the note, rest, or bar line associated with the tag. For example, if the tag is associated with a quarter note, and the distance between that note and the next was 0.5 inches, specifying "+ time 2" (a half note) would mean 1.0 inch to the right, or specifying "- time 2" would mean 1.0 inch to the left, even if the notes to the left or right happened to be spread somewhat differently than 0.5 inches per quarter note. Thus it is usually advisable not to specify a time offset greater than the time value of the note or rest associated with the tag, nor to subtract a time value. Stated another way, when specifying the X portion of a coordinate using a time offset, it is best to use a location tag based on whichever note, rest, or bar is immediately to the left of the X location you are trying to specify.

The various kinds of offsets can be combined. 

( _pp + 1.2 - time 3.5, _zz + 2)

At least one of the three possible items--tag, stepsize offset, or time offset--must be specified for each direction. Only one tag is allowed for each direction. If no tag is specified, the reference becomes an absolute reference, giving an exact page location. For example: 

(10, 20)

is 10 stepsizes from the left edge and 20 stepsizes above the bottom of the page. Time offsets are not allowed on absolute references, and must follow the tag reference.

It is possible to specify multiple offsets of the same type, although this is rarely, if ever, useful. Thus the following are equivalent: 

( f.x + 1 - 0.5 + time 1 - time 0.5, f.s + .3 - .1)
( f.x + 0.5 + time 0.5, f.s + .2)

   <-- previous page     Table of Contents    next page -->