CapeSoft.Com
Clarion Accessories
Draw
Documentation
DrawGauge
Download Latest Version Index History
CapeSoft Logo

CapeSoft DrawGauge
Documentation

Installed Version Latest Version

Introduction

The DrawGauge class is based on the Draw class. It provides the base class for higher-level gauge drawings which allow you to easily create gauges in your program. It is compatible with iDash, and Gauges can be used as widgets on an iDash dashboard.

The DrawGaugeCircle class is based on DrawGauge. It is designed to help you create circular, or semi-circular gauges such as speedometers and so on.

DrawGauge, like the rest of Draw, supports both ABC and Legacy (Clarion) apps and will work the same in both environments.

JumpStart

  1. Make sure the Draw Global Extension is added to the application.
  2. Go to a window, populate the DrawGauge control onto it
  3. Fill in the template options. Most of them can be left "as default" however the ones you will need to set are;
    Needle Tab: NeedleValue. (This is the field containing the value for the Gauge.)
    Needle Tab: Minimum Angle / Maximum Angle. (See Angles for more on angle values.)
    Value Tab: Minimum Value / Maximum Value. This sets the "range" for the gauge.
    Title Tab: Show Title / Text. This is the title for the gauge.
    Circles Tab: Select a Quick Design.

Angles

When it comes to angles, Draw uses a co-ordinate system similar to a normal math co-ordinate system. In this system angles are measured anti-clockwise from 3 o'clock, so 3 o'clock is 0 degrees, 12 o'clock is 90 degrees and so on.

Most speedometers use a clock-wise motion to indicate higher values, and the resting zero value is at 6 o'clock.

In order to make the Gauge classes easier to use, the coordinate system for angles is the Speedometer one, not the Draw one. A method (used internally) called ConvertAngle is provided to convert from the Gauge coordinate system to the Draw coordinate system.

All angles are measured in tenths of a degree. In other words a value of 900 = 90 degrees.

A call to the method SetNeedleRange determines the minimum and maximum angles for the needle. It also specifies the maximum and minimum values for the gauge. This allows you to use the SetNeedleValue method (and not worry about angles at all) whenever the value changes.

Gauge Design

A gauge consists of the background and the needle. The background in turn consists of circles, tick marks at various points on the circles, and text labels for some or all of the tick marks. You can also specify a center spot, a title for the gauge and a displayable value.



The circle can consist of multiple parts, where each part may have a different color or width. Ticks can be placed at any point on (or near) the circle, and the ticks can be labeled or left unlabeled.

A number of methods (AddCircle, AddTicks, AddTick) are provided to allow these background parts to be easily defined, and added to the gauge.

The background color of the gauge is set via the property called BackgroundColor.

Various other properties set the position, and look, of the Title and Value components. Almost all the items are of course completely optional - a gauge could be reduced to simply a needle.

In addition the whole Draw drawing class is available, including all low-level drawing methods, so the background can be drawn onto with any Draw method. A method (DrawCustom) is provided for any extra draw commands that you may wish to add to the background.

Needle

A gauge consists of the background (circles, ticks, labels and so on) and the needle.

To change the value of the needle you can call a method called DrawNeedle.

If your value for the needle is a variable with the LONG data type then you can set the gauge to simply monitor that value. If the value changes then the gauge will automatically move its own needle as soon as an event happens on the window. For example, if the needle should monitor loc:progress then the code looks something like this;

gauge.NeedleValuePtr &= loc:progress

Use the SetNeedleRange method when setting up the gauge to set the minimum and maximum values, which in turn allows the class to convert the values into angles internally.

The look of the needle itself is determined by a number of properties.

The width of the needle (in pixels) and the color of the needle are set via NeedleWidth and NeedleColor respectivly.

The NeedleOffset determines where the needle ends. A value of 0 will end the needle on the outer edge of the circle. If this number is greater than 0 then it will extend beyond the edge of the circle by that many pixels. And if it is less than zero then it will end inside the circle by that many pixels. So, for example, if it is set to -10, and the width of the circle is 5, then the needle will end 5 pixels short of the circle's inner edge.

The NeedleLength property determines how long the needle is. If it is set to 0 then it will be drawn to the circle edge, taking the offset into account. The gauge circle may not be round (the shape of the image control determines the shape of the circle) so the needle may be a different length depending on where in the circle it is. If the length is set to a value other than zero, then the length will be fixed to that amount, regardless of the shape of the circle.

Layers

Background Layer

The background layer sits at the bottom of the drawing. The other layers are drawn on top of this one. You can use and Draw method to draw on this layer. for example;

gauge.WithLayer(self.BackgroundLayer)
gauge.SetPenColor(color:red)
gauge.SetPenWidth(1)
gauge.Box(self.gx,self.gy,self.gw,self.gh)

Dynamic Layer

The dynamic layer is reserved for all the components that have to be redrawn when the value of the gauge changes. So, for example, on a Circular gauge the dynamic layer holds the needle and the text value. If you draw on this layer then you need to also draw the same components on the DynamicAlpha layer, in color:black. For example;

gauge.WithLayer(self.DynamicLayer)
gauge.SetFontColor(color:red)
gauge.SetFontStyle(font:bold)
gauge.Show(self.gx,self.gy,'!')
gauge.WithLayer(self.DynamicAlphaLayer)
gauge.SetFontcolor(color:black)
gauge.Show(self.gx,self.gy,'!')

Top Layer

The top layer sits on top of the dynamic layer, but it contains items that do not need to be redrawn when the value changes. For example, in a circular gauge the center spot is above the needle, and hence is on the top layer. If you draw on this layer then you also need to draw the same item on the TopAlpha layer, in the color black. For example;

gauge.WithLayer(self.TopLayer)
gauge.SetPenColor(color:green)
gauge.Line(self.gx,self.gy,self.gw,self.gh)
gauge.WithLayer(self.TopAlphaLayer)
gauge.SetPenColor(color:black)
gauge.Line(self.gx,self.gy,self.gw,self.gh)

 

Template

Draw provides a control template, which allows you to quickly and easily add a gauge to your window without needing to write any code, or call any of the methods directly.

Global Extension

Before you can use the DrawGauge template on a window you will need to add the Draw Global Extension to the application. To do this go to the Global Extensions section of your application, click on Insert and select the Draw global extension. all of the settings can be left at their default values at this point, with the exception of the Multi-DLL tab (if you are working in a multi-app program.)

If you are working in a program that consists of multiple app files, then you will need to set the settings on the Mutli-DLL tab correctly in your Data DLL, other DLL's and EXE's. See https://www.capesoft.com/accessories/standards.htm#MultiDLLApplications for more information.

Once the global extension template has been added then you are ready to add gauges to your application.

Control Template

To add a gauge control on a window;
  1. Go to the Window Designer
  2. Go to the Control Templates Pad.
  3. Click on the DrawGauge item in the Draw section
  4. Click on the window where you want the gauge control to be.
  5. Once added the control can be positioned and sized as desired.
  6. Right-Click on the control and select Actions to see the template settings for the control.

General Tab

Tip (Dashboard Only)
Allows you to specify a tip for the Gauge when it's used as a widget on a dashboard.
Do not generate this object
This disables the template in this window and no template code for the control will be generated. (the control itself will remain on the screen.) This setting is useful for debugging.

Needle Tab

Needle Value (LONG)
A field or variable which is declared as a LONG. If this template setting is set then the gauge will automatically update when the value in the field changes. If the value is not in a convenient LONG then you can use the DrawNeedle method to set the needle whenever you want the needle value to change.

If you are using the gauge as a widget on a dashboard, then the variable has to have Global scope. If you do not set anything here, then the wValue parameter (if it exists) will be used as the value. If the wValue is changed via a call to .SetOption then the needle will automatically change as well.
Unit
The default value for needle settings is in tenths of a degree measured clockwise from 6 o'clock. The range for this unit is 0 to 3600, although it is also bound by the MinAngle and MaxAngle properties. If this setting is set to Percentage then the value for the needle settings is 0 to 100 inclusive.
Color
The color of the Needle.
Width
The width, in pixels, of the needle.
Offset
The offset of the needle in pixels. More more information on the needle offset see the Needle section.
Length
The length of the needle in pixels. If 0 then the length will adjust to the shape of the gauge.

Settings Tab

Padding
The amount of white-space, as a percentage of the drawing size, to leave around the edge of the circle. The default value is 5, meaning 5% padding.
Semi Circle
If this is on then the gauge is a semi circle (from 90 degrees to 270 degrees) instead of a full circle.

Circles Tab

The gauge itself consists of a circle around the edge of the gauge. This circle can consist of multiple arcs, and each arc of the circle can be a different color, a different width, and so on.
Start Angle
The starting angle of this arc. This value is in tenths of a degree, so 900 = 90 degrees.
End Angle
The ending angle of this arc. This value is in tenths of a degree, so 900 = 90 degrees.
Color
the color of this arc.
Width
The Width of this arc, in pixels.

Ticks Tab

Around the circle you can draw Ticks - little markers that indicate graduations. To make adding ticks easier it is possible to add multiple ticks with a single setting in the template.
From Angle
The angle to draw the tick at. (If the To Angle setting is entered, then this setting is the angle for the first tick in the set.)
To Angle
If you wish to add multiple ticks then put the angle of the last tick here.
By
If you are adding multiple ticks then enter the gap between ticks here. This is in hundredths of a degree so 100 = a tick every 10 degrees.
Color
the color of the tick.
Width
The width, in pixels, of the tick.
Offset
The offset of the tick in pixels from the outer edge of the circle. A positive value (more than 0) indicates the tick is outside the circle. A negative value moves the tick inside the circle.
Length
The length of the tick, in pixels.
Label(s)
The label to be draw with the tick. If you are creating multiple ticks then this label is a tilde (~) separated list of labels.
Label Offset
The offset of the label position, relative to the outside of the circle.
Label Font Size
The Font size for the label. If omitted then the font size for the window is used.
Label Font Color
The Font Color for the label.

Classes Tab

Object name
The name of this gauge object.
Class name
The class to use for this gauge object. Default is DrawGaugeCircle.



How To

Use an Image as a Background

Note this example makes use of DrawImage. To activate that in your application see here.

In some cases it may be desirable to use an image file (BMP, PNG or whatever) as the background to a gauge. You can then draw circles, ticks, title and center on top of that, or not as you choose. The background could contain the drawing of a gauge, or it may just be a design of some sort which you want to use.

The needle will appear as usual "above" the background, and the "Center" will appear as usual "above" the needle.

The following code should be embedded in the DrawCustomBackground method. This is called before the other background properties (Circles, Ticks, Title) are drawn. If you added this code to the DrawCustom method then it would override the circles, ticks and title.

self.WithLayer(self.BackgroundLayer)
self.diReadImage('background.png',0,0)

The WithLayer command tells it to load the image onto the background layer.
The diReadImage command loads the image itself.

Note that diReadImage makes use of the Clarion FreeImage template and DLL. So you will need to
  1. Add the Activate Clarion FreeImage global extension to the application
  2. On the Draw Global extension, Options tab, tick on the option to Activate DrawImage

Basic Example

A gauge consists of a background (which can include circles, parts of circles, tick marks and labels) plus a needle for showing the current value. Here is an annotated example if setting up such a gauge.

gauge.Start()

All gauges should start with a call to Start. This refreshes the object an makes it easier to use one object to display multiple gauges.

gauge.SetPadding(10,10,10,10,true) 

The padding is the gap between the gauge and the edge of the control. these are percentage values, so in this case a 10% gap all around the gauge is maintained. In this example a fifth parameter indicates that the gauge is a semi-circle, not a full circle.

gauge.AddCircle (900,2000,color:Green,25)
gauge.AddCircle (2000,2700,color:Maroon,25)

These lines add two Arcs to the background of the gauge. The first parameter is the start angle and the second is the end angle. Remember these are in tenths of a degree. The third parameter is the color. The final parameter is the width of the circle line.

gauge.AddTicks(900,2700,100,color:black,3,-35,10)

Multiple tick marks can be added to the gauge with a single call. In this case a small tick mark is placed around the edge of the circle every 10 degrees. (From 90 degress to 270 degrees, every 10 degrees, add a tick mark in black, with a width of 3 pixels. The ticks should be inside the (outside of the) circle by 35 pixels and each tick should be 10 pixels long.

gauge.AddTicks(900,2700,400,color:black,5,-35,20,'0~10~20~30~40~50',-70)

You can overwrite existing ticks with new values. In this case every fourth tick is being reset. the tick is wider (5 pixels), and longer (20 pixels). In addition these ticks are being labeled (using a tilde separated list) and are located at an offset of -70 to the outside of the circle.

needle = gauge.MinAngle
gauge.DrawGauge(needle)

The gauge is complete, and can be draw with the desired needle location. The needle is measured in tenths of a degree. The property .MinAngle contains the minimum angle of the circle (in this case 90 degrees) and the .MaxAngle property contains the maximum angle of the circle (in this case 270 degrees).

If the value of the needle needs to change then simple call

gauge.DrawNeedle(needle)


Method Reference

The DrawGauge class is derived from the Draw class, and all the methods and properties in that class are in scope here.

The DrawGaugeCircle class is derived from the the DrawGauge class, and so all the properties and the methods from DrawGauge (and Draw) classes are in scope in the DrawGaugeCircle Class.
DrawGuage Methods
Bounds Sets the boundaries for the gauge based on the current size of the Image control.
Design A method where all the components of the gauge design can be done in one place.
DrawCustom An empty method, provided to make custom drawing on the gauge possible.
DrawCustomBackground An empty method, provided to make custom drawing on the gauge possible.
DrawTitle Draws the title on the gauge. Do not call directly, call DrawGauge instead.
DrawValueText Draws the value text on the gauge.
DrawGauge Draw and display the whole gauge (Circles, Ticks, Labels, Title, Value and Needle)
Init Called to initialize the object to the Image control on the window.
Resize Call when the size of the Image control changes - this resets the object to match the new size.
SetPadding Sets the padding percentage
Start Called before you start using the object. This restores the object to "clean" initial settings, especially useful if you are reusing the object to display a completely different gauge.
TakeEvent Responds to any events (like Event:DoResize) which may require the gauge to respond.
ValueToText Allows for custom formatting of the value into text.
DrawGuageCircle Methods
AddCircle Add a circle (or part of a circle) to the background of the gauge.
AddTick Add a tick mark to the edge of the gauge.
AddTicks Add multiple ticks to the edge of the gauge.
ConvertAngle Convert an angle from the Gauge coordinate system to the Draw coordinate system.
DrawCenter Draws the center spot of the gauge on the top layer.
DrawCircles Draw all the circles on the background.
DrawNeedle Redraw just the needle on the gauge. This is called as the value of the gauge changes.
DrawTicks Draw all the ticks around the edge of the circles.
DrawTickLabel Draw all the labels on the gauge.
SetNeedleRange Sets the range for the needle.
SetNeedleValue Sets the value of the needle to a specific value. The needle is not drawn. Not usually called directly, use DrawNeedle instead.

AddCircle

AddCircle(LONG pStart, LONG pEnd, LONG pFillColor, LONG pWidth, LONG pOffset)

Description

Adds a circle, or circle segment to the gauge. A gauge can have multiple circle segments, so that different parts of the circle can be in different colors or different widths.

Parameters
Parameter Description
pStart The start angle of the circle segment. This value is in the range 0 through 3600. Angles are measured in tenths of a degree clockwise, from 6 o'clock.
pEnd The end angle of the circle segment. This value is in the range 0 through 3600. Angles are measured in tenths of a degree clockwise, from 6 o'clock.
pFillColor The color of the segment.
pWidth The width (in pixels) of the segment.
pOffset The distance (in pixels) from the outer edge of this circle, to the outer edge of the gauge. For example this is 0 for a circle on the edge of the gauge, and 10 for a circle which is inside the gauge by 10 pixels.
Returns

Nothing

Remarks



Examples
This picture

is achieved with the following two calls;

gauge.AddCircle (900,2000,0085A952h,25,0) ! green, from 90 degrees to 200 degrees
gauge.AddCircle (2000,2700,00324BCCh,25,0) ! red, from 200 degrees to 270 degrees

See Also

AddTick, AddTicks, DrawGauge

AddTick

AddTick(LONG pAngle, LONG pColor, LONG pWidth, LONG pOffset, LONG pLength, <String pLabel>, LONG pLabelOffset=0, LONG pFontSize=-1, LONG pFontColor=color:none)

Description

Adds a tick mark to the circle.

Parameters
Parameter Description
pAngle The angle, in tenths of a degree (900 = 90 degrees) where the tick should appear. Angles are measured clockwise, from 6 o'clock.
pColor The color of the tick.
pWidth The width (in pixels) of the tick.
pOffset The offset of the tick, in pixels, from the outer edge of the circle. A value of 0 means the tick will be draw from the outer edge of the circle towards the center of the circle. A value greater than 0 moves the tick outwards, away from the center, a value < 0 moves the tick inwards towards the center.
pLength The length of the tick mark in pixels.
pLabel [optional] The label to add to the tick mark. If omitted the label is not added to the tick.
pLabelOffset [optional] The offset of the center of the label, in pixels, from the outer edge of the circle. If omitted the value is 0.
pFontSize [optional] The size of the font to use. If omitted the window font size is used.
pFontColor [optional] the color of the font. If omitted, or set to color:none then the window font color is used.
Returns

Nothing

Remarks

Examples
! add a tick at 90 degrees, 5 pixels wide, 20 pixels long, 35 pixels inside the circle. Label it 10 and set the label inside the circle by 70 pixels.
gauge.AddTick(900,color:black,5,-35,20,'10',-70)

See Also

AddTicks, DrawGauge

AddTicks

AddTicks(LONG pFromAngle, LONG pToAngle, LONG pBy, LONG pColor, LONG pWidth, LONG pOffset, LONG pLength, <String pLabel>, LONG pLabelOffset=0, LONG pFontSize=-1, LONG pFontColor=color:none)

Description

Adds multiple tick marks to the circle at the same time. The parameters are (mostly) the same as for the AddTick method, however instead of a single angle a range of angles (and a step value) can be set here.

Parameters
Parameter Description
pFromAngle The starting angle, in tenths of a degree (900 = 90 degrees).
pToAngle The ending angle, in tenths of a degree (2700 = 270 degrees).
pBy The step value between ticks. (100 = every 10 degrees)
pLabel A tilde ( ~ ) separated list containing the labels for the ticks. If this parameter contains more labels than ticks then excess labels are simply ignored. If there are fewer labels, then the later ticks will have a blank label. If this parameter is omitted then all the labels are blank.
  See the AddTick method for a description of the other parameters.
Returns

Nothing

Remarks

Existing ticks can be changed using this method.

Examples

! add ticks at 10 degree intervals, from 90 degrees to 270 degrees, width 3, offset -35, length 10 pixels.
gauge.AddTicks(900,2700,100,color:black,3,-35,10)

! update ticks at 40 degree intervals, for 90 to 270 degrees, width 5, length 20 pixels, and label from 0 to 50.
gauge.AddTicks(900,2700,400,color:black,5,-35,20,'0~10~20~30~40~50',-70)


See Also

AddTick, DrawGauge

Bounds

Bounds()

Description

Sets the gx, gy, gw and gh properties to indicate the boundaries of the drawing area, based on the current values in the LeftPadding, RightPadding, TopPadding and BottomPadding properties and taking into account the current size of the image control. Sets the cx and cy properties to the center of the gauge - the place where the needle originates from.

Returns

Nothing

Remarks

Usually called internally when either the padding changes (via SetPadding) or the size of the control changes (via Resize).

See Also

SetPadding

Design

Design(LONG pDesign=0)

Description

This is a method which is provided as a convenient place to put all the calls to SetPadding, AddCircle, AddTicks, AddTick and SetNeedlAngle that are required to set the "look" of the gauge.

Parameters
Parameter Description
pDesign [optional] An optional parameter that allows you to include multiple designs in your method, and then use this parameter to switch between them. The DrawGaugeCircle class includes five built-in designs, DrawGauge:ProgressStyle, DrawGauge:ResourceStyle, DrawGauge:AudioStyle, DrawGauge:SpeedometerStyle and DrawGauge:LowHigh.
Returns

Nothing

Remarks

The template puts all the code which determines the "look" of the gauge into this method.

Example
self.SetPadding(10,10,10,10,true)
self.AddCircle (900,2000,0085A952h,25) ! green
self.AddCircle (2000,2700,00324BCCh,25) ! red
self.AddTicks(900,2700,100,color:black,3,-35,10)
self.AddTicks(900,2700,400,color:black,5,-35,20,'0~10~20~30~40~50',-70)
self.SetNeedleAngle(self.MinAngle)

See Also

AddCircle, AddTicks, AddTick, SetNeedleAngle

ConvertAngle

ConvertAngle(LONG pAngle)

Description

Converts an angle from the gauge frame of reference (clockwise from 6 o'clock) to the Draw frame of reference (anti-clockwise from 3 o'clock.) This is used internally where necessary. All gauge methods (described in the document) use the gauge frame of reference for angle values, but the other draw methods (including inherited methods which take angles) use the Draw frame of reference.

Parameters
Parameter Description
pAngle The angle value, in tenths of a degree to convert.

Returns

The angle suitable for use with the Draw methods which use a frame of reference starting at 3 o'clock and incrementing anti-clockwise.

Remarks

The reason for the difference in frames-of-reference is that gauges work universally by incrementing in a clockwise direction. It is a lot easier to draw circles and ticks if you are using this reference.

Examples
a = self.ConvertAngle(0)    ! a = 2700
a = self.ConvertAngle(900)  ! a = 1800
a = self.ConvertAngle(1800) ! a = 900
a = self.ConvertAngle(2700) ! a = 0

See Also


DrawCenter

DrawCenter()

Description

Draws the center spot of the circle.
 
Returns

Nothing

Remarks

The properties CenterColor and CenterRadius are used to determine the color and size of the spot respectively. The center is drawn onto the top layer, so is above the needle.
this method is not usually called directly, use DrawGauge instead.

See Also

DrawGauge

DrawCircles

DrawCircles()

Description

Draws the circles added by one or more calls to AddCircle. Called internally from DrawGauge. The drawing is not cleared before the circles are drawn.

Returns

Nothing

Remarks

Not usually called directly - use DrawGauge instead.

See Also

AddCircle, DrawGauge

DrawCustom

DrawCustom()

Description

This method provides a convenient place to embed custom drawing functions on the gauge after the circles, ticks and title are drawn.

Since the DrawGauge class is derived from the Draw class, all the drawing functions available in Draw are also available in DrawGauge. If you wish to add custom drawing routines then this is a good place to add them.

Returns

Nothing

Examples
! draw a circle at the center of the gauge
self.SetPencolor(color:maroon)
self.Ellipse(self.cx - 5, self.cy - 5, 10, 10)

! draw a box around the edge of the image control
self.SetPencolor(color:green)
self.SetPenWidth(3)
self.box(3,3,self.width-3,self.height-3)

See Also

DrawGauge, DrawCustomBackground

DrawCustomBackground

DrawCustomBackground()

Description

This method provides a convenient place to embed custom drawing functions on the gauge, before all the other background items are drawn. This is a good place to load a background image for the gauge, or to draw items which will be "behind" the circles, ticks and title.

Since the DrawGauge class is derived from the Draw class, all the drawing functions available in Draw are also available in DrawGauge.

Returns

Nothing

Examples
self.WithLayer(self.BackgroundLayer)
self.diReadImage('background.png',0,0)

See Also

DrawGauge, DrawCustom

DrawTitle

DrawTitle()

Description

Draws the Title on the gauage.

Returns

Nothing

Remarks

If the ShowTitle property is false, then the title is not displayed. This method does not clear the existing title from the gauge and hence is not usually called directly. Use DrawGauge instead.

See Also

DrawGauge

DrawValueText

DrawValueText(<String pValue>)

Description

This method draws the value text

Parameters
Parameter Description
pValue The formatted text to display.

Returns

Nothing

Remarks

This value is called from DrawNeedle, and is not usually called directly. The properties ValueX, ValueY, ValueW and ValueH are updated when this method is called.

See Also

DrawNeedle

DrawGauge

DrawGauge(<LONG pValue>)

Description

Clears the drawing surface (to self.backgroundcolor), then draws the circles, ticks, labels, title, vlaue and needle. The needle can then be moved, and the value updated, using calls to DrawNeedle.

Parameters
Parameter Description
pValue [optional] The value to set the needle to. This should be in the range between self.MinimumValue and self.MaximumValue. If omitted then the current value of Self.NeedleAngle is used.
Returns

Nothing

Remarks

Once the gauge has been created (by calls to AddCircle, AddTicks and AddTick) then it can be drawn using this method. If a static part of the gauge changes (circles, ticks, title, center, custom) then call this method to redraw the gauge.

 Examples
See Also

AddCircle, AddTicks, AddTick, DrawNeedle, DrawCustom

DrawNeedle

DrawNeedle(<LONG pValue>)

Description

This draws (or redraws) the position of the needle on the gauge. Call this method anytime that the need value changes. The width of the needle is determined by the NeedleWidth property, the color of the needle is determined by the NeedleColor property, and the offset of the needle is determined by the NeedleOffset property, the length of the needle is determined by the NeedleLength property.

Parameters
Parameter Description
pValue [optional] The value of the needle to draw. If omitted then the current value of Self.NeedleAngle is used.
Returns

Nothing

Remarks

Internally the gauge is constructed using layers. Since the needle is draw to its own layer, redrawing the needle does not result in a redraw of the whole gauge. Thus custom drawing on the gauge itself does not need to be redone when a needle value changes.

Examples
ThisGauge.DrawNeedle(progress)

 See Also

AddCircle, AddTicks, AddTick, DrawNeedle

DrawTicks

DrawTicks()

Description

Draws the ticks added by one or more calls to AddTicks or AddTick. Called internally from DrawGauge. The drawing is not cleared before the ticks are drawn.

Returns

Nothing

Remarks

Not usually called directly - use DrawGauge instead.

See Also

DrawGauge

DrawTickLabel

DrawTickLabel()

Description

Draws a tick label added by one or more calls to AddTicks or AddTick. Called internally from DrawTicks. The drawing is not cleared before the label is drawn.

Returns

Nothing

Remarks

Not usually called directly - use DrawGauge instead.

SSee Also

DrawGuage

Init

Init(LONG Control)

Description

Initializes the object to an image control on the window.

Parameters
Parameter Description
Control The use equate of an image control on the window.
Returns

Nothing

Examples
ThisGauge.Init(?SomeImage)
See Also

Start

Resize

Resize()

Description

Resets the boundaries of the gauge based on the current size of the image control. Can be called after an image control is resized. Is called automatically (via TakeEvent) on an event:DoResize.

Returns

Nothing

Examples
self.resize()

SetPadding

SetPadding(Long pLeft, Long pRight, Long pTop, Long pBottom, Long pSemi=false)

Description

Sets the padding around the gauge to allow for some space between the edge of the gauge circles and the edge of the control. Note that this does not apply to tick marks, or labels, only the circle itself. All values are measured as a percentage of the control width and height.

Parameters
Parameter Description
pLeft The percentage value to use for the left edge of the gauge.
pRight The percentage value to use for the left edge of the gauge.
pTop The percentage value to use for the left edge of the gauge.
pBottom The percentage value to use for the left edge of the gauge.
pSemi If set to false then the gauge is a full-circle gauge. If set to true then only angles from 900 to 2700 will be possible on the gauge.
Returns

Nothing

Remarks

Internally calls the Bounds method to set the gx, gy, gw and gh properties.

 Examples
self.setPadding(10,10,5,5,false)

See Also

Bounds

SetNeedleRange

SetNeedleRange(LONG pMinAngle, LONG pMaxAngle, REAL pMinValue, REAL pMaxValue)

Description

Sets the value of the needle. This method does not draw the needle. To set the needle, and draw it, use the DrawNeedle method instead.

Parameters
Parameter Description
pMinAngle The minimum angle for the gauge. Angles are measure in tenths of a degree, from 6 o'clock. Valid values are 0 through 3600.
pMaxAngle The maximum angle for the gauge.
pMinValue The minimum value for the gauge.
pMaxValue The maximum value for the gauge.

Returns

Nothing

Remarks

A fair number of the other methods use these properties either directly, or indirectly, so getting this call correct is important. By setting the ranges for the Angles, and Values, correctly the needle position can be correctly calculated when the value changes.

See Also

DrawNeedle

SetNeedleValue

SetNeedleValue(LONG pValue)

Description

Sets the value of the needle. This method does not draw the needle. To set the needle, and draw it, use the DrawNeedle method instead.

Parameters
Parameter Description
pValue The new value of the needle.

Returns

Nothing

Remarks

Once the gauge has been drawn, and is visible, then the needle should be updated with a call to DrawNeedle. However this method can be used to set the initial needle value when the gauge is being constructed.

This method calculates the new angle for the needle. If this angle is less than self.Minangle then  the needle is set to self.MinAngle. If this value is greater than self.MaxAngle then the needle is set to self.MaxAngle.

See Also

DrawNeedle

Start

Start()

Description

Returns the object back to the point as if it has just been created. This allows a single object to be reused, without there being side-effects from previous uses of the object.

Returns

Nothing

Remarks

This method should be used if you allow the user to change the look or style of the gauge at runtime. Rather than trying to undo earlier settings (circles, ticks, labels and so on) the object can be "cleaned" back to the original state simply by calling this method.

EEExamples
self.start()

TakeEvent

TakeEvent()

Description

This method call should be added to your event loop for the window. It allows the gauge control to respond to events

Returns

0 if event processing should continue for this event. If not 0 then processing for this event should not continue.

Remarks

Responds to EVENT:DoResize events on the window to redraw the gauge. This method does not resize the gauge control.

Examples
If ThisGuage.TakeEvent() then cycle.

See Also

Resize

ValueToText

ValueToText(Long pValue)

Description

Generates the text version of the value, based on the number. By default applies the ValuePicture property to the value.

Parameters
Parameter Description
pValue The value to be formatted

Returns

String. The formatted value.

Remarks

This is a good place to embed code if the formatting of the value requires more than the application of a single clarion picture.

Examples
self.start()

Properties

Properties
BackgroundColor Long The background color for the gauge. defaults to color:white. You can change this property at any time, call the DrawGauge method to see the change take effect.
BackgroundLayer Long The layer number for the background (which includes the circles, and ticks.) Do not change this value. However if you are drawing on the background using other Draw methods, then you will need to do a
thisDraw.WithLayer(thisDraw.BackgroundLayer)
before doing any drawing. See Layers.
BottomPadding
LeftPadding
RightPadding
TopPadding		 Long Set via the SetPadding method. Is a percentage of space between the gauge and the edge of the image control.
CenterColor Long The color of the center spot of the gauge.
CenterRadius Long The radius of the center spot of the guage.
CircleQueue DrawCircleQueueType A queue of all the circle segments added with AddCircle.
Circles Long Contains the number of circle segments that have been added via calls to AddCircle.
cx
cy		 Long The center of the circle.
Dynamic Layer Long Items on the dynamic layer are redrawn whenever the value of the gauge changes. See Layers.
DynamicAlphaLayer Long This is the alpha layer for the Dynamic layer. If you draw on the dynamic layer you also need to draw on this layer. See Layers.
gx
gy
gw
gh		 Long The boundaries of the gauge area, inside the image control, after being adjusted for the padding.
MaxAngle Long The maximum angle for the circle. Automatically set when the circle segments are added via AddCircle.
MaxValue Real The maximum value for the gauge.
MinAngle Long The minimum angle for the circle. Automatically set when the circle segments are added via AddCircle.
MinValue Real The minimum value for the gauge.
NeedleAngle Long The angle of the needle. To change the needle angle at anytime call
thisDraw.DrawNeedle(newAngle)
NeedleColor Long The color of the needle. Defaults to color:Gray. Can be changed at any time. Call the DrawNeedle method to see the change take effect.
NeedleLength Long The length of the needle. If 0 the it is set to the distance from the center of the gauge to the outside of the circle. If set to a specific value (in pixels) then it will be that long, regardless of the shape of the circle.
NeedleOffset Long The offset of the needle base from the center of the circle. If set to a value then the internal end of the need will stop short of (if <0) or beyond (if >0) the circle center.
NeedleValuePtr &Long A pointer to a Long variable that contains the desired needle value. If the variable changes, then the gauge automatically updates the needle to that value on the next window or control event. If the needle value is not in a Long then use the SetNeedleAngle method, and leave this property set to NULL.
NeedleWidth Long the width in pixels of the needle. Defaults to 3 pixels.
Semi Long Default is FALSE. Set to TRUE  if the gauge is a semi-circle rather than a full circle. Set via the SetPadding method.
ShowLabels Long If FALSE then the labels as set via the AddTicks and AddTick methods are not drawn.
ShowTicks Long If FALSE then the ticks as set via the AddTicks and AddTick methods are not drawn.
ShowTitle Long If set to TRUE then the title text is displayed in the gauge. See Gauge Design.
ShowValue Long If set to TRUE then the value text is displayed on the Dynamic layer of the gauge. When the value changes this text is redrawn.
TickQueue DrawTickQueueType A queue of all the ticks and labels added with AddTicks and AddTick.
TitleFontName, TitleFontSize, TitleFontColor, TitleFontStyle String, Long, Long, Long The font properties of the title string. If you change any of these after the gauge is already drawn then call the DrawGauge method to refresh the title.
TitleText String The text to display in the title position, on the background layer. If you change this after the gauge is drawn then call DrawGauge to refresh the text.
TitleX, TitlyY, TitleW, TitleH Long The position of the title text, in the control, after it has been drawn. These properties should be treated as "read-only" - they are not used internally by the class, however they are set (for your convenience) when a title is drawn. This allows you to draw other items manually near the title text.
TitleYP Long The position of the title, as a percentage of the height of the gauge. Valid values for this are 0 through 100.
TopLayer Long The layer which sits above the Dynamic layer. Items drawn on this layer also need to be drawn, in black, on the TopAlphaLayer. See Layers.
TopAlphaLayer Long The Alpha layer for the Top layer.
ValueFontName, ValueFontSize, ValueFontStyle, ValueFontColor String, Long, Long, Long The font properties for the value string.
ValuePicture String The value can be formatted using a Clarion picture before it is displayed. If this property is set then this picture will automatically be applied.
ValueText String The text value to display.
ValueXP, ValueYP Long The X and Y position of the value text, as a percentage of the width and height of the gauge.
ValueX, ValueY, ValueW, ValueH Long The position of the value text, in the control, after it has been drawn. These properties should be treated as "read-only" - they are not used internally by the class, however they are set (for your convenience) when a value is drawn. This allows you to draw other items manually near the value text.