WkCircularGauge

The WkCircularGauge widget provides a visual indication of a magnitude within a given range. It can be used to represent such values as the amount of gas left in a gas tank, or the remaining balance in a bank account. It is also often used to indicate the amount of time spent/remaining on a long compute-bound processing task, such as reading a file or sorting a list.

The gauges provided in WidgetKit/Controls can either be rectangular or circular. The rectangular versions, WkHorizontalBarGauge and WkVerticalBarGauge, show a rectangular bar to indicate the current value of the gauge (increasing to the right and upwards, respectively). The WkCircularGauge fills the wedge of a circle to indicate its value.

The direction of the progress sweep can be specified (clockwise or counterclockwise). The angle of the gauge’s completion indication is controlled by the start angle, value, minimum and maximum resources. The gauge’s progress indication is a color (pieColor resource). The uncompleted progress indication is a color (foregroundColor resource). A label can be drawn centered in the progress bar. This can either be a percentage complete (value / (max - min)), displayed automatically by the progress bar (howPercentage resource), or any defined renderable image as the label (image resource). The guage can be forced to be circular or drawn as an oval that fits its bounding box (mustBeCircle resource).

Protocol

direction: anInteger
Specifies the direction the pie is drawn.

Default: XmFORWARD (Forward/Clockwise)

Valid resource values:

XmFORWARD (Forward/Clockwise) - The pie is drawn clockwise.

XmREVERSE (Reverse/Counter Clockwise) - The pie is drawn counter clockwise.

 

fractionComplete: anInteger
Specifies the current amount of progress to show in the progress bar. This resource is a fraction, denoting a number between 0 and 1. For example, 1/10 specifies 10 % complete. 1 represents 100 % complete.

 

image: aPixmap
Specifies the renderable object which draws as the label of the progress bar. The label is displayed only if the showPercentage resource value is false. Note that the image label is drawn twice, in the foreground and background colors, so that the label appears ‘reversed’ over the actual foreground and background colors of the progress bar. If a ribbon image is being used, then the label is drawn once, using the foreground color.

 

imageColor: aCgRGBColor
Specifies the color of the label drawn according to the image resource, or the color of the percentage complete label, according to the showPercentage resource. If the resource value is nil, then the label is drawn in reverse color over the colors of the progress bar (foreground color) and the background color.

 

maximum: anInteger
Specifies the gauge's maximum value.

 

minimum: anInteger
Specifies the gauge's minimum value.

 

mustBeCircle: aBoolean
Specifies whether the gauge should be forced to be circular (default is oval).

 

pieColor: aCgRGBColor
Specifies the color of the pie.

 

setValue: anInteger
Sets the gauge's position between minimum and maximum and triggers the value changed callback.

 

shadowType: anInteger
Specifies the drawing style for the frame around the progress bar widget.

Default: XmSHADOWIN (Shadow In)

Valid resource values:

XmSHADOWNONE (Shadow None) - No frame is drawn.

XmSHADOWIN (Shadow In) - Draws a frame such that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed.

XmSHADOWOUT (Shadow Out) - Draws a frame such that it appears outset.

 

shadowWidth: anInteger
Specifies the width for the border

 

showPercentage: aBoolean
Specifies the whether a label showing the percentage completed is shown in the progress bar. If true, then the string ‘X %’ is show in the progress bar, where X is the percentage of progress completed. If false, then no percentage label is shown.

 

startAngle: anInteger
Specifies the starting angle of the gauge in degrees (90 is the default).

 

value: anInteger
Specifies the gauge's position between minimum and maximum.

Callbacks & Events

Value Changed Callback
These callbacks are triggered after widget’s value has been changed.

Editor

Circle
Determines whether the gauge should be forced to be circular (default is oval).

 

Direction
Specifies the direction the pie is drawn.

Forward/Clockwise - The pie is drawn clockwise.

Reverse/Counter Clockwise - The pie is drawn counter clockwise.

 

Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.

 

Image
Specifies the renderable object which draws as the label of the progress bar. The label is displayed only if the showPercentage resource value is false. Note that the image label is drawn twice, in the foreground and background colors, so that the label appears ‘reversed’ over the actual foreground and background colors of the progress bar. If a ribbon image is being used, then the label is drawn once, using the foreground color.

 

Maximum
Specifies the gauge's maximum value.

 

Minimum
Specifies the gauge's minimum value.

 

Shadow Type
Specifies the drawing style for the frame around the progress bar widget.

Shadow None - No frame is drawn.

Shadow In - Draws a frame such that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed.

Shadow Out - Draws a frame such that it appears outset.

 

Shadow Width
Specifies the width for the border

 

Show Percentage
Specifies the whether a label showing the percentage completed is shown in the progress bar. If true, then the string ‘X %’ is show in the progress bar, where X is the percentage of progress completed. If false, then no percentage label is shown.

 

Start Angle
Specifies the starting angle of the gauge in degrees (90 is the default).

 

Value
Specifies the slider current position along the scale, between minimum and maximum.

 

Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.

Example

The following example code creates a WkCircularGauge where the completed portion of the gauge is indicated by a red pie wedge. The widget has also be set up to show the percent completion and has been initialized with a value of seven (out of ten). This example corresponds to the top right image at the beginning of the WkCircularGauge section.

aWkCircularGauge := WkCircularGauge

createWidget: 'aWkCircularGauge'

parent: aCwForm

argBlock: [:w | w

x: 120;

y: 8;

width: 100;

height: 100;

foregroundColor: (CgRGBColor

red: 16rFFFF

green: 16r0

blue: 16r0);

showPercentage: true;

value: 7;

scale].

The next example code creates a WkCircularGauge reminiscent of a PacMan. The foreground and background colors have been set to blue and the completion indicator is in yellow. The minimum and maximum ranges have been set to 1 and 360 respectively. The start angle has been set to 30 degrees and the value has been set to 30. This example corresponds to the bottom middle image at the beginning of the WkCircularGauge section.

aWkCircularGauge3 := WkCircularGauge

createWidget: 'aWkCircularGauge3'

parent: aCwForm

argBlock: [:w | w

x: 84;

y: 124;

width: 60;

height: 60;

backgroundColor: (CgRGBColor

red: 16r0

green: 16r0

blue: 16rFFFF);

foregroundColor: (CgRGBColor

red: 16r0

green: 16r0

blue: 16rFFFF);

maximum: 360;

minimum: 1;

value: 60;

pieColor: (CgRGBColor

red: 16rFF00

green: 16rFF00

blue: 16r0);

startAngle: 30;

scale].