Chart attributes control the visual style of charts, ranging from truly significant decisions like what is the chart type to much smaller (but still important) details like what is the distance between axis labels and title. This chapter introduces what kind of style attributes Davisor Chart supports, how do they behave, and how can you find the right attributes that do what you want to do.
To give you some feeling of what to expect, the following example shows what kind of rich details chart styles are made of. This example does not represent all attributes there are, but it shows a good and wide enough a set to get you started. To see what attributes control what area in the example, follow the capital letter hyperlinks A-X at the bottom of the image. To see the corresponding XML listing that shows all the attributes (and data) used in this example, hit the button, and to play around with the chart youself, try the buttom. Once satisfied, come back here to learn more about the general principles controlling Davisor Chart attributes.
|
|
| A B C D E F G H I J K L M N O P Q R S T U V W X |
Controlling chart visual style is easy, although the number of controllable style attributes may seem a little overhelming at first. In order to maintain control over all these attributes, the following important design principles ensure that chart style control remains simple and convenient while at the same time it is accurate and powerfull enought to create exactly the like of charts you want. In particular, these principles are:
All attributes have sensible default values, so it is not necessary to set any particular attribute values in order to create a chart from any given data. Instead, you may start from a very simple or even non-existent attribute set, and gradually fine-tune the style definition for those details only that you think need adjusting. To prove this, here is the same example as above, but now with only a minimal attribute set that defines only that we would still like to create a combo chart.
|
| Default attributes only. |
When an attribute value is not explicitly set, the attribute willgain a default value which may be one of:
A fixed default attribute value explicitly defines what attribute value should be used if that attribute value is not otherwise specified. For example, enclose attribute default value is true, so all symbols drawn on plot area are clipped against plotting area bounds by default.
If an attribute value is not explictly set and it instead gains a null default value, this indicates that the corresponding item the attribute controls shoud not appear in or otherwise affect the chart at all. For example, axis title text default value is null, and therefore axes will not have any title text unless explicitly given one.
An attribute value may also default to the value of another attribute. In this case the first attribute is said to inherit the value of the second attribute. The value of this second attribute may then be an explictly defined value, or yet another default value. In particular, if it is a default value, it may again be a fixed, null, or yet another inherited value. Several different attributes may then form a chain of default values, along which attribute values are then searched for until the first explicit or fixed value is found, or the chain ends to a null default value.
Typical examples of default value inheritance chains can be found for example from axis attributes that control the appearance of one chart axis. "Around" these attributes, there is another set of corresponding axes attributes that control the same concepts that the single axis attributes do, but that span their scope over the entire coordinate axis system, now made of one or more individual axes. Each individual axis is now part of an larger axis system, and inside such a system, attributes specified for a certain axis are more specific and therefore more significant for a target axis than attributes given for an entire coordinate axis system as a whole. However, if some axis specific attributes is not set, the corresponding attribute value defaults to corresponding coordinate system wide attribute value, hence creating the start of a default value inheritance chain.
For detailed information about attribute default value preferences and inheritance, please see the XML Reference guide, and in particular the Defaults sections that appear in each XML element attribute documentation. For a good example of a fairly long inheritance chain, see for example axis label color reference documentation.
The meaning of all attributes remain always the same regardless of the surrounding context. In particular, attributes and attribute names that prove to be unnecessary or unsupported in a particular case are never recycled or reused for different purposes. Instead, if an attribute does not for some reason make sense in some circumtances, it's presence and value are simply and silently ignored. For example, pie charts support no axis titles, and therefore they always ignore all axis title attributes. If at the same time the same attribute set would be used to create an area chart (from the same or different data), the axis title text and other title related attributes would be recognized and utilized.
This attribute usage consistence principle means that the entire Davisor Chart attribute set is in fact an union over all the attributes that are required by different chart types. This attribute value consistency principle is important because it makes it possible to create generic chart styles that may be applied to any chart data and type combination, and still always get visually consistent results every time. For details of what chart types support which attributes, please see the XML Reference guide, and in particular the Footnotes sections that appear in each XML element attribute documentation. The general principle is, that all chart types support most of the attributes, but there are some exceptions, and they are all documented in the footnotes.
Chart attributes may be grouped into the following major attributecategories:
The attribute sub-chapters listed above describe the use and significance of the chart attribute groups in more detail. To quickly locate the attribute or attribute group that controls some specific area in a chart image, you may also use the Attribute Map below.
There is also a separate XML Reference document that lists all chart concepts, attributes, and attribute value types as seen from the Davisor Chart XML configuration file point of view. Finally, there is also a API Reference document for Java programmers that describe the underlying object model, tools, attribute values, and types as they are understood from the Java programming interface point of view.
The following chapters decribe in short terms what attribute areas and targets there are in the example chart at the top of this page. For more information about each target and the relevant attributes, follow the corresponding hyperlinks to the XML Reference guide.
An offset between marker and label.
Tag: <axis>
Attributes: markerOffset
A painted area between two markers. The paint is set for the "upper" marker, whose position in this case is "after".
Tag: <marker>
Attributes: position, linePaint
A marker line set for the given position in axis. There may also bea symbol on the axis.
Tag: <marker>
Attributes: position, lineColor, lineStroke, pointColor, pointPaint, pointShape, pointStroke
The plot area appearance is controlled by the three possible axis tags. X-axis controls the "back plane". In isometric "3D" charts the Y-axis controls the left side, and Z-axis sets the "floor" attributes. Area fill paint and border color and style can be set.
Tag: <axis>
Attributes: backColor, backPaint, backStroke
Grid lines and tic marks are per axis. Tic marks are the small symbols on the axis wherefrom grid lines begin. Grid lines can be turned on and off.
Tag: <axis>
Attributes: gridColor, gridLines, gridStroke, ticColor, ticStroke
Value labels are rendered using the given valueFormat, whichmay contain fixed text and macros like "{.value}".
Attributes: valueAlignment, valueColor, valueFont, valueFormat, valuePaint
The border color and style for bars and pie slices can be set using the pointColor attribute, or a special data channel with type "color".
Attributes: pointColor, pointStroke
The fill color for bars and pie slices can be set using the pointPaint attribute, or a special data channel with type "paint".
Attributes: pointPaint
In area, line, and scatter charts, the data points may be represented by symbols. The symbol shape, edge style and color, and fill color can be given. Also the "color" and "paint" channels can be used to set these values.
Attributes: pointColor, pointPaint, pointShape, pointStroke
The appearance of lines in area, line, and scatter charts can be set using lineColor and lineStroke attributes. Also the "color" and "paint" channels can be used to set these values. Note, that if linePaint is given, the area below the line will be painted (area chart).
Attributes: lineColor, lineStroke, linePaint
The outer edge of the chart image can be set using the chart area background color and style.
Tag: <area>
Attributes: backColor, backStroke
Chart background can be defined by attribute backPaint.
Tag: <area>
Attributes: backPaint
Legend will appear into chart image when the <legend> tag is given. It may be positioned into four directions (right, left, up, down) in according to the chart. The border line color and style can be set.
Tag: <legend>
Attributes: legendAlignment, backColor, backStroke
Legend text font and color can be adjusted as well as the gap between the symbols. Other series information is taken from <plot> and <series> tags.
Tag: <legend>
Attributes: gap, labelColor, labelFont
By default the legend background is not filled and the legend entries are just drawn onto the chart background. However, the legend fill color can be set.
Tag: <legend>
Attributes: backPaint
The margins between legend and chart, and between legend and image edges can be defined using the margin attribute or some of its alternatives. The amounts are given in pixels and there is by default a 5 pixels margin between the legend and the chart.
Tag: <legend>
Attributes: margin, marginBottom, marginLeft, marginRight, marginTop
Relative gap between categories given in percents (0-100). Set to category axis.
Tag: <axis>
Attributes: gap
A title for axis given in titleText. Color, font, and rotation can also be controlled. Rotation direction is counter-clockwise, thus use value "-90" to get Y-axis title horizontal.
Tag: <axis>
Attributes: titleAlignment, titleColor, titleFont, titleRotation, titleText
An offset between title and marker labels, or between title and axis labels.
Tag: <axis>
Attributes: titleOffset
Distance between axis line and labels.
Tag: <axis>
Attributes: labelOffset
Label format and outfit may be controlled by label attributes. Labels can also be left hidden by attribute silent.
Tag: <axis>
Attributes: labelAlignment, labelColor, labelFont, labelFormat, labelRotation, silent
Axes series can be controlled like other lines - color and stroke can be set. But also axis position and drawing direction can be set. An axis can be referred using axis dimension index (0,1,2) or name (x,y,z) or logical name (category, value, series). Axis angle can also be set to create isometric or 3D images.
Tag: <axis>
Attributes: angle, axisColor, axisStroke, dim, opposite, position, reversed
The minimum and maximum values and the step for value axis labels can be resolved from the data or they can be set explicitly.
Tag: <axis>
Marker name or label can be given using attribute labelText. If not given, the marker position value is shown in label. By default the marker label is laid along the axis. To get the y-axis marker label aligned horizontally, use rotation value "-90".
Tag: <marker>
Attributes: labelAlignment, labelColor, labelFont, labelPaint, labelRotation, labelText