1 Using the GLG Widgets
The GLG Toolkit includes an extensive library of pre-built widgets that may be incorporated into a wide variety of applications. Each widget is a GLG drawing (".g" file) containing a collection of GLG graphical objects that implement the widget's graphical appearance and run-time behavior.
The widgets have no source code associated with them, and their functionality is completely defined in each widget's drawing. Widgets' drawings are cross-platform and may be used by GLG applications on various platforms and programming environments (C/C++, Java, C#/.NET, etc.) with no porting required.
Customizing GLG Widgets
The widgets are highly customizable. A widget drawing may be loaded into the GLG Graphics Builder and edited as any other GLG drawing. The Resource Browser of the Graphics Builder may be used to navigate and modify the widget resources using the Object Resources toolbar button. Unnecessary elements may be deleted and custom annotations and labels may added to the widget. Custom dashboards may be created by combining several widgets into a single drawing, and new custom widget components may be created.
This chapter contains a general description of the categories of the GLG widgets: graphs, meters and dials, input widgets and process control objects, as well as the resource conventions in effect for each of these categories.
Using Widgets in the Graphics Builder
The graphs, dials and other widgets may be loaded into the Graphics Builder by loading corresponding ".g" files, located in the widgets directory. However, the widget palettes are the most convenient way of adding the widgets to a drawing using the drag and drop functionality. To pop up a widget palette, click on the Palettes button of the main menu, then select the desired palette type.
Loading and Adding Widgets to the Drawing
There are two ways to load a widget drawing into the Graphics Builder:
- To add a widget to an existing drawing, simply click on the widget's icon in the palette. The widget will be added at the current location of the editing focus. When creating a panel containing several widgets in a "$Widget" viewport, use the Hierarchy Down button to go into the viewport and then add widgets to it; otherwise, the widgets will added at the top level outside of the viewport. When creating widget panels, individual widgets should be assigned unique names via the Properties dialog.
- To load the whole widget drawing into the Graphics Builder, Ctrl-click (click with the Control key held down) on the widget icon in the palette. This will discard the current drawing and replace it with the drawing of the selected widget. The widget drawing contains the widget, its icon and an animation command for prototyping the widget in the Run mode. The animation command is visible in the drawing as a text object.
Prototyping Widgets Using Predefined Animation Commands
All widgets may be prototyped using the Graphics Builder's Run mode. To start the Run mode, select Run, Start from the main menu or click on the Start toolbar button. This will activate a dialog for entering an animation command.
To simplify the process, all graph and control widget drawings include proper animation commands. To animate a widget with the animation command included in the widget drawing, Ctrl+click on the widget icon in the palette to load the widget's drawing, then start the Run mode and press the OK button in the animation command dialog to start the animation.
The Run mode toolbar provides controls for changing animation speed and pausing the animation. It also displays update performance data, such as updates per seconds and seconds per update.
For control widgets that can be used for both input and output, such as dials, sliders, toggles and other interface widgets, the Run mode may also be used to test the widget's interactive behavior. Press the Pause button in the Run mode toolbar to stop animating the widget with output data and use the mouse to interact with the widget. For example, you can move a dial or slider with the mouse or change the state of a toggle widget.
Prototyping Dials and Meters With Custom Animation Commands
Custom animation commands may be used to animate any dial or meter widget in the drawing. For example, the following command will provide a smooth animation of a dial by using a sinusoidal wave in the 0-100 range as a datasource for the widget's Value resource:$datagen -sin d 0 100 $Widget/Value
$Widget/Value is a resource path for the resource that will be animated.
To enter the animation command, start the Run mode by selecting Run, Start from the main menu or clicking on the Start toolbar button. This will activate a dialog for entering an animation command. Enter the command and press OK to see animation.
If a dial is renamed or placed inside a panel containing several dials, the path may be different from the one used above. For example, the following path will animate a Value resource of a dial named Dial2 placed inside a top level $Widget viewport:
If the resource path is not correct, an error message will be generated. Use the Graphics Builder's Resource Browser (the All Resources toolbar button) to browse the drawing's resources and check the resource path.
To animate more than one dial, use several animation commands in one string. For example, the following command will animate dials in the drawing named Dial1 and Dial2:$datagen -sin d 0 100 Dial1/Value -sin d 0 50 Dial2/Value
Refer to the The datagen utility is embedded into the GLG Builder, which invokes the utility to generate data for prototyping the drawing in the Run mode using the $datagen command in the Run dialog. $datagen instructs the Builder to use an internal version of the datagen utility. on page 350 of the GLG Programming Reference Manual for a complete list of the animation command options.
Prototyping Real-Time Charts with Custom Animation Commands
Real-time charts are animated by supplying data sample values and time stamps into the chart's ValueEntryPoint and TimeEntryPoint. If a time stamp is not supplied, the chart will automatically use current time to generate a time stamp. The following prototyping command may be used for animating a real-time chart with a single plot:$datagen -sin d 1 9 $Widget/Chart/Plots/Plot#0/ValueEntryPoint
A default animation command included in each chart widget's drawing provides a good starting point for experimenting with the chart's options. A modified animation command may be stored in the drawing using the Run, Store Run Command option from the main menu.
Prototyping Graph Widgets with Custom Animation Commands
Prototyping Graph Widgets in the Graphics Builder requires more elaborate prototyping commands that animate both the graph's labels and datasamples. If you want to use a custom animation command for a graph, use a default graph animation command defined in the graph's drawing as a starting point and customize it to explore various graph animation options. The modified animation command may be stored in the drawing using the Run, Store Run Command option from the main menu. The customized drawing may be saved for later reuse or added to the Builder's palettes.
The Store Run Command option stores the current animation command by setting the $DatagenString resource of the drawing, if it is present. In the graph widgets' drawings, a text object at the top of the drawing displays the Run command. The TextString attribute of the text object is named $DatagenString. If a graph widget's drawing was loaded using Ctrl-click on the graph's icon in a palette, the $DatagenString resource is already present in the drawing; if a graph widget was added using a mouse click, the $DatagenString resource may be added to the drawing by placing a text object in the drawing and naming its TextString attribute $DatagenString.
Real-Time Charts and Graph Widgets
Graph and Chart Widgets are used to display a collection of dynamically changing numerical data in a graphical form, such as a bar graph, a line graph, a surface graph and others graphs. The graph widgets are animated in the same way as any other GLG drawings, by setting their resources. Each graph or chart has two types of resources: resources that control its appearance, such as a number of labels or datasamples, and resources for entry points that are used to supply dynamic data for the graph's values and labels.
There are two types of chart and graph widgets:
- Real-Time Chart widgets are optimized for displaying a large number of lines with a huge number of data points. They also provide integrated zooming and scrolling functionality, tooltips and cursor feedback, as well as multiple Y axes, flexible tick labeling and many other features. Both time-based scrolling charts and XY Scatter widgets are provided.
- 2D and 3D graph widgets provide a variety of graph types with presentation features, such as gradient shading or 3D presentation of multiple sets of data.
All real-time chart widgets use the GLG Chart object which implements all real-time and interaction features of each chart. The chart object contains integrated axes, plots, legend and other objects and has a number of attributes that control its behavior.
Refer to Chart Objects of the GLG User's Guide and Builder Reference Manual on page 129 for a detailed description of the chart's attributes and features. Refer to Using GLG Real-Time Charts on page 75 of the GLG Builder and Animation Tutorial for information on editing real-time chart widgets.
In addition to chart properties, a Chart object of every real-time chart widget provides OffsetTop, OffsetBottom, OffsetLeft and OffsetRight resources that control layout of the chart inside the widget.
An application supplies data for a chart using the chart's ValueEntryPoint, TimeEntryPoint and Valid Entry Point described in the Chart Objects. An application can either provide a time stamp for every data sample, or let the chart use current time as a time stamp. The chart automatically positions and scrolls its data samples according to their time stamps. The chart also supports the use of invalid data samples, which are displayed as gaps in the plot lines.
A real-time chart maintains a data buffer of a variable size that keeps data samples accumulated in the chart. Users can zoom and scroll the chart in both vertical and horizontal direction using the chart's integrated zooming and scrolling features. The chart can also be scrolled by simply dragging it with the mouse.
The integrated zooming and scrolling behavior of the chart is controlled by the ZoomMode and the Pan attribute of the chart's parent viewport. Refer to Integrated Zooming and Panning of the GLG User's Guide and Builder Reference Manual on page 53 for more details.
The chart's integrated tooltips and cursor feedback features may be used to display a cross-hair cursor that follows the mouse, as well as display a tooltip showing the information about the data sample located under the current mouse position. The chart object also provides an API for querying chart selection from a program.
To activate the chart's tooltip, the ProcessMouse attribute of the chart's parent viewport must be set to TOOLTIP. This is the default for chart widgets in the Real-Time Charts palette.
2D and 3D Graphs
2D and 3D graphs provide a collection of graph widgets with a variety of graph types, such as bar, pie, polar and other graphs, and with support for gradient and 3D shading.
While the Real-Time Charts are implemented using a single Chart object, the 2D and 3D graphs (including their axes and legends) are constructed using a collection of individual graphical objects, such as polygons, text, series and other objects. This allows for a greater flexibility in modifying their appearance by editing their drawings.
The following chapters describe components and resource hierarchies of the 2D and 3D graph widgets.
The 3D version of graph widgets is optimized for the OpenGL driver by default. It uses alpha-blending and transparency by setting the Visibility attribute of the graph's DataGroup to a fractional value. Set DataGroup/Visibility to 1 when a 3D graph widget is used with a non-OpenGL driver.
Components of a GLG Graphs
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 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, as shown in the picture below.
For convenience, these elements have identical names in all graphs, although some names may have additional suffixes in 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 edited with the GLG Graphics Builder to produce customized versions.
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 (X or Y), such as XLabel or YMajorTick.
- The series object is used to create a variable number of objects in a graph, such as a variable number of datasamples, labels and ticks. The name of the series object ends with the Group suffix, such as DataGroup, XLabelGroup or YMajorGroup for major ticks on the Y axis.
- Each series replicates an object defined as its template. The value of the series' Factor attribute defines the number of the created template copies. For example, DataGroup/Factor defines the number of datasamples in a graph, and XLabelGroup/Factor defines the number of major tick labels. The label and tick series also have the MinorFactor attribute which controls the number of minor ticks, such as XLabelGroup/MinorFactor.
- The name of a template of a series object does not have any numerical suffix, such as DataSample. 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, such as DataSample0, DataSample1, and so on. All indexes are zero based, and DataSample1 is actually the second object in a series.
- Nested series may be used for creating several groups of groups with a variable number of elements. For example, a multi-line graph uses the first series to create a line with a variable number of points. This series is then used as a template to the second series to create a variable number of lines.
In the case of nested series objects, the name of top level series object is 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. The final hierarchy and the corresponding names look like this:DataGroupOne (series of lines) DataGroup (line template) DataSample (datasample template) DataGroup0 (first line instance) DataSample (datasample template) DataSample0 (datasample instance) DataSample1 (datasample instance) ... DataGroup1 (second line instance) DataSample (datasample template) DataSample0 (datasample instance) DataSample1 (datasample instance) ... ...
By default, the 2D version of graph widgets uses gradients for the graph's DataArea, line markers, bars of the bar graphs and other graph elements. When a large number of datasamples needs to be displayed with a fast update rate, the gradients may be disabled by editing object's rendering attributes to minimize CPU utilization and increase graph's update rate.
The RollBack attribute of the graph's DataGroup may be used in conjunction with the WRAPPED scrolling type for implementing scrolling behavior which scrolls the graph only once every n iterations, as defined by the value of the RollBack attribute.
For example, consider a graph with the WRAPPED scroll type, 200 datasamples, 10 X axis major ticks with labels, and 20 minor ticks per one major tick interval. Setting DataGroup/Rollback=40 and XLabelGroup/RollBack=2 will "roll" the graph back by 2 major tick and label intervals (which corresponds to 40 datasamples) when the graph gets completely filled with data.
The use of the RollBack limits the CPU-intensive scrolling operation to be performed only once on every 40th data update, compared with every data update in the regular scrolling graph with the SCROLLED scrolling type.
A special case of the rollback may be used to implement the graph which switches from the WRAPPED behavior to the SCROLLED behavior when the graph gets completely filled with data the first time. For example, for a graph with the WRAPPED scroll type, 200 datasamples, 10 X axis major ticks and labels, and 20 minor ticks per one major tick interval, the following settings may be used: DataGroup/Rollback=1 and XLabelGroup/Rollback=0.05 ( which corresponds to one minor tick - 1/20).
The update speed of a graph also depends on the number and type of objects rendered on every update iteration. Deleting auxiliary elements of a graph such as grids or minor ticks, as well as filled data area can substantially increase the graph's maximum update speed.
For graphs with a large number of data samples and fast update rates, rendering performance may be optimized by reducing the number of times the graph is redrawn. For example, if a graph receives a new data value every 10 milliseconds and redraws after each new data value, it will be redrawn 100 times per second. Instead of refreshing the graph each time a new data point is received, the application may update the graph just several times per second. Each update would push all data points accumulated since the last update and redraw the graph just once for all accumulated new data values.
Commonly Used Graph Resources
Before proceeding with the detailed description of all graph resources, let's consider the typical resources used to animate a bar graph:
DataGroup/Factor Defines the number of datasamples in the graph
DataGroup/DataSample/Low Defines the low range of data
DataGroup/DataSample/High Defines the high range of data
DataGroup/DataSample/Value Defines an initial value for graph's samples
DataGroup/ScrollType Defines the graph's scroll type (WRAPPED or SCROLLED)
DataGroup/EntryPoint An entry point for pushing data values into the graph.
XLabelGroup/Factor Defines the number of X labels, major ticks and grids
XLabelGroup/MinorFactor Defines the number of minor ticks per each major tick interval
XLabelGroup/XLabel/String Defines an initial value for the label, usually set to an empty
XLabelGroup/EntryPoint An entry point for pushing X axis labels into the graph
YLabelGroup/Factor Defines the number of Y labels, major ticks and grids
YLabelGroup/MinorFactor Defines the number of minor ticks per each major tick interval
YLabelGroup/Low Defines the low range of the Y axis labels, same as
YLabelGroup/High Defines the low range of the Y axis labels, same as
A line graph has a slightly different resource hierarchy for its DataGroup:
DataGroup/Factor Defines the number of datasamples in the graph
DataGroup/Marker/DataSample/Low Defines the low range of data
DataGroup/Marker/DataSample/High Defines the high range of data
DataGroup/Marker/DataSample/Value Defines an initial value for graph's samples
DataGroup/ScrollType Defines the graph's scroll type
DataGroup/EntryPoint An entry point for pushing data values into the graph
A multi-line graph has a different DataGroup hierarchy as well:
DataGroupOne/Factor Defines the number of lines in the graph
DataGroupOne/Persistent May be set to PERSISTENT to preserve attribute
settings of individual lines
DataGroupOne/DataGroup/Factor Defines a number of point in each line
DataGroupOne/DataGroup/Marker/DataSample/Low Defines the low range
DataGroupOne/DataGroup/Marker/DataSample/High Defines the high range
DataGroupOne/DataGroup/Marker/DataSample/Value Defines an initial value
DataGroupOne/DataGroup/ScrollType Defines the graph's scroll type
DataGroupOne/EntryPoint An entry point for pushing data values into all lines
DataGroupOne/DataGroupN/EntryPoint An entry point for pushing values into the Nth line
The top level DataGroupOne/EntryPoint resource may be used to push values into all lines of the graph. The entry points of each line (the DataGroupOne/DataGroupN/EntryPoint resources, where N is the index of a line) may be used to push datasamples into each line separately.
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. For example, a bar graph uses a series object to create a variable number of bar datasamples, and a line graph uses a polyline object to create a line with a variable number of points. In both cases, the Factor resource controls the number of bars or line points. Regardless of the type of an object used to replicate graph's datasamples, such a collection of data samples is called a data group, and these are identified with the DataGroup resource name.
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.
Each DataGroup has an EntryPoint resource which is used to push new data into the graph, while the graph automatically scrolls the data, via a history object attached to the DataGroup. The ScrollType resource allows changing the graph's scroll type, while the Inversed resource controls the update direction.
Resources of a DataSample
The type of object used as a data sample depends on the type of the graph. However, there are three resources present in the DataSample resource no matter the type of object. These are:
- The value to be represented by the data sample object. The Value resource of the template DataSample defines the initial value of all datasamples, while the Value of other datasamples defines the value of the datasample displayed in the graph.
- 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.
- Changes made to the Value 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. This may be used to save the data in the graph, and not as general technique, as the graph looses the ability to change the number of its datasamples after its datagroup has been exploded.
- 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. If the Low or High resources are changed, the graph automatically adjusts all currently displayed data to the new range. This allows the application program to change the range of the data on the fly when the amplitude of the data increases or decreases beyond the current graph's data range. It also allows the program to scale the data samples when the values get too small.
- Controls how the data samples with values outside of the graph's range are plotted. If set to YES, the values will be truncated to fit inside the graph's range. For vertical graphs, the data samples whose values are truncated will appear at the top or the bottom of DataArea.
The data sample objects displayed in a graph are dynamically created objects whose attributes are inherited from the template DataSample. The attributes of the DataSample template may be changed to define the appearance of all datasamples in a graph.
The program can change attributes of any datasample at any time as well, but as with any series object, changes to the template instances are not permanent, and last only until the drawing is reset or reloaded, at which time the instances of the datasamples are recreated by copying the template datasample. This behavior may be prototyped in the GLG Graphics Builder by changing resources of datasample instances: the changes will be discarded after resetting the graph by pressing the Reset toolbar button.
Local and Global Attributes
Any attribute of a datasample or any other template object may be made local or global by setting the value of its Global flag. If the attribute is global, it is constrained for all datasamples in the series. Changing the value of a global attribute will affect all datasamples as well as the series' template. To change an attribute of individual datasamples independently, set the Global flag for that attribute to LOCAL.
If a template attribute is GLOBAL, changing the attribute immediately affects all instances of the template in the series. If a template attribute is LOCAL, the drawing needs to be reset by pressing the Reset toolbar button after changing the attribute in the GLG Graphics Builder to see the new values. In a program, the values of local attributes must be set before the hierarchy setup, since the hierarchy setup creates instances of the template and copies the settings of the template's attributes.
In some graphs, various attributes of the data samples may have a transformation attached to them. For example, in a multi-line graph, the line's EdgeColor attribute has a List transformation to change the color depending on the line index, so that each line is rendered in a different color. A similar transformation is used to vary colors of the individual bars in packed and stacked bar graphs.
In this case, the value of the attribute can not be edited directly, as it is affected by the transformation attached to it. Instead, the Color0, Color1, Color2, ... resources will be provided to define a color of each line or bar.
To add more colors to the list of colors, select the line template of the polyline, select its EdgeColor attribute and edit a transformation attached to the attribute.
Nested Data Groups
Some types of graphs contain data groups whose elements are themselves composite objects. For example, a line graph with multiple lines or a packed bar graph that contain several "packs" of data, each of which contain several data samples.
In a multi-line graph, the series object used to create multiple lines is named DataGroupOne. It contains a template object named DataGroup which is used as a template for each line. The created line instances are named DataGroup0, DataGroup1, and so on. Each line instance contains datasamples named DataSample0, DataSample1, etc., located inside the line's Points group: Points/DataSample0, Points/DataSample1, and so on. Each line also contains DataSample template located inside its Marker object: Marker/DataSample.
In graphs such as a packed or stacked bar graph, the top level series object named DataGroup is used to replicate a desired number of "packs" or "stacks" of data, defined in its template named Pack. The created instances of packs will have names Pack0, Pack1, and so on. Each pack is a series object too, used to replicate its DataSample template to create several datasamples in each pack, named DataSample0, DataSample1, and so on.
For multi-line and other multi-set graphs, the DataGroupOne/Persistency attribute may be set to PERSISTENT to preserve attribute settings of individual lines. By default, the Persistent attribute is set to VOLATILE, and only the color setting is saved, while the rest of the line attributes have to be set at runtime. When the PERSISTENT setting is used, the attributes of individual lines may be set in the Builder.
DataGroup Resource Hierarchy
A DataGroup of a bar graph and other graphs that use the series object to replicate datasamples have the following resource hierarchy:DataGroup (series object) EntryPoint (entry point for pushing data values into the graph) Factor (number of datasamples) DataSample (datasample template) Low (low range of the graph) High (high range of the graph) Truncate (controls how out of range values are plotted) Value (inital value) DataSample0 (datasample instance) DataSample1 (datasample instance) ... (more datasample instances)
A packed or stacked bar graph will have a slightly different resource hierarchy:DataGroup (series object) EntryPoint (entry point for pushing values into the graph) Factor (number of datasample packs in the graph) Pack (template of a pack containing several datasamples) Factor (number of datasamples in a pack) Persistent (May be set to preserve attribute settings of individual samples in a pack) DataSample (datasample template) Low (low range of the graph) High (high range of the graph) Truncate (controls how out of range values are plotted) Value (inital value) Pack0 (pack instance) Pack1 (pack instance) ... (more pack instances)
A typical line graph and other graphs that use the polyline object with a variable number of points have the following resource hierarchy:DataGroup (polyline object) EntryPoint (entry point for pushing values into the graph) Factor (number of datasamples) Marker (template used for a point of the graph) DataSample (datasample) Low (low range of the graph) High (high range of the graph) Truncate (controls how out of range values are plotted) Value (inital value) Points (group containing all line's datasamples) DataSample0 (datasample instance) DataSample1 (datasample instance) ... (more datasample instances)
Finally, multi-line graphs that display several lines have the following resources:DataGroup One (series object used to replicate line instances) EntryPoint (entry point for pushing values into all lines) Factor (number of lines) Persistent (May be set to preserve attribute settings of individual lines) DataGroup (polyline object used as a line template) Factor (initial number of points in each line) Marker (template used for a point of the graph) DataSample (datasample) Low (low range of the graph) High (high range of the graph) Truncate (controls how out of range values are plotted) Value (inital value) DataGroup0 (line instance) EntryPoint (entry point for pushing values into this line) Factor (number of datasamples in this line) Marker (template used for a point of this line) DataSample (datasample) Low (low range of this line) High (high range of this line) Value (inital value) DataGroup1 (line instance) ... (line resources, same as in DataGroup0) ... (more lines instances)
The Data Area is a filled polygon used as a background for 2D graphs. It allows the graph to paint the area behind data samples in a color different from the background color. 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 rendered as a parallelogram object, and has three control points.
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 of the Data Area adjusts the geometry of all datasamples displayed in the graph.
An axis of a graph is just a polygon. Axes are named by the corresponding coordinate: XAxis, YAxis and ZAxis (for 3D graphs).
Major And Minor Ticks
A major tick is represented by a polygon object named XMajorTick for the X axis, YMajorTick for the Y axis, and ZMajorTick for the Z axis of 3D graphs. Everything described below in this chapter for the X axis ticks is also applicable to the ticks on the 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 for the X axis. The graphs use two nested series objects to produce the minor ticks. The inner series object, named XMinorGroup, uses XMinorGroup polygon as a template to produce the necessary number of minor ticks for one major tick interval. The series object on the top level, named XMinorGroupOne, uses the XMinorGroup series as a template reproduce it the number of times equal to the number of major tick intervals.
The templates of both the major and minor ticks have the EndPoint resource which controls the length of the tick. This resource may be used to adjust the tick length when the graph is stretched and ticks on one of the axes become too long or too short.
Setting the Number of Major and Minor Ticks
For convenience, the Factor and MinorFactor resource of both the major and minor ticks and the grids are constrained to the corresponding factors of the labels and may be edited in one place - the XLabelGroup series. Its Factor resource controls the number of labels, major ticks and grids, and the MinorFactor resource controls the number of minor ticks per each major tick. The total number of minor ticks, which is the product of the number of major ticks times the number of minor ticks, must match the number of the graph's datasamples, or the ticks will be misaligned:XLabelGroup/Factor * XLabelGroup/MinorFactor = DataGroup/Factor
In graphs with a large number of datasamples, the minor ticks series may be deleted to simplify the graph and increase its update performance.
Ticks can be positioned on a logarithmic scale if the graph displays 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.
The background grid lines in a GLG Graph are rendered as polygons named XGrid and YGrid. The polygons are used as templates in the series objects named XGridGroup and YGridGroup, which produce the necessary number of grid lines. The factors of the grid's series are constrained to have the same values as the number of major ticks on the corresponding axis.
Axis labels to be displayed at each major tick are represented by text objects named XLabel, YLabel and, for 3D graphs, 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 defines the number of labels, major ticks and grids. The MinorFactor resource defines the number of minor ticks per one major tick interval. For the time axis with scrolling labels (the X axis for horizontal graphs), the total number of minor ticks, which is the product of the number of major ticks times the number of minor ticks, must match the number of the graph's datasamples, or the ticks and labels will be misaligned with the datasamples.
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 XLabelGroup/XLabel and YLabelGroup/YLabel access the label templates which define the initial appearance of all labels for the X and Y axes. The attributes of each individual label of the label series may be changed dynamically at run time, but these changes are volatile and disappear after resetting or reloading the drawing.
The labels' font can be changed by editing the FontType and FontSize attributes of the label's template, i.e. XLabelGroup/XLabel/FontType.
By default, the labels use SCALED text and the FontSize resource controls the maximum size. The label will use a smaller font if the window is resized to a small size or if the label is too long. To use a label with a constant font size, change the label template to a FIXED font and adjust its control point (the XLabel/Point resource) to position it below the corresponding major tick.
If the type of the text object template for a label series is SCALED, the Global flag of the SizeConstraint attribute of the template label controls whether or not all axis labels are displayed using the same 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.
Value Labels and the Format Resource
The labels on the value axis (the Y axis for horizontal 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".
Every value 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 ranges of the graph's DataSample. Changing these resources affects both the labeling range and the data range of the graph, rescaling currently displayed data and displaying new label values.
The String attribute of a value label has a format transformation attached to the attribute to produce the proper value. The Format attribute of the transformation is exported as the Format resource of the label and may be edited to change the label format.
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 two digits of precision for all labels in the Y label series, change the Format resource of the label series template (YLabelGroup/YLabel/Format) to "%.2f". The Format may also be set to the following string "Value=%.2f" to display the "Value=" in front of each label value.
The "%" character has a special meaning and defines the start of a format specification. 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.
NOTE: It is the responsibility of the programmer to supply a valid 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, including a program crash.
To disable automatic labelling and supply a string to be displayed in each label at run-time, set the value of the Global flag of the Format resource of the template label to LOCAL (and reset the drawing if it is done in the GLG Graphics Builder). Then set the Format resource of each label instance to a desired string. For example, setting a format string of a label instance to "Level 1" simply displays "Level 1" in the label.
Scrolling Time Axis Labels
The labels on the time axis (X axis horizontal graphs) annotate the datasamples of the graph and scroll with them. The XLabelGroup time label series is equipped with the EntryPoint resource 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 the program 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.
To keep scrolling labels synchronized with the corresponding datasamples, the Factor and MinorFactor resources must be set to values that match the number of datasamples in the graph. The XLabelGroup/Factor resource controls the number of labels and major, while the XLabelGroup/MinorFactor resource controls the number of minor ticks per one major tick interval. The product of these two values yields the total number of minor ticks in the graph and should equal to the number of datasamples:
DataGroup/Factor = XLabelGroup/Factor * XLabelGroup/MinorFactor
When this condition is met, the program can simply supply one time label per each datasample, and the graph will handle the scrolling, displaying only the label values that correspond to the major tick.
For example, let's consider a graph with 200 datasamples, 10 major ticks and labels, and 20 minor ticks per each major tick interval. Since 10 * 20 == 200, the program may supply one label and one datasample value per each update, and the graph will scroll the datasamples and labels automatically.
For a multi-line graph with the same resource settings and three lines, the program would supply three datasample values (one for each line) and one label per each update. The same would also be true for a packed or stacked bar graph with 3 datasamples in each pack.
For the graphs with a large number of datasamples, minor ticks may be deleted from the drawing to decrease the number of objects used by the graph. The MinorFactor of the label series should be still set to a proper value to maintain the equation Factor x MinorFactor = Number of DataSamples.
The ScrollType and Inversed resources of the XLabelGroup object is constrained to the corresponding resources of the graph's DataGroup to ensure that the scrolling behavior of the labels is consistent with the scrolling behavior of the graph. The values of these resources may be set in either place.
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 to annotate application-specific thresholds.
A level object is represented by a polygon named LevelObject which is used as a template for the LevelObjectGroup series to produce several copies of the level object. A factor of the 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, for example using different colors. As with all series, the Global flags of the template attributes that need 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, otherwise the attributes have to be changed dynamically at run-time.
Level objects may be set invisible or deleted from the graph drawing if they are not used.
The status object (the StatusObject resource) is used to indicate the current update position for the graphs with the WRAPPED scrolling type. It moves after every update to the next data sample, wrapping back to the starting position after reaching the last one.
A status object may be set invisible or 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 for horizontal graphs.
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.
Graphs with multiple datasets, such as multi-line graph or packed bar graph, contain legends that annotate the entities displayed by the datasets of the graph. 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. The Special widget set also contains optional legends that may be added to any graph.
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 LegendLabel text object is used to name entities in the graph. The polygons and markers are used to display the color, line width or line type associated with a particular entity.
The Special widget set contains optional axis objects that may be added to any graph. Both the value and scrolling time axes are provided, including the vertical and horizontal versions. A rotary axis for dial widgets is also provided.
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.
- XAngle, YAngle, ZAngle
- Control the rotation of the whole drawing around the specified axis.
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, which provides the best 3D effect.
Input Widgets, Dials and Meters
The GLG Widget Library provides a wide selection of dial, meters, sliders, buttons, toggles, and other input widgets. Most of these widgets have an input handler attached to the widget's viewport and may be used for both input and output. To disable the widget's interactive capabilities and use it only for the output, delete or disable the widget viewport's input handler.
This chapter describes common resources of various input widget types. Refer to Input Objects of the GLG User's Guide and Builder Reference Manual for detailed information on resources of various input handlers.
Note that the input handlers attached to an input widget expects the widgets to have several predetermined resources depending on the type of the input handler. Altering the names of these resources may render the widget inoperable, and may generate an error message when the drawing is reset.
At run-time, the application's Input callback receives a message when a widget receives some input. Refer to Input Objects on page 217 of the GLG User's Guide and Builder Reference Manual for information on the message parameters of various input handlers.
Refer to the Appendix B: Message Object Resources section on page 399 of the GLG User's Guide and Builder Reference Manual for information on the input actions for various types of input handlers.
Meters, Dials and Avionics gauges
Most of the meters, dials and avionics gauges use the rotary axis and the Knob resource set described below. Some of the avionics gauges use two sets of needles and/or two sets of rotary axes. Most of the meters and dials are available in two versions: with a viewport and viewport-less.
A viewport-based version of a dial displays each dial in a separate window by using a viewport object as a container for each widget. The GlgKnob input handler is attached to the widget's viewport, enabling the widget to handle both the input and output. If the widget's input handler is not disabled, the dial's needle can be moved with the mouse.
A viewport-less version does not create a window and may be used as a non-rectangular dial on top of a custom background image. Most of the avionics dials provide only viewport-less version, but may easily be placed in a viewport if necessary.
The rotary axis is a part of a variety of GLG dials, meters, knobs and rotary switches, as well as most of the avionics gauges. The rotary axis includes two components: the rotary axis (named Axis in the drawing) with labels, major and minor ticks, and the alarm sector (named AlarmSector), consisting of colored arcs which indicate the normal and abnormal range of values (similar to the the alarm sectors commonly used in tachometers).
Rotary axis contains the following resources that control its appearance:
- AngleStart (DDATA) The start angle of the rotary axis.
- Angle (DDATA) The angle between the start and end of the axis.
- Center (GDATA) The axis' center position (may also be changed by moving the
arc with the mouse).
- High (DDATA) The high range of the axis' labels.
- Low (DDATA) The low range of the axis' labels.
- InnerBorder (ARC) The inner arc outline (drawn if Visibility=ON).
- OuterBorder (ARC) The outer arc outline (drawn if Visibility=ON).
- OuterCircle (ARC) A full circle drawn around the axis (drawn if Visibility=ON).
- InnerRadius (DDATA) The inner radius of the axis' ticks.
- OuterRadius (DDATA) The outer radius of the axis' ticks.
- LabelRadius (DDATA) Controls the position of the axis' labels.
- NumMajorTicks (DDATA) The number of major tick intervals.
- NumMinorTicks (DDATA) The number of minor tick intervals.
- NumLabels (DDATA) The number of label intervals (one less than the number of
- MajorTick (POLYGON) The major tick template.
- InnerOffset (DDATA) The offset between the inner radius and the inner end of the
major tick, used to control the tick length.
- OuterOffset (DDATA) The offset between the outer radius and the outer end of the
major tick, used to control the tick length.
- MinorTick (POLYGON) The minor tick template.
- InnerOffset (DDATA) The offset between the inner radius and the inner end of the
minor tick, used to control the tick length.
- OuterOffset (DDATA) The offset between the outer radius and the outer end of the
minor tick, used to control the tick length.
- TickLabel (TEXT) The label template.
- Format (SDATA) The C-style label format.
Alarm Sector Resources
- Visibility (DDATA) Controls the visibility of the alarm sector.
- AngleStart (DDATA) The start angle of the alarm sector.
- AngleEnd (DDATA) The end angle of the alarm sector.
- BgColor (GDATA) The background color of the alarm sector; is usually constrained
to the background color of the dial.
- Center (GDATA) The alarm sector's center position (may also be changed by
moving the arc with the mouse).
- InnerRadius (DDATA) The inner radius of the alarm sector.
- OuterRadius (DDATA) The outer radius of the alarm sector.
- NumAlarms (DDATA) The number of arcs in the alarm sector.
- Colors (GROUP) A group of the alarm sector's colors.
- Color<N> (GDATA) A color of the <N>th alarm sector.
- High (DDATA) The high range of the thresholds. The default value is 100,
allowing the specification of thresholds as percentages of the
- Low (DDATA) The low range of the thresholds. The default value is 0.
- Thresholds (GROUP) A group of the alarm sector's thresholds.
- Value<N> (DDATA) A thresholds of <N>th alarm sector. Controls's the <N>th alarm
sector's angle, the range of the values must match the High and
Low range of the thresholds.
A Slider Widget converts a linear mouse position into one or two scalar values, and provides some appropriate visual feedback by moving its active element. When the left mouse button is pressed over the Slider Widget, the slider reacts by moving its active element to the mouse position. If the left mouse button is held down and dragged, the active element of the slider follows the mouse until the button is released.
There are several different versions of slider widgets in the GLG Widget Library, each with a different look and feel. There are also two-dimensional versions that control two variables, one corresponding to the X coordinate and the other corresponding to the Y coordinate. For one-dimensional sliders, there are horizontal and vertical versions of each slider. Native sliders and scrollbars are also provided as separate widgets.
The slider contains ValueX (for the horizontal slider) or ValueY (for the vertical slider) resource which contains the slider's value and is set by the slider each time its knob is moved. The two-dimensional slider contains both ValueX and ValueY resources, while horizontal and vertical sliders contain only one of them, depending on the slider direction. A native slider contains a Value resource regardless of the slider direction.
An object called ActiveElement provides a visual feedback for the current slider value. The range of positions of the active element is associated with the range of the slider values, defined by the Low and High resources of the slider. Some sliders also have an indicator showing the current slider value in digital form. Many sliders have the SliderSize, StartPosition and EndPosition resources that control the size of the ActiveElement as well as the extent of its movement.
A slider may also be used for output, displaying a value of its Value resource. When the slider's ValueX, ValueY or Value resources are set, the slider positions its active element to show the new value. If the widget is used only for output, you may decide to delete or disable the input handler of the widget's viewport, although this is not necessary. The ActiveElement's Truncate resource controls how out of range values are displayed. By default, it is set to ON to truncate the out of range values to force them in the range, so that the slider's knob does not move outside its start and end positions.
These are the resources you are likely to see in a Slider Widget's hierarchy. Note that while the ValueX and ValueY resources are optional, the slider widget must contain at least one of them. A native slider widget contains the Value resource instead of ValueX and ValueY.
- ValueX (DDATA, optional) The slider's X value.
- OutValueX (DDATA, optional) The slider's X output value. It can be used to constrain other
objects to this resource.
- ValueY (DDATA, optional) The slider's Y value.
- OutValueY (DDATA, optional) The slider's Y output value. It can be used to constrain other
objects to this attribute.
- Value (DDATA, optional) The native slider's input value.
- OutValue (DDATA, optional) The native slider's X output value. It can be used to constrain
other objects to this attribute.
- Low (DDATA, optional) The lower limit of the slider's output value.
- High (DDATA, optional) The upper limit of the slider's output value.
- LowX (DDATA, optional) The lower limit of the 2D slider's X value.
- HighX (DDATA, optional) The upper limit of the 2D slider's X value.
- LowY (DDATA, optional) The lower limit of the 2D slider's Y value.
- HighY (DDATA, optional) The upper limit of the 2D slider's Y value.
- Granularity (DDATA, optional) If this resource is present and set to a non-zero value, the slider
is limited to the number of allowed positions defined by the
value of this resource.
- DisableMotion (DDATA, optional) If this resource is present and set to a non-zero value, the
slider's reaction to MotionNotify events is disabled.
- StartPosition (GDATA, optional) A point that defines the lower limit of the slider's range.
- EndPosition (MARKER, optional) A point that defines the upper limit of the slider's range.
- ActiveArea (POLYGON, optional) The screen cursor must be within this polygon for the slider
to react to user input. This resource is not usually present in
the default slider. Instead, the ActiveAreaSpare polygon
(invisible by default) is defined. It may be renamed
ActiveArea and positioned as desired to make only some area
of the slider sensitive to mouse events.
- Plane (POLYGON, optional) The slider pointer slides on the plane defined with this polygon.
The points of the polygon must be coplanar.
A slider may also have buttons. A user may click on these buttons to move the slider pointer the distance specified by the Increment resource in some direction. The buttons have the following names:
- Increase (VIEWPORT, optional) An "increase" button for a one-dimensional slider.
- Decrease (VIEWPORT, optional) A "decrease" button for a one-dimensional slider.
- PageIncrease (VIEWPORT, optional) A "page increase" button for a one-dimensional slider.
- PageDecrease (VIEWPORT, optional) A "page decrease" button for a one-dimensional slider.
- Left (VIEWPORT, optional) A directional button for a two-dimensional slider.
- Right (VIEWPORT, optional) A directional button for a two-dimensional slider.
- Up (VIEWPORT, optional) A directional button for a two-dimensional slider.
- Down (VIEWPORT, optional) A directional button for a two-dimensional slider.
- Increment (DDATA, optional) If the slider viewport contains motion buttons, each click on the button moves the slider by the amount specified by this resource. The value of the resource is between 0 and 1, and refers to a proportion of the total range of the slider. If this resource is not present, the default increment of motion is 0.02 times the total slider range.
- PageIncrement (DDATA, optional) Defines the amount of the page increment. The value of the resource is between 0 and 1, and refers to a proportion of the total range of the slider. If this resource is not present, the default page increment is 0.1 times the total slider range.
Refer to GlgSlider on page 221 of the GLG User's Guide and Builder Reference Manual for information on other optional resources of the slider widgets.
A Knob Widget converts an angular mouse position into a value, providing visual feedback in the form of the angular position of the knob's active element. When the left mouse button is pressed over the Knob Widget, the knob reacts by moving its active element to the mouse position. If the left mouse button is held down and dragged, the active element of the knob follows the mouse until the button is released.
There are several different versions of Knob Widgets in the GLG Widget Library, each with a different look and feel. Each uses an object called ActiveElement to provide the visual feedback for the current knob value. The range of positions of the active element is associated with the range of the knob values, defined by the Low and High resources of the knob. Some knobs also have an indicator that shows the current knob value as a number.
A knob may also be used for output. When used this way, the widget converts a scalar values (specified with the Value resource) into the position of its active element. If the widget is used only for output, you may decide to delete or disable the input handler of the widget's viewport, although this is not necessary. The ActiveElement's Truncate resource controls how out of range values are displayed. By default, it is set to ON to truncate the out of range values to force them in the range, so that the knob does not rotate outside its start and end positions.
- Value (DDATA, mandatory) The knob's value.
- OutValue (DDATA, optional) The knob's output value. It can be used to constrain other
objects to this resource.
- Low (DDATA, optional) The lower limit of the knob's value.
- High (DDATA, optional) The upper limit of the knob's value.
- Granularity (DDATA, optional) If this resource is present and set to a non-zero value, it
specifies the number of allowed positions for the knob.
- DisableMotion (DDATA, optional) If this resource is present and set to a non-zero value. the
knob's reaction to MotionNotify events is disabled.
- StartAngle (DDATA, optional) The Value resource is at its lower limit when the knob is at
- EndAngle (DDATA, optional) The Value resource is at its upper limit when the knob is at
- Center (MARKER, optional) A marker placed at the rotation center of the knob.
- ActiveArea (POLYGON, optional) The screen cursor must be within this polygon for the knob
to react to user input. This resource is not usually present in
the default knob. Instead, the ActiveAreaSpare polygon
(invisible by default) is defined. It may be renamed
ActiveArea and positioned as desired to make only some area
of the knob sensitive to mouse events.
- Plane (POLYGON, optional) The knob pointer slides on the plane defined with this
polygon. The points of the polygon must be coplanar.
A Knob Widget may also have control buttons. A user may click on these buttons to move the knob pointer a preset distance in some direction. The buttons have the following names:
- Increase (VIEWPORT, optional) An "increase" button for a knob.
- Decrease (VIEWPORT, optional) A "decrease" button for a knob.
- PageIncrease (VIEWPORT, optional) A "page increase" button for a knob.
- PageDecrease (VIEWPORT, optional) A "page decrease" button for a knob.
- Increment (DDATA, optional) If the knob viewport contains control buttons, each click on the button moves the knob by the amount specified by this resource. The value of the resource is between 0 and 1, and refers to a proportion of the total range of the knob. If this resource is not present, the default increment of motion is 0.2 times the total knob range.
- PageIncrement (DDATA, optional) Defines the amount of the page increment. The value of the
resource is between 0 and 1, and refers to a proportion of the total range of the knob. If this resource is not present, the default page increment is 0.1 times the total knob range.
Refer to GlgKnob on page 225 of the GLG User's Guide and Builder Reference Manual for information on other optional resources of the knob widgets.
A Button Widget is a widget activated with a mouse press. Buttons can be push buttons that produce some action when they are pushed, but do not have a "state," or toggle buttons, that have an internal state. The type and behavior of different buttons are based on the resources present in the button's viewport. Native push button and toggle widgets are also provided.
- OnState (DDATA, optional) The toggle state of the button. Buttons with this resource are
toggle buttons. If the resource is not present, they are push
buttons. If present, this resource may be 0 or 1. A toggle button
will usually use this resource to create some indicator showing
- InState (DDATA, optional) This resource is 1 when the mouse cursor is on the button, and
0 otherwise. A button can use this resource to change some
attribute when the mouse cursor enters the button viewport.
- PressedState (DDATA, optional) This resource is 1 when the mouse cursor is on the button and
the mouse button is depressed.
- ArmedState (DDATA, optional) This resource is set to 1 when the mouse is on the button and
the Control key is pressed. This functionality can be disabled
by setting the resource to -1.
- LabelString (SDATA, optional) The label for the button. This resource is used when the button
is on a menu, and allows a button's label to be changed from a
- TokenValue (DDATA, optional) The button's value. This resource is used when the button is a
part of a menu widget.
- ActOnPress (DDATA, optional) If this resource is present and non-zero, the button state will
change with the down-click of the mouse button. Otherwise,
the state changes with the up-click. This resource cannot be
changed dynamically; the drawing must be reset to update it.
- PressedLightCoeff (DDATA, optional) This value is added to the button's ambient light
coefficient. It is used to control how much darker the
button becomes when pressed.
- BevelSize (DDATA, optional) Specifies the width of the bevels, if there are any. The width is
given in numbers of pixels.
Refer to GlgButton on page 228 of the GLG User's Guide and Builder Reference Manual for information on other optional resources of the button widgets.
A Menu Widget is an array of button widgets. The Menu manages the buttons, allowing the application to manage the array of buttons as a single object. The use of the GlgMenu input handler is described on page 236 of the GLG User's Guide and Builder Reference Manual.
- Button<n> (VIEWPORT) These are the buttons on the menu. The <n> is a zero-based
index. A menu must contain at least one button.
- ScrollObject (VIEWPORT, optional) The menu scroll bar. Scrolling is enabled if LabelList
contains the number of labels bigger than the number of
buttons in the menu.
- SelectedIndex (DDATA, optional) The index of the last selected button.
- SelectedString (SDATA, optional) The label of the last selected button.
- SelectedValue (DDATA, optional) The value of the last selected button.
- LabelList (GROUP, optional) A list of S data objects containing button labels. This resource
may not be modified dynamically. The drawing must be reset
after each change to the LabelList.
- TooltipList (GROUP, optional) A list of S data objects containing tooltip strings. This resource
may not be modified dynamically. The drawing must be reset
after each change to the TooltipList.
Refer to GlgMenu on page 236 of the GLG User's Guide and Builder Reference Manual for information on other optional resources of the menu widgets.
A Text Widget is used for entering a text string. There are versions of the text widget for entering numerical values, both integer and floating point.
- TextString (SDATA, optional): The current value of the text string entered.
- The following resources are present only in the numerical version of the text widget:
- Value (DDATA) The current value.
- MinValue (DDATA, optional) The minimum value.
- MaxValue (DDATA, optional) The maximum value.
- ValueFormat (SDATA, optional) The C-style format for displaying the value.
- InputInvalid (DDATA) Displays the status of input parsing.
Refer to GlgNText on page 230 of the GLG User's Guide and Builder Reference Manual for information on other optional resources of the text widgets.
A Spinner Widget is used for entering a numerical value using arrows to increase or decrease it. An optional slider may be used for changing the value with the mouse.
- Value (DDATA) The spinner's value.
- MinValue (DDATA, optional) The minimum allowed value.
- MaxValue (DDATA, optional) The maximum allowed value.
- Increment (DDATA, optional) The value increment.
- PageIncrement (DDATA, optional) The value page increment.
- Wrap (DDATA, optional) Enables wrap mode.
- IncreaseKeys (SDATA, optional) Lists keyboard accelerators for increasing the value.
- DecreaseKeys (SDATA, optional) Lists keyboard accelerators for decreasing the value.
- TextInput (VIEWPORT, optional) A text input viewport for entering the value.
- Increase (VIEWPORT, optional) An optional button for increasing the value by Increment.
- Decrease (VIEWPORT, optional) An optional button for decreasing the value by Increment.
- PageIncrease (VIEWPORT, optional) An optional button for increasing the value by
- PageDecrease (VIEWPORT, optional) An optional button for decreasing the value by
- Slider (VIEWPORT, optional) An optional slider object for changing the value with the
List and Option Menu
The List and Option Menu widgets provide access to the corresponding native list and option menu or combo box widgets. Refer to the corresponding chapters on page 233 and page 235 of the GLG User's Guide and Builder Reference Manual for information on the resources of these widgets.
Clock and Stopwatch
The Clock and Stopwatch Widgets display the current time or elapsed time. Both widgets use the same input handler, The handler takes care of updating the time and reacting to the input events for the stopwatch. The Clock Widget continues updating even while being edited.
The Clock Widget does not react to input events from a user and serves to display the current time only. If the TimerState resource is present, the clock measures elapsed time instead of real time, and the widget becomes a stopwatch. The Stopwatch Widget can receive input through three buttons contained in the clock viewport.
If the input handler of the Clock Widget is deleted or disabled, the widget may be used to display user-defined time under control of an application program. In this case the application program uses the widget resources to drive the clock.
The hands and other elements of the widgets may be edited the same way as any other object.
- Hour (DDATA, optional) The number of hours. (0-11)
- Min (DDATA, optional) The number of minutes. (0-59)
- Sec (DDATA, optional) The number of seconds. (0-59)
- ValueHour (DDATA, optional) The scaled hour value. This is a value between 0 and 1, and is
provided to simplify the positioning of clock hands.
- ValueMin (DDATA, optional) The scaled minute value. This is a value between 0 and 1, and is
provided to simplify the positioning of clock hands.
- ValueSec (DDATA, optional) The scaled second value. This is a value between 0 and 1, and is
provided to simplify the positioning of clock hands.
- HourLabel (TEXT, optional) A title for the hour display.
- MinLabel (TEXT, optional) A title for the minute display.
- SecLabel (TEXT, optional) A title for the second display.
- TimeString (SDATA, optional A string describing the time in the "00:00" format.
The following resources are used for the stopwatch widgets.
- TimerState (DDATA, optional) If this resource is present, the Clock Widget measures elapsed time.
When the resource is 0, the clock is stopped, and when it is 1, the
clock is running.
- Start (VIEWPORT, optional) If a button with this name is present within the clock viewport,
pressing it will cause the stopwatch to start.
- Stop (VIEWPORT, optional) If a button with this name is present within the clock viewport,
pressing it will cause the stopwatch to stop.
- Reset (VIEWPORT, optional) If a button with this name is present within the clock viewport,
pressing it will cause the stopwatch to reset to zero.
A Palette Widget is used for creating different palettes with which to present a user with choices of objects. The Palette Widget was created to help a user choose colors, but it can be used to choose one from any selection of objects. This widget is designed to be used within a program using the GLG API.
A palette contains a single resource, an object named PaletteObject. This is a group or series object that contains several objects, each corresponding to a different possible choice. The user selects one of the presented objects with the left mouse button, and the choice is returned to the calling program in the callback message object.
For more information about callbacks and message objects, see the GLG User's Guide and Builder Reference Manual.
- PaletteObject (ANY OBJECT) An object displaying the set of choices.
- SelectedObject (ANY OBJECT, message only) The selected object. This resource does not
appear in the drawing resource hierarchy, but is
passed to the user-supplied callback function
inside the message object.
- DisableMotion (DDATE) Disables handling motion events. If motion
events are enabled, selection messages are
generated on both mouse click and mouse
Font, Resource and Tag Browsers
The Font Browser Widget is used to facilitate the font selection from the list of all fonts available for the X server used to display the widget. The Font Browser, in turn, uses other widgets such as Menu, Text and Slider as its components. The Font Browser Widget is not available on the Windows platform, where a native font browser is available.
The Resource Browser and Tag Browser Widgets provide the application with the resource and tag browsing functionality similar to the one in the GLG Graphics Builder.
Note that the browser's buttons may have labels different from their resource names.
Common Resources of Browser Widgets
The following resources are shared by all types of the browser widgets:
- Path (VIEWPORT) A text widget for entering a resource path for the resource
browser or tag name for the tag browser.
- Filter (VIEWPORT, optional) A text widget for entering and displaying the current value
of the filter string. Only entries that match the filter string
are displayed in the selection menu.
- Menu (VIEWPORT) A menu widget that displays a list of all available entries.
- Done (VIEWPORT, optional) A button for accepting the selection. This button is used to
generate an "Activate" message when the selection is
- Cancel (VIEWPORT, optional) A button for cancelling the selection. This button is used to
generate a "Cancel" message to indicate the user's desire
to cancel the selection process without making a selection.
- Reset (VIEWPORT, optional) A button to reset the filter.
Resource Browser's Resources
- ListNamed (VIEWPORT) A toggle that controls the display of named resources.
- ListAliases (VIEWPORT) A toggle that controls the display of aliases.
- ListDefault (VIEWPORT) A toggle that controls the display of default resources.
Tag Browser's Resources
- UniqueTags (VIEWPORT) A toggle that controls the display of unique tag names. If
set to ON, all tags with the same name will be displayed.
If set to OFF, only tags with unique names will be
Font Browser Resources
- FontName (VIEWPORT) A text widget for entering and displaying the current font
- FontSampleName (SDATA, optional) The name of the selected font.
- FieldMenu (VIEWPORT, optional) A menu widget for constructing the filter. Clicking on one
of the buttons shows a list of the available options for that
- FontSample (VIEWPORT, optional) A viewport with a text object in it to display sample text
using the selected font.
- FontSampleName (SDATA, optional) The name of the selected font.
Process Control Objects
The process control symbols palettes provide the user with an easy way to create process control drawings by simply selecting the pre-built objects from a palette. Most of the objects have a built-in dynamic behavior to be used for displaying values or animation.
The resource named Value is the main dynamic resource of these objects. For example, setting the Value of a tank object to a value in the range from 0 to 1 changes the level of the tank's filling. For a valve object, the Value resource controls its opening. For fans, pumps and other dynamic equipment, changing the Value resource from 0 to 1 in small increments animates the piece of equipment.
The objects may also have other resources to control their appearance:
- ForegroundColor and BackgroundColor control objects' colors.
- OpenColor and CloseColor control the colors of valves.
- ColorIndex controls the displayed color of various indicator objects, and Color0, Color1, ... ColorN resources define available colors.
- LineWidth controls the line width of lines used to render the object.
- Units controls the unit label string used by various indicator objects.
- Format controls the C format used to display the object's numerical value.
The process control objects also include connector-style objects such as various pipes and lines. While most of the objects are like nodes with just one control point, the connector-style objects have two control points which may be used to define their shape. Some of the connectors have various elements replicated along the connector and have the NumElements and ElementSize resources to control the elements.
The Resource Browser may be used to list all resources of the selected process control object. Tags may be assigned to the resource names to facilitate connecting dynamic data to the objects. Refer to Using Tags on page 279 of the GLG User's Guide and Builder Reference Manual for more information about tags.
Layout templates provide a collection of templates for an application's top-level window. Each template contains a viewport named DisplayArea, as well as optional fixed-size (non-resizable) viewports on the left, right, top and bottom of DisplayArea that can be used to host a toolbar, a menu or a message area. The optional areas are named AreaLeft, AreaRight, AreaTop and AreaBottom. The OffsetLeft, OffsetRight, OffsetTop and OffsetBottom resources define the size of the optional areas in screen pixels.
For applications that use a menu to navigate between different drawings, the DisplayArea viewport can be replaced with a SubWindow object by selecting the viewport and using the Arrange, Replace Viewport with SubWindow menu option available in the Enterprise Edition of the Graphics Builder. The subwindow's Source attribute can then be changed to FILE, and the Source Path attribute can be used to supply a filename of the drawing to be displayed in the subwindow.
Generic Logic, Inc.