Although Multigraph constructs much of a graph automatically, some of the most important aspects of a graph cannot be completely determined automatically. These include things like titles, legends, plot styles, color choices, special annotations, and font sizes. A well-designed graph that easily conveys the intended information to its audience will have a carefully chosen combination of these things that fits the data and the context in which it is being presented. This section describes how to control these aspects of a graph.
Many visual components in Multigraph are positioned relative to something else in the graph. For example, a graph title or legend is typically positioned (centered, left justified, right justified, etc) relative to the entire graph window. A title for an axis is usually positioned relative to the axis, and labels along the axis are positioned relative to the tic marks on the axis. The axes themselves are positioned relative to the plot area. Multigraph uses a common collection of attributes and conventions for relative positioning of various components; this section describes these conventions and attributes.
In the most general case, relative positioning can be thought of as the task of placing a small rectangle, called the "placed rectangle", relative to a large rectangle, called the "base rectangle". (It may help to think in terms of placing the placed rectangle "inside" the base one, but in some cases the placed rectangle will be positioned so that it extends beyond the edges of the base one, or lies outside it completely.) The placed rectangle might represent a legend or a text string, for example, and the base rectangle represents some rectangular region of the graph window --- for example, the plot area where the data is plotted (see Section 4.2, “Borders, Margins, and the Plot Area”). Each of these rectangles has a width and height in pixels, and locations in the rectangle can be specified by giving pixel coordinates. Since it is sometimes awkward to specify locations in pixels, though, Multigraph also makes use of a "relative" coordinate system for each rectangle, in which the lower left corner has the coordinates (-1,-1), and the upper right corner has coordinates (1,1). The center of the rectangle has coordinate (0,0).
The top part of Figure 4.4, “Positioning” shows an example in which the base rectangle is blue and the placed rectangle is green, and the "relative" coordinates of several key points in each rectangle are marked. We want to specify a location of the green rectangle relative to the blue one. We do so by choosing a "base" point in the blue rectangle, and an "anchor" point in the green rectangle. We then position the green rectangle in the blue one so that its anchor point lines up with the base point in the blue rectangle, but possibly offset by a vector which is called the "position", and possibly at a given "angle" to the horizontal. The bottom part of Figure 4.4, “Positioning” shows the result.
In Figure 4.4, “Positioning”, the base point is (1,0) and the anchor point is (1,-1). The base point is specified in the relative coordinates of the base rectangle, and the anchor point is in the relative coordinates of the placed rectangle. The "position" is a vector that indicates an offset of the anchor point away from the base point in the final positioning; it is specified in pixels rather than relative coordinates. In the figure, the position vector looks like it might be something like (-30,-20). The "angle" is specified in degrees, with positive angles pointing counterclockwise, so in the figure the angle appears to be roughly -45.
These four quantities, the base, anchor, position, and angle,
are available for several tags in mugl files using the
base
,
anchor
,
position
,
and
angle
attributes.
Values for the
base
,
anchor
,
and
position
attributes are specified as a pair of numbers separated by a space,
without parentheses. These attributes allow for any arbitrary
positioning of the placed rectangle relative to the base rectangle in a way
that makes many common alignment possibilities easy to specify. For
example, to center a text string (think of the green rectangle as
representing a text string) just under the top edge of the blue rectangle,
use
base="0 1",
anchor="0 1",
position="0 0",
angle="0".
If you want to add a few pixels of vertical space between the top
of the text and the top edge of the blue rectangle, use something
like
position="0 -5",
which shifts the text down by 5 pixels.
To center
a text string just ABOVE the top edge of the blue rectangle, use
base="0 1",
anchor="0 -1",
position="0 0",
angle="0".
To right justify a legend
(now think of the green rectangle as a legend) along the middle of the
right edge of the blue rectangle, use
base="1 0",
anchor="1 0",
position="0 0",
angle="0".
Having the base and anchor points specified in relative coordinates
but the position vector in pixels might seem odd at first, but this
turns out to be a powerful combintation that allows you to specify locations that do not
depend on the exact pixel size of the graph, and that continue to work
correctly if and when the size of the graph is changed. Think of
base
, anchor
,
and
angle as the main way that an object is
positioned, and position
as an offset to allow for
a small amount of padding. Often the amount of padding that looks best
depends on the font size being used, or on the pixel size of an object,
so position
is given in pixels. The
base
and anchor
points, though,
specify relative location and alignment and do not depend on specific pixel
measurements.
Some mugl tags that use these attributes do not allow all of them; for example, the
legend
tag does now allow the
angle
attribute, because legends cannot be rotated (legends are always
displayed with an angle of 0). Most
mugl tags that use these attributes have default values for them, so that you only
need to specify attributes that differ from the defaults. The default values vary depending
on the tag; see the documentation for each tag to find out what its default attribute values are.
In some situations the base point is determined by context and there
is no need (or it doesn't make sense) to think in terms of a base
rectangle. For example, when positioning an axis title, the base
point is the center point of the axis, so the title
subelement of the axis elements takes position
,
anchor
, and angle
attributes
that position the title relative to the axis center point, and the
base
attributes is not needed (or allowed).
There is one more attribute that is sometimes used in connection with positioning.
Some mugl tags accept the frame
attribute as a way of identifying
the base rectangle. It typically takes values like "plot" or "padding", to
indicate that the base rectangle is the plot box or the padding box, respectively; see
Section 4.2, “Borders, Margins, and the Plot Area” for a description of these boxes. In
most cases, though, the base rectangle is determined by the context and there
is no need (or allowance) for a frame
attribute.
In some cases either the base rectangle or the placed rectangle may
actually not be a rectangle, but rather just a line segment.
For example, when specifying the location of an axis relative to
the plot area, the "placed rectangle" is the axis. In cases
such as this, where the placed rectangle is a line (segment), the
anchor
attribute can take a value that is a
single number ranging from -1 to 1 that represents a location along the line segment,
rather than a pair of numbers. Similarly, in cases where the "base
rectangle" is a line segment, such as when positioning an axis
title relative to the axis, the base
attribute
can be a single number between -1 and 1.
The labels
subelement of the
horizontalaxis
and verticalaxis
elements allows you to control how Multigraph places tic marks and
labels along the axis. The location of the label for each tic mark is
determined by the position
,
anchor
, and angle
attributes of
the labels
tag. In terms of the discussion in
Section 4.6.1, “Positioning”, the "small" rectangle that is being positioned
is an imaginary rectangle surrounding the text label, and
the "base" point for each label is the
location of the corresponding tic mark on the axis (the
labels
tag does not take a base
attribute).
Through various combinations of the anchor
,
position
, and angle
attributes
it is possible to position, orient, and justify text in a graph very precisely.
Figure 4.5, “Axis Label Placement Examples” shows several examples. Note that the rectangles drawn around
the text in the figure are shown just for clarity; in a real graph, Multigraph does
not draw these rectangles.
The title
element allows you to add a title, or caption, to a graph. More documentation for this
will be written soon.
The legend
element allows you to control the graph's legend.
More documentation for this
will be written soon.
The grid
element tells Mulitgraph to draw a grid behind the plot.
More documentation for this
will be written soon.
Sometimes it is helpful to add a horizontal line to a graph that appear at a certain place
along the axes but that doesn't correspond to a variable in your data. For example, on a temperature plot
you might want to draw a horizontal line that indicates a freezing point. You can do this
by creating a separate plot
element for the line, and using the
constant
element inside the plot's
verticalaxis
element, instead of the
variable
element. The constant
element takes one attribute,
value
, which is the data value at which the horizontal line should appear.
You can specify styling details for the horizontal line, such as what plot style and colors to use,
in the normal way for all plots as described in Section 4.4, “Plots”, by using the
renderer
subelement.