Graph Widgets
Graph Widgets are used to display a collection of dynamically changing numerical data in a graphical form, like a bar graph, line graph, surface graph and others. Graph Widgets are animated in the same way as any other GLG drawing, by manipulating its resources.
Most of the graphs are available in both 2D and 3D versions. Some of them, like the surface graph, have only a three-dimensional version. For any graph, the 2D version is faster, takes less memory and intended for use with larger sets of data. The 3D version takes more memory and is slower, but in return it allows you to examine data in 3D space. For example, you can place several data sets in rows or look at them from different angles.
The graphs of the GLG Widget Library are all constructed using similar elements to represent graph components such as axes, ticks, labels, and data. A typical graph has a frame, data area, axes, grids, titles, minor and major ticks, major tick labels for each axis, a data group containing graph data samples, a group of level lines and a status object. See the figure below.
Components of a Graph
For convenience, these elements have identical names in all graphs, although some names may have added suffixes for certain cases. This means that editing any particular element is similar for all graphs.
The widgets in the GLG Widget Library are intended for use as templates. They may be used as they are, or easily edited with the GLG Graphics Builder to produce customized versions.
Naming Conventions
The names of resources play an important role since they are used to access objects inside a widget. There are a few naming conventions used for the Graph Widget components:
The names of the elements associated with an axis start with the name of the axis, like XLabel .
The name of a template of a series object does not have any numerical suffix, like DataGroup .
The names of the created instances of the template in a series object have a numerical suffix corresponding to the sequential number of the instance, like DataGroup3 . As with all GLG indexes, the index is based at zero, so DataGroup3 is actually the fourth object in a series.
In the case of nested groups or series objects, the names of outer objects are formed by adding a numerical suffix to the name of the bottom level composite object. This suffix indicates the level of the hierarchy and is spelled out as a word. For example, if there are two levels of series objects and the name of the inner series is DataGroup , the name of the outer series is DataGroupOne . If that series were itself the template for a third series, that third level would be called DataGroupTwo , and so on. Since the inner series is used as a template by the outer series, there are also copies of the DataGroup template in the DataGroupOne series. The final hierarchy and the corresponding names look like this:
DataGroupOne (series of series) DataGroup (template) DataGroup0 (copy) DataGroup1 (copy) ...Optimization
The update speed of a graph depends on the number and type of objects rendered on every update iteration. Deleting auxiliary elements of a graph such as grids, levels, a data area and a status object can substantially increase the update speed.
In a simple graph, the tick and label elements may easily be responsible for two- thirds of the memory consumed by the graph. If you have large sets of data, you may delete unnecessary elements or decrease major and minor ticks factors to minimize the number of objects in the graph. This reduces the amount of memory used by the graph and increases its update speed.
In the case of a graph with a large number of data samples, you can also reduce the computing demands made by reducing the number of times you update the graph. Instead of updating the graph each time a new data point is written, you can try updating after each second or third or more point is written.
Data Samples and the Data Group
Data samples are objects used by a graph to display its data. The type of object used as a data sample may be different depending on the type of the graph. For example, a data sample in a bar graph is represented by a polygon whose height changes with the value of the data value displayed. For a line graph, the data value is represented by the position (usually just the Y-coordinate) of a point on the line.
The method used to create multiple instances of a data sample object depends on the type of the graph as well. For example, a series object is used to create multiple instances of a data sample object for graphs like a bar chart or a pyramid graph. For a line graph, a polyline object is used, and for a surface graph a polysurface object renders the surface. Whatever the variety of composite object, such a collection of data samples is called a data group , and these are identified with the DataGroup resource.
If a series object is used to produce multiple copies of data samples, a template of the series object is usually named DataSample. The names of the created copies are formed by adding a consecutive digital index of the copy to the name of the template: DataSample0, DataSample1, and so on.
The type of object used as a data sample depends on the type of the graph. However, there are three resources present no matter the type of object. These are:
Value
The value to be represented by the data sample object. Changes made to this resource are not permanent, and will revert to an initial value when the graph is reset. To make Value resource changes permanent, explode the DataGroup object with the GLG Graphics Builder. The value of this resource for the template object is the initial value of the series members. The graph always works in a linear coordinate system. If data has to be displayed in the logarithmic format, it must be converted to the logarithmic scale before setting the Value resource.
Low and High
These resources define the range of data displayed by the graph. Data sample shapes that extend beyond these limits may be clipped. The default values are 0 and 1, respectively. These resources may be changed dynamically without losing data currently displayed in a graph. In this case the graphical attributes of data samples are automatically recalculated to display current data in the new range. This allows the application program to change the range of the data when the amplitude of the data increases (or decreases) beyond the current graph's data range. It also allows the program to scale data samples when the values get too small.
Whether part of a series or a polyline, or some other composite object, the data sample objects displayed in a typical graph are dynamically created objects whose attributes are inherited from some template object. As with any series object, changes to the template instances are not permanent, and last only until the drawing is reset or reloaded. However, you can use the GLG Graphics Builder to explode a datagroup object. This will turn a series of dynamically created objects into a group of static objects. The attributes of the static objects may then be edited, and these changes will be permanent.
Constrained Attributes Of Data Samples
In some graphs, some attributes of the data samples are constrained to have values corresponding to the value of the data sample. For example, the fill color of the bars in a bar graph may change according to the height of the bar, so that the bigger the height of the bar, the brighter the color. In this case, the fill color is the subject of a complicated set of constraints, so that directly changing the FillColor attribute does not yield the desired results.
In the graphs where a FillColor attribute is constrained, two resources are provided to define the color range: StartColor and EndColor. Together with the FillColor attribute, they define the range of colors for a data sample object. When the Value of the data sample is at the lower limit of the graph, its color is that specified by StartColor , while it takes the EndColor when the Value resource is at the upper limit of the graph. For values in between the two, the color is derived by linear interpolation between the two extremes.
Note: In order for the results to be intelligible, the StartColor resource should be set to the same value as the FillColor attribute.
If the start and the end colors are of the same hue, dithering patterns are used to provide more colors. This feature may be disabled by setting the number of dithering patterns to 1 for the graph's viewport (use pattern factor equal to 0).
On an 8-bit color machine, the number of color gradations is usually small if the start and end color do not have the same hue. You can, however, change the parameters of a colortable for the viewport to be different from the default one, providing more hues and less shades. This increases the number of color gradations available for coloring the bars.
To disable color constraints, set the StartColor and the EndColor resources to the same color. This prevents color from being dependent on the data sample value and allows colors of the bars to be set directly.
Nested Data Groups
Several kinds of graphs contain data groups whose elements are themselves composite objects. For example, a line graph with multiple lines or a 3D bar graph with several rows of bars. There are also the packed bar graphs that contain several copies of graph "packs," each of which contain several data samples.
Different standards obtain for naming nested data groups, depending on the style of graph in question. The series object used to create multiple copies of data groups in one data area is usually named DataGroupOne and its template is named DataGroup. The produced instances of a data group have names DataGroup0, DataGroup1, and so on.
In some graphs, such as the packed or stacked bar graphs, the first (inner) series object, named Pack , is used to produce the necessary number of bars in one pack. The second series object, named DataGroup , is used to reproduce the desired number of packs in the graph, which are called Pack0 , Pack1 , and so on.
In the case of nested data groups like these, either series object or both of them may be exploded with the GLG Graphics Builder to customize the graph. For example, in a packed bar graph, it may be desirable to have the corresponding bars in every pack identified by a different value of some attribute. Perhaps the first bar of every pack should be yellow, the second one should be green and so on. In order to do this, the Pack series object on the lower level has to be exploded in the Builder.
In this case, choose the desired number of bars in the pack, set the Global attribute of the FillColor attribute of the template bar to LOCAL to allow bars to have different colors in the exploded pack, then explode the Pack series object. Now for every bar in the exploded pack set the Global flag of its FillColor attribute back to GLOBAL and set the attribute to the desired color. (Remember to edit the template pack object rather than the copies.) Since the Global flag of the FillColor attribute of every bar in the pack is set to GLOBAL, the colors of corresponding bars in all packs are constrained to have the same value that you have just defined. If you change the color of one bar, all corresponding bars change.
Data Area
The Data Area is a polygon used as a background for 2D graphs. It allows you to paint the area behind data samples a color different from the background color of the viewport. In 3D versions of the graphs there are several data areas, representing the three planes of the graph's frame.
By selecting the Data Area polygon and editing it you may change its fill color, border color and border width. You may also change the geometry of the whole graph by moving control points of the Data Area. The Data Area is a parallelogram object, and has three control points.
If the Data Area parallelogram is changed to be not rectangular, the graph is distorted accordingly, displaying its samples under the angle defined by the sides of the Data Area. This can be used to create special effects.
Like any parallelogram object, the three unconstrained control points of the Data Area may be named and then accessed as resources. This gives you the ability to change the geometry of the graph dynamically from a program. Changing the geometry does not destroy data currently displayed in the graph.
Axes
An axis of a graph is just a polygon. Axes are named by the corresponding coordinate: XAxis, YAxis and ZAxis (for 3D graphs).
Some graphs, like a line graph with multiple variables, may have multiple vertical axes. In this case, an axis with a set of labels and ticks are kept in the group named YAxisGroup. This group is used as a template in the series object named YAxisGroupOne, which contains multiple copies of the axis group, called YAxisGroup0, YAxisGroup1, and so on.
To change the number of axes, change the value of the Factor attribute of the YAxisGroupOne series object. To edit attributes of all axes, edit the YAxisGroup template.
Major And Minor Ticks
A major tick is represented by a polygon object named XMajorTick for an X axis. Major ticks for Y and Z axes are named YMajorTick or ZMajorTick. Everything described below in this chapter for the X axis ticks is also applicable to the ticks on Y and Z axes.
The XMajorTick polygon is used as a template for the XMajorGroup series object to produce multiple copies of a major tick. The number of ticks is defined by the factor of the series object, and their appearance is defined by the series object template.
A minor tick is represented by a polygon named XMinorTick. The graphs use two nested series objects to produce all the minor ticks on an axis. The inner series object, named XMinorGroup, produces the necessary number of minor ticks between any pair of major ticks. The series object on the second level, named XMinorGroupOne, is used to reproduce that interval between all pairs of major ticks.
To change the number of minor ticks per major tick, change the factor of the XMinorGroup series object on the lower level. The factor of the outer XMinorGroupOne series is constrained to have the same value as the factor attribute of the major tick series.
For convenience, the factor attribute of the XMinorGroup object is also constrained to the MinorFactor resource of the major tick series.
The factor attributes of the grid and axis label series are constrained to have the same value as the factor of the major tick series. The number of data samples in the graph is not so constrained.
Optimization
Since ticks are an expensive resource, keep number of them at a necessary minimum. In general, the total number of X minor ticks should be smaller or equal to the number of data samples in the graph. In any case, the total number of minor ticks should be a factor of the number of the graph's data samples, otherwise data samples and minor ticks are misaligned. The same is true for the major ticks as well.
Logarithmic Ticks
Ticks can be displayed on a logarithmic scale if you want to display logarithmic data. In this case only minor ticks are drawn with uneven intervals. Major ticks are still drawn evenly, since they correspond to the integer powers of the logarithm base. It is the responsibility of the program or the process supplying data to provide logarithmic data sample values.
To make minor ticks logarithmic, set the LogType attribute of the lower level series object of Y minor ticks (YMinorGroup) to LOG. The factor of this series should be set to a value of the base of the logarithm minus 1. For example, for the logarithm base ten, the factor should be set to nine.
Grid Lines
The background grid lines in a GLG Graph are rendered as polygons named XGrid and YGrid. Series objects named XGridGroup and YGridGroup are used to produce the necessary number of grid lines. The factors of the series objects are constrained to have the same value as the number of major ticks on the corresponding axis.
Labels
Axis labels to be displayed at each major tick are represented by text objects named XLabel, YLabel and ZLabel. These text objects are used as templates for the series objects named XLabelGroup, YLabelGroup and ZLabelGroup, which produce the desired number of labels for the corresponding axis. Each label is positioned at the corresponding major tick. The values of the Factor attribute of each label series are constrained to have the same value as the number of major ticks on the corresponding axis. As with any other series, every individual label may be accessed with the index of the label as a suffix. For example, XLabelGroup/XLabel3 accesses the fourth label on the X axis (since the index is zero-based). The changes to the attributes of individual labels are volatile and disappear after resetting or reloading the drawing. To assign custom text strings to the labels permanently, the label series object can be exploded with the GLG Graphics Builder.
The font for a label can be changed by editing the series Font attribute in the same way as any other attribute. Changes to the series template will change the font used to display all the labels in the series, while changes to the attribute for any particular instance of the series template will affect only that copy.
If the type of the text object template for a label series is SCALED, the Global flag of the SizeConstraint attribute of the template text object controls whether or not all axis labels are displayed in one font size when labels have different length.
If the Global flag is set to LOCAL for the template label, label text strings are fitted into their boxes individually and may be displayed in different font sizes if labels have different length. If the flag is set to GLOBAL, fitting the text of one label into the corresponding box affects all other labels. It means that if the text of a label does not fit into its box, a font of the smaller size is chosen for that label. This change of a font size affects all labels on the axis, so that all of them are displayed in this smaller font size. After the conditions that caused the change of the labels' font size are eliminated, the labels stay in their current small font size until the viewport is resized or reset.
Constrained Labels and the Format Resource
Some labels, like those on the value axis (the Y axis for most of the graphs), are constrained to the values associated with the corresponding major ticks. The strings for the labels are supplied automatically depending on the graph's data range and the factor of major ticks.
For example, if the data range of the graph is [0,1] and the graph has six major ticks (the factor of major ticks is 5), then the strings displayed in the labels are"0.0", "0.2", "0.4", "0.6", "0.8" and "1.0".
The text string of a constrained label is not controlled with the TextString attribute, but with the text object's Format resource. Changing the TextString attribute of such a label does not affect the string displayed, since it is constrained. The Format resource defines a C-style format used to display a label's data value. The format string should have no more than one conversion specification requiring an argument. This conversion specification should take a double-precision value as an argument, therefore only f, g and e format specifications are allowed. The conversion specification is optional, and may be omitted, allowing you to use the Format resource to replace the label string.
For example, to specify that all labels in the label series show two digits of precision, change the Format resource of the series template to " %.2f ". The Format resource is a character string where the `%' character has a special meaning, so you may also set it to strings like " Value=%.2f ". In this case, the " %.2f " will be replaced with the label value when the label is displayed. You can omit the conversion specification entirely, so that changing the label's format string to "Level 1" simply displays "Level 1" in the label. If you want to display a "%" character in the string, use "%%" in its place. Refer to any C compiler documentation for a complete explanation of string formatting capabilities.
If you want to disable automatic labelling, make sure that the value of the Global flag of the Format resource of the template label is set to LOCAL. You may also have to use the GLG Graphics Builder to explode the label series to avoid having the changes discarded by the next drawing reset.
Attention: Be careful defining C format for the format string. The GLG Toolkit does not check the format for validity before displaying a drawing. Any entry is treated as a valid C format, in exactly the same way as any C program does. Defining the wrong format may cause unpredictable results.
Every constrained label has resources named Low and High that define the range used for labeling. These resources are constrained to have the same values as the low and high range resources of the graph. Changing these resources affects both the labeling range and the data range of the graph, rescaling currently displayed data and setting new label strings.
Scrolled And Wrapped Labels
While labels on a GLG Graph Widget's value axis are constrained, the labels on the time axis (X axis for most of the graphs) are not constrained. For most of the graphs, the XLabelGroup series is equipped with an entry point for convenience in setting graph labels. There are two methods of supplying strings for updating time axis labels.
The first method is to set the String attribute of the label directly using the name of the label text object. For example, XLabelGroup/XLabel3/String would be the resource name used to access the string of the fourth label on the X axis. Although straightforward, this method requires the application program to keep track of the current update position and to update labels differently depending on the scrolling behavior of the graph.
The second method is to use the EntryPoint resource of the label group. This method allows you to supply label strings without defining where to place them. This keeps the labels synchronous with the corresponding data samples.
The XLabelGroup/EntryPoint resource is used for updating X axis labels. Setting this resource to different values in a loop animates the X axis labels according to the graph scrolling behavior. Querying the value of the resource yields the last string used for updating.
The number of elements in a label series is constrained to be equal to the product of the number of major ticks on the axis and the number of minor ticks between a pair of major ticks. This is useful for applications that require the axis labels to scroll with the data sample values. This presents a problem because convention has it that labels are generally only displayed next to the major ticks.
GLG accommodates this convention by not displaying the label values that correspond to axis minor ticks. This means that if there is one minor tick between each pair of major ticks on an axis, only the odd-numbered labels are actually displayed. (If the axis does not have minor ticks or they were deleted, the MinorFactor resource of the major tick or label series defines the missing minor factor.) In general, if there are several minor ticks per one major tick (the minor tick factor of the axis is bigger than 1), then only every nth supplied value for the label is visible, where n is the factor of minor ticks. If this factor is equal to 1, then all supplied label values are visible.
The label series scrolling behavior is defined by the ScrollType resource of the XLabelGroup object and may have values SCROLLED or WRAPPED. If it is SCROLLED, all labels shift when updated and the new label appears at the entry point. If it is WRAPPED, only one label changes on every update, shifting the next update position to the next label in the series.
The ScrollType resource of labels is constrained to have the same value as the ScrollType resource of the DataGroup object of the graph. This ensures that the scrolling behavior of the labels is consistent with the scrolling behavior of the graph.
The Inversed resource of the XlabelGroup series controls the direction of scrolling. Setting this resource to YES reverses scrolling direction. Since this resource is constrained to the corresponding resource of the DataGroup object, changing the resource reverses the scrolling direction of the data samples as well as labels.
To use label entry points in a graph, refer to Graphs with Multiple Entry Points, below.
Graphs with Multiple Entry Points
While it is convenient to use series entry points to control multiple series in a graph, GLG contains no mechanism for synchronizing the data entered at two different entry points. This means that if your application requires labels that march along with the data entered from some external source, you must find some way to ensure that the right label is displayed with the right data value.
Axis Labels
Consider a simple bar graph where there is a minor tick on the X axis for each bar in the graph. To operate this graph properly, you must supply two pieces of data for every update iteration: the scalar value to be displayed and the character string with which to label it. The scalar value is used to set the DataGroup/EntryPoint resource, and the string is used to set the XLabelGroup/EntryPoint resource.
For this graph, the number of labels in the series is constrained to equal the number of minor ticks, which, for this example, happens to equal the number of data samples in the graph. Only the labels corresponding to the major ticks on the axis are actually displayed, however. The unseen labels cause the label values to shift if they are scrolled, or shift the update position without any visual change if labels are wrapped.
For scrolled graphs, the total number of minor ticks (the minor tick factor times the major tick factor) should be equal to the number of data samples. For wrapped graphs, the total number of minor ticks may be smaller than the number of data samples, but the total number of minor ticks should be an integer factor of the number of data samples in order for the graph's elements to be properly aligned. In this case, a value for the entry point of wrapped labels should be supplied only every nth update, where n is the number of data samples divided by the total number of minor ticks.
For example, if a graph has 100 data samples, 5 major ticks and 10 minor ticks per major tick on X axis, the total number of minor ticks is 50. The number of minor ticks is therefore half the number of data samples. Therefore a value for the label strings should be supplied for every other data sample.
This means that the sequence of the supplied data for the graph should look like:
data sample value, data sample value, label string value, data sample value, data sample value, label string value, data sample value, data sample value, label string value,If the axis does not have minor ticks or they were deleted, the MinorFactor resource of the major ticks' or labels' series defines the missing minor factor.
Nested Data Groups
There are also cases where a single tick on an axis might correspond to more than one data sample. For example, a graph may have multiple data groups, like a line graph with multiple lines or a 3D bar graph with several rows of bars. The total number of data samples for such a graph is equal to the number of data samples in one data group multiplied by the number of data groups.
Another example is a packed or stacked bar graph, where one pack may contain several data samples. In these graphs, one minor tick corresponds to several data samples of one pack, and the total number of data samples is equal to the number of packs multiplied by the number of bars in one pack.
Again, because GLG provides no general mechanism to synchronize two series values, you must be careful to provide synchronized data to the Graph Widget. That is to say, for graphs like these, the values for the corresponding data samples of all lines or all bars of one pack should be supplied during one update iteration, otherwise lines or packs will be out of sync.
Level Objects
In addition to grids, many of the GLG graphs have level objects . These are horizontal lines usually used to mark some special thresholds in the graph. While grid lines are always positioned automatically on the levels defined by the major ticks, level objects may be positioned arbitrarily.
A level object is represented by a polygon named LevelObject and placed inside a LevelObjectGroup series object to produce several copies of the level object. A factor of this series defines the number of level objects created. Each level object has a Value resource, controlling its position, or level.
Attributes of polygons representing every level line may be changed to distinguish different levels. As with all series, the Global flags of attributes to be changed must be set to LOCAL, otherwise all level objects are affected. The level's series object may be exploded with the GLG Graphics Builder to make the changes permanent.
Remember to delete level objects in the customized version of the graph if they are not used.
Status Object
Several graphs have a status object , indicated with the StatusObject resource. This object is used only for graphs with the WRAPPED scrolling type. It is a graphical shape, used to indicate the position of the last updated data sample. It moves after every update to the next data sample, wrapping back to the starting position after reaching the last one. The status object may be any graphical object. The object's local origin is aligned with the point on the axis corresponding to the data sample.
A status object may be deleted if not used. When a graph is just loaded or after a reset, the position of the status object coincides with the Y axis (or with the X axis for graphs with vertical scrolling).
Titles
A few freely positioned titles are used to annotate a graph and its axes. The X and Y axis titles are named XAxisLabel and YAxisLabel , respectively. The graph's title text object is named Title . A title's position, as well as direction, text string, and other attributes may be changed by moving control points or editing attributes of the text object indicated by the resource name. An unlimited number of additional titles may be created in the GLG Graphics Builder by creating new text objects and positioning them.
Optional Legends
The GLG Graph Widget set contains a set of optional legends that can be used to annotate graphs with multiple data sets, such as a line graph with multiple lines. Every legend item shows the name of the entity displayed by the corresponding data set and also the color or line attributes used to annotate it.
A legend consist of a series object named LegendGroup used to create multiple copies of a legend template. The legend template is made of a group named Legend . It contains a text object named LegendLabel and two polygons named LegendBox and LegendLine . Two marker objects named LegendMarker1 and LegendMarker2 are constrained to the ends of the LegendLine polygon.
The text object is used to name entities in the graph. The polygons are used to display the color, line width or line type associated with a particular entity. Choose which polygon, a box or a line, you want to use and delete the other one from the template.
To change attributes of the individual legend elements to correspond to the entities displayed in the graph, the legend series object has to be exploded with the GLG Graphics Builder. Before exploding, set the number of legend elements and make sure the Global attribute is set to LOCAL for the attributes that are changed individually.
If you plan to change the number of legend elements dynamically from the program, don't explode the legend series. In this case the changes made to individual legend elements are not permanent, but the increased flexibility may be worth the extra trouble.
Some graphs have preinstalled legends. The number of legend elements in the preinstalled legend is constrained to the number of the data sets in the graph. These legends may be deleted if desired.
The legend object is kept in its own file called legend1.g . The legend viewport can be loaded into an existing graph using the GLG Graphics Builder. (When loading, make sure the viewport is loaded into the graph's viewport, not into the Drawing Area's viewport.) For convenience, the legend is placed in a viewport. This is not essential to the operation of the legend, and if you do not want to use the viewport, you may cut out the legend series object and paste it directly into the graph without a viewport, deleting the viewport afterwards.
3D viewing
3D Graph Widgets have a few resources designed to control the user's view of the graph in 3D space:
ShearFactor, ShearX, ShearY
Controls a shear transformation that may be applied to the whole drawing. The ShearFactor defines the degree of shear, and is meant to take values between 0 and 1 (although other values may be used for special effects). The ShearX and ShearY attributes determine the proportion of the shear in the X and Y direction. These two attributes should add to 1.
To obtain the best effect, use either a rotate or shear transformation but not both, since they may interfere with each other. Most of the 3D graphs use the Shear viewing transformation by default. If you must add a rotation transformation to these graphs, make sure to start from the main view if you are using the Builder.