4.6. Styling

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.

4.6.1. Positioning

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).

Figure 4.4. Positioning

Positioning

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.

4.6.2. Axis Label Positioning

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.

Figure 4.5. Axis Label Placement Examples

Axis Label Placement Examples

4.6.3. Graph Titles

The title element allows you to add a title, or caption, to a graph. More documentation for this will be written soon.

4.6.4. Legends

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>


4.6.5. Grids

The grid element tells Mulitgraph to draw a grid behind the plot. More documentation for this will be written soon.

4.6.6. Constant Lines

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.

4.6.7. Background Color or Image

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.