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.
When a graph has more than one plot, Multigraph automatically adds a legend
in the upper right corner. The legend
tag allows you
to control the legend's appearance. The legend
tag appears at the top
level inside the mugl
tag, and accepts the followng attributes:
visible
This attribute determines whether the legend is present or not; a value of "true" means that the legend should appear, and "false" means that it should not. The default is for the legend to appear if the graph contains more than one plot. You can use this attribute to disable the legend in graphs containing more than one plot, or to enable it in graphs containing only one plot.
anchor
base
position
These attributes give the location of the legend relative to the plot area, according
to the conventions described in Section 4.6.1, “Positioning”. If you think of the
legend as being bounded by an imaginary rectangular box, these attributes determine the
location of that box.
base
is the location of the base point relative to the plot area;
the default value for base
is "1 1" --- i.e. the upper right corner of the plot area.
The default for anchor
is also "1 1", which means that the upper right
corner of the legend is anchored to the base point.
position
is a coordinate pair of pixel offsets, as described in
Section 4.6.1, “Positioning”; its default value is "0 0".
frame
The frame
attribute determines whether the legend is positioned
relative to the plot area or the padding box (described in Section 4.2, “Borders, Margins, and the Plot Area”).
More precisely, it determines the coordinate system of the base
point,
described above.
The default value is "plot", which means that the legend will be positioned relative
to the plot area. This is usually what you want, since the plot area is where the data
is plotted. If you have a graph that has large margins, however, for example to allow
for multiple vertical axes, you can specify "padding" for the frame
attribute, in which case the legend will be positioned relative
to the padding box (which is the entire window minus any border and padding amount).
rows
columns
The legend contains an entry for each plot, layed out in a grid.
The rows
and columns
attributes
determine the number of rows and columns in that grid. If you specify
one of these values and not the other, the other will be determined by
the number of entries in the legend. The default is columns="1"
and rows
unspecified, which means that the legend
will be layed out in a single vertical column, with one row per entry. If you
want a single horizontal legend layout instead, specify
rows="1"
and leave columns
unspecified.
border
The thickness of the border drawn around the legend; the default is "1". Use "0" to turn off the border.
bordercolor
The color of the border; the default is "0x000000", which is black.
color
The color used to fill the background of the legend; the default is "0xFFFFFF", or white.
opacity
The opacity value for the legend, in the range 0.0 to 1.0. This is relevant because depending on where the legend is, it may obscure some parts of the plot data. The default is 1.0, which is completely opaque, which means that any parts of the plot data that appear behind the legend will not be visible at all. any
cornerradius
Determines whether the corners of the legend box, if it is drawn, appear rounded.
If cornerradius
is 0, which is the default, the corners are drawn square.
If cornerradius
> 0, then the corners are rounded off
using circles whose radius is cornerradius
pixels.
padding
An amount of padding, in pixels, to leave between the edges of the legend box and the entries inside it. The default is 0.
The legend
tag can optionally contain an
icon
subtag, which affects the appearance of the individual plot icons
in the legend. The icon
subtag takes the following attributes:
width
height
The width and height, in pixels, of the icons. The defaults are
width="40"
and height="30"
.
border
The thickness of a border drawn around the icons; the default is "1". Use "0" to turn off the icon borders.
In addition to the legend
tag at the top level
of the mugl file, which controls the overall properties of the legend,
each plot can contain its own legend
inside its
plot
section for controlling how that plot's entry
in the legend appears. In this context, the legend
tag takes the following attributes:
visible
Determines whether the plot is listed in the legend at all. The default
behavior is for all plots to have an entry in the legend if the legend is present at
all. To omit a particular plot from the legend, specify
visible="false"
in that plot's legend
tag.
label
The text to be used for the plot's entry in the legend. The default is to use the id of the (first) variable assigned to the plot's vertical axis.
The individual plot entries in the legend are layed out in the order in which
the corresponding
plot
sections appear in the mugl file. To change the order
of the entries in the legend, change the order of the plot
sections.
Below is an example mugl snippet with 4 plots that specifies a legend to be layed out in a single row, centered at the top of the plot area, with no border drawn around either the legend itself or the individual plot icons. One of the plots is omitted from the legend, so the legend will contain 3 columns.
Example 4.3. Example Legend Specification
<?xml version="1.0"?> <mugl> <legend rows="1" base="0 1" anchor="0 1" border="0"> <icon border="0"/> </legend> ... <plot> <legend label="Temperature"/> ... </plot> <plot> <legend label="Precipitation"/> ... </plot> <plot> <legend label="Pressure"/> ... </plot> <plot> <legend visible="false"/> ... </plot> ... </mugl>
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.
By default, Multigraph draws a solid white background behind every graph.
You can specify an alternate background color, and or an image to be used
in the background of a graph, via the background
tag.
The background
tag, if it is present at all, should appear
at the top level of the Mugl file, inside the mugl
tag.
It accepts a single optional attribute:
color
The color to use for the graph background. The default is white ("0xffffff").
The
img
subtag, which may optionally appear inside the
background
tag, can be used to specify an image to
be drawn in the background. It accepts the following attributes:
src
The URL of the image to be used. This URL may be either relative (to the location of the Multigraph SWF file), or absolute. If it is on a different server from the Multigraph SWF file, the normal constraints of Flash security apply (i.e. access must be allowed by a crossdomain file on the server containing the image).
anchor
base
position
These attributes specify where the background image should be drawn in the graph, according
to the conventions described in Section 4.6.1, “Positioning”.
base
is the location of the base point relative to
either the padding box or the plot area (the default is the padding box; see
the
frame
attribute below);
the default value for base
is "-1 -1" --- i.e. the upper left corner.
The default for anchor
is also "-1 -1", which means that the upper left
corner of the image is anchored to the base point.
position
is a coordinate pair of pixel offsets, as described in
Section 4.6.1, “Positioning”; its default value is "0 0".
frame
The frame
attribute determines whether the background image
is positioned relative to the plot area or the padding box (described in Section 4.2, “Borders, Margins, and the Plot Area”).
More precisely, it determines the coordinate system of the base
point,
described above.
The default value is "padding", which means that the background image will be positioned relative
to the padding area (the entire part of the graph that is inside the border).
If you want to position the background image relative to just the plot area, however,
you can specify "plot" for the frame
attribute, in which case the base point will refer to the plot area.