The VkMeter class supports simple compound bar charts, displayed in either vertical or horizontal mode. If you display multiple values, the data is presented in layers, with the bar representing the second value starting where the first value ends.
Meter Constructor and Destructor
The VkMeter accepts the standard ViewKit ObjectPak component constructor arguments: a component name and a parent widget:
VkMeter(const char *name, Widget parent)
You should rarely need to create subclasses of VkMeter.
The VkMeter destructor frees all space associated with the meter:
Resetting the Meter
Before adding any items for display to a VkMeter object, you must call VkMeter::reset() to reset the meter:
void reset(int peak = -1)
First value peak sets the initial peak value displayed by the meter. All items displayed by the meter are scaled relative to the peak value. For example, if the peak value is 200 and one of your items is 40 units long, that item scaled to take 20% of the meter's total length. Default peak size is 100 units.
Note: To change meter values or otherwise update a meter object, you must call reset() and then add the items to the meter again.
Adding Items to a Meter
You add items for a VkMeter object to display with VkMeter:add():
- void add(int value, char *color)
The value argument is the item's value. When displayed, the VkMeter class scales this value relative to the peak value set by reset(). For example, if the peak value is 500 and one of your items is 80 units long, that item will be scaled to take 16% of the meter's total length.
When you use these forms of the add() function, the VkMeter object displays the items sequentially. For example, if you have set the peak value to 100 and you add three items with values of 20, 10, and 30 in that order, the meter displays three bars: the first ranging from 0 to 20, the second from 20 to 30, and the third from 30 to 60.
All data items must have an associated color. You can specify the color as a Pixel value, pixel, or as a string, color. If you provide a string, add() first treats the string as the name of a resource that add() looks up relative to the component and converts to the desired color. If add() finds no such resource, it uses the string itself as the name of a color. For example, the following adds an item with the color "red":
The following adds an item with the color specified by the resource name "criticalColor":
Specifying item width
You can specify the width of an item by providing a width argument, expressed in pixels. If you do not provide a width, the width of the item is the same as the width of the meter.
Two more complex forms of add() allow you to precisely control the position of bars in a meter, and even display bars side by side:
- void add(int start, int size, int sideValue, int width, char *color)
In these forms of add(), the first value, start, specifies the starting position of the bar, and the second value, size, specifies the size (length) of the bar. VkMeter scales these values relative to the peak value set by reset(). The third argument, sideValue, and the fourth argument, width, specify values in the opposite dimension. VkMeter does not scale these values relative to the meter's peak value.
For example, consider a meter with a peak value of 100. The following lines add four bars to the meter:
- add(0, 20, 0, 10, "red");
If you display this meter vertically, it shows three vertical bars ranging from 0 to 20 side by side in red, blue, and green. Above them is a yellow bar spanning all of them and ranging from 20 to 40.
Updating the Meter Display
After adding all items to a meter, call the VkMeter::update() function to update the meter's display:
Note: Remember that if you want to change the meter display, you must first call reset() and then add each item in the new display.
Setting the Meter's Resize Policy
The meter you create can have either a fixed size or it can attempt to resize itself dynamically as it requires more or less room to display the items it contains. You can specify the meter's resize policy with VkMeter::setResizePolicy():
void setResizePolicy( unsigned char policy )
You can provide any of the following values:
XmRESIZE_NONE The meter never attempts to resize itself. The application, or managing widget, is in complete control of the meter's size.
XmRESIZE_GROW The meter calls XtSetValues() on the widget used to display the meter to attempt to grow as needed. The success of the call to XtSetValues() depends on the parent widget's geometry management policy.
XmRESIZE_ANY The meter calls XtSetValues() on the widget used to display the meter to attempt to grow or shrink as needed. The success of the call to XtSetValues() depends on the parent widget's geometry management policy.
Determining the Desired Dimensions of the Meter
You can determine the dimensions that a meter needs to display itself completely by calling VkMeter::neededWidth() and VkMeter::neededHeight():
X Resources Associated with the Meter Component
The following X resources are associated with the VkMeter class:
XmNorientation Determines the orientation of the meter. The default value is XmVERTICAL which specifies a vertical meter. Set the value of the resource to XmHORIZONTAL for a horizontal meter.
XmNresizePolicy Determines the resize policy of the meter, as described in "Setting the Meter's Resize Policy" . The default value is XmRESIZE_NONE.
XmNdrawBorder Determines whether bars are drawn with borders. The default value is FALSE, in which case bars do not have borders. If you set the value to TRUE, bars have borders drawn in the color specified by the XmNborderColor resource.