[mup] / mup / docs / uguide / tags.html

<HTML>
<HEAD><TITLE>
Location Tags
</TITLE></HEAD>
<BODY>
<P>
&nbsp;&nbsp;&nbsp;<A HREF="roll.html">&lt;-- previous page</A>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="prnttext.html">next page --&gt;</A>
</P>
         
<H2>
Location tags
</H2>
<P>
A location tag is associated with a
<A HREF="noteattr.html#ntag">note,</A>
<A HREF="chrdattr.html#ctag">chord,</A>
or
<A HREF="bars.html#btag">barline.</A>
It can then be referenced in order to place a second object, like a comment
or dotted line, relative to the first object.
</P>
<P>
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:
<BR><PRE>
c.n	// north of tag c
_xyz.e	// east of tag _xyz
x.x	// x coordinate of tag x
</PRE><BR>
</P>
<P>
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 &quot;center&quot; coordinate of the object. This is not necessarily
the geometric center, but more of a &quot;logical center.&quot; 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 &quot;normal&quot; 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.
</P>
<P>
Tag names can be re-used. The value of a tag will always be its most
recent definition.
</P>
<P>
There are also several &quot;pre-defined&quot; tags. They are:
<DL>
<DT>
_page
<DD>
the entire page
<DT>
_win
<DD>
the available part of the page
<DT>
_cur
<DD>
the current location
</DL>
</P>
<P>
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.
</P>
<P>
<A NAME="wintag">The _win tag</A>
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.
</P>
<P>
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.
</P>
<P>
Location tags can be referenced by a number of commands, including those
for
<A HREF="prnttext.html">printing text,</A>
or
<A HREF="linecurv.html">drawing lines or curves.</A>
In the simplest case, two
tag references are given in parentheses. The first tag
must refer to a horizontal direction (the &quot;x&quot; 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:
<BR><PRE>
(g.x, g.y)	// x and y of tag &quot;g&quot;
(_tag.w, _item.n)   // west of tag &quot;_tag&quot; and
                   // north of tag &quot;_item&quot;
</PRE><BR>
The first example refers to the x,y coordinate of tag &quot;g&quot;. 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 &quot;_tag,&quot; while its vertical
position is in line with the north side of the object having the tag &quot;_item&quot;.
In other words, if a line were drawn along the west side of the object
tagged with &quot;_tag&quot; and another line were drawn along the top edge of the
object with tag &quot;_item&quot;, the point where those two lines crossed would be
the point referenced.
</P>
<P>
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.
<BR><PRE>
(g.x + 4.5, g.y + 4.5)
</PRE><BR>
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:
<BR><PRE>
(k.w - 1.3, m.n - 2)
</PRE><BR>
refers to a point 1.3 stepsizes to the left of the
west edge of k and 2 stepsizes below the top of m.
</P>
<P>
In the horizontal direction, offsets can be given in terms of &quot;time&quot;. This
is specified by using the keyword &quot;time&quot; followed by a number of beats.
As an example, suppose we have the tag reference:
<BR><PRE>
(q.x + time 1, q.y + 2)
</PRE><BR>
If the
<A HREF="param.html#time">time signature</A>
is 4/4 and tag &quot;q&quot; 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 &quot;q&quot; 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.
</P>
<P>
In the case of a
<A HREF="bars.html#btag">tag associated with a bar line,</A>
the time to distance mapping
is done based on the distance between the bar (at count &quot;0&quot;) and the first
chord in the measure (at count &quot;1&quot;). 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.
</P>
<P>
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  &quot;+ time 2&quot; (a half note) would mean 1.0 inch to the right, or
specifying &quot;- time 2&quot; 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.
</P>
<P>
The various kinds of offsets can be combined.
<BR><PRE>
( _pp + 1.2 - time 3.5, _zz + 2)
</PRE><BR>
</P>
<P>
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:
<BR><PRE>
(10, 20)
</PRE><BR>
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.
</P>
<P>
It is possible to specify multiple offsets of the same type, although
this is rarely, if ever, useful. Thus the following are equivalent:
<BR><PRE>
( f.x + 1 - 0.5 + time 1 - time 0.5, f.s + .3 - .1)
( f.x + 0.5 + time 0.5, f.s + .2)
</PRE><BR>
</P>
<HR><P>
&nbsp;&nbsp;&nbsp;<A HREF="roll.html">&lt;-- previous page</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="prnttext.html">next page --&gt;</A>
</P>
</BODY></HTML>
Commit	Line	Data
69695f33 MW	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>