OCX Controls & software technologies

Precision Round Gauge

Version 1.1

Overview

Purpose
Precision Round Gauge is a powerful OCX control for you application which displays a value using an indicator on a curved graduated bar that covers up to an angle of 360°.
Optimization
Precision Round Gauge was written entirely in C++ and is composed of strongly optimized code. The only required libraries are the MFC and MSVCRT DLLs, that are shipped with every version of Microsoft Windows. You do not need to add any additional component to your application distribution kit.
Small size
Precision Round Gauge is only 50k in size ! This means that it is very fastly loaded at runtime into your application and it does not significantly increase your final application size.
High customisability
Precision Round Gauge has 42 parameters you can set. For example it is possible to set the color of every single graphical element, the font of every written text, the number of divisions, the geometry and the layout of the components, the line thickness and so on.
Graphics
Precision Round Gauge makes no use of fixed-size bitmaps ! Every component you see, is dynamically scaled according to the container window size and to user's choices !
Flicker-free refresh
Precision Round Gauge makes use of a double-buffering technology in order to avoid unpleasant flickering effects: every graphic manipulation is done in memory and only eventually the final result is transferred to the video buffer, using all the available hardware optimizations that the graphic card provides for the BitBlt.
Any special requirement ?
If you are developing an application and found Precision Round Gauge nearly perfect for you needs except for small details, please feel free to contact us: let's talk about it !
Documentation
All the documentation you may need on Precision Analog Meter is on line ! We have prepared a detailed quoted and printable diagram, available in multiple formats, to which you can refer to better exploit the full power of the geometry parameters.

Quick start

You can start using Precision Round Gauge incredibly fast: the control default factory parameters are already sensible for a basic use, you have only got to:

If you are using the full version (NOT the trial one) you must call the SetLicense method passing your license number as argument and make sure it returns True. Simply ignore this step if you are testing the trial version.
Set the MinimumValue and the MaximumValue properties to the desired values.
Set the GreenStartValue, YellowStartValue and the RedStartValue properties to appropriate values. Set all them to the value assumed by MaximumValue if you do not want colored sections.
Set your current Value over and over again.

Now you can take a more accurate look at the properties to fully exploit the power of Precision Level Indicator.

Properties

BackColor
Domain: any color
Default value: 0x00C0C0C0
Meaning: this is the color used to fill the back plane of the control. This is actually visible only if the enclosing circle (refer to the diagram) does not cover the full area of the bounding box rectangle.
This value can be dynamically varied to convey easy-readable status information to the user.
BackgroundPicture
Domain: any image
Default value: (none)
Meaning: this is the picture which is drawn on the back plane of the control. If you set this property to an image, that image will be stretched in order to completely fill the bounding box. If you want to completely avoid the slight image degradation due to the stretching, use only images whose sizes are exactly corresponding to control bounding box.
If you only want a solid color on the back plane, do not select any image.
This value can be dynamically varied to convey easy-readable status information to the user.
Caption
Domain: any text string
Default value: ... (it depends on your development environment)
Meaning: this is the fixed text written on the control. This text is drawn used the CaptionColor and CaptionFont properties.
CaptionColor
Domain: any color
Default value: 0x00FFFFFF (white)
Meaning: this is the color used to draw the caption text.
CaptionFont
Domain: any font
Default value: Arial, 14, Bold Italic
Meaning: this is the font used to draw the caption text.
DivisionLineThickness
Domain: any integer number (small)
Default value: 2
Meaning: this is the thickness of the small segments which represent the division measuring marks. These marks are usually accompained by text labels which indicates the value there assumed by the quantity you want to represent.
EnclosingCircleColor
Domain: any color
Default value: 0x00000000 (black)
Meaning: this is the color used to fill the enclosing cirle (refer to the diagram).
EndAngle
Domain: a meaningful real number
Default value: -45
Meaning: this is the angle, expressed in degrees, with respect to the instrument X axis (as indicated on the diagram; positive if counterclockwise, negative clockwise) in which the instrument graduated bar ends. The instrument graduated bar extends from the StartAngle to the EndAngle along a clockwise direction.
ExternalCircleThickness
Domain: an integer number (small)
Default value: 2
Meaning: this is the thickness of the line used to draw the instrument graduated bar external circle segment.
ForeColor
Domain: any color
Default value: 0x00000000
Meaning: this color is not currently used; the property has been reserved for future features; its value is ignored.
GreenColor
Domain: any color
Default value:0x0000FF00
Meaning: this is the actual color used to fill the second section of the instrument graduated bar (which is usually drawn in green in real instruments). This colored section will be actually visible only if the value assumed by the GreenStartValue property is less than the value assumed by the YellowStartValue and RedStartValue.
GreenStartValue
Domain: a real number between MinimumValue and MaximumValue
Default value:60
Meaning: this is the starting value for the second section of the instrument bar (which is usually drawn in green, or the color indicated by the GreenColor property). If you try to set this property to a value that is out of the MinimumValue-MaximumValue range, it will be set to the nearest bounding value. This colored section ends at the beginning of the following one or, to be more precisely, at the YellowStartValue.
IndexColor
Domain: any color
Default value: 0x003030FF (light red)
Meaning: this is the color used to fill the instrument index (the isosceles triangle which indicates the current value of the quantity you want to represent).
This value can be dynamically varied to create animation effects or to convey further information.
IndexLineThickness
Domain:
Default value: 0 (very thin)
Meaning: this is the color used to draw the borders of the isosceles triangle which represents the instrument index.
MaximumValue
Domain: any real number
Default value: 100
Meaning: this is the maximum value you will allow the CurrentValue to assume.
MinimumValue
Domain: any real number
Default value: 0
Meaning: this is the minimum value you will allow the CurrentValue to assume.
NumberColor
Domain: any color
Default value: 0x00FFFFFF (white)
Meaning: this is the color used to draw the text labels which accompany the division measuring marks and indicate tha value there assumed.
NumberFont
Domain: any font
Default value: MS Sans Serif, 8, Normal
Meaning: this is the font used to draw the text labels which accompany the division measuring marks.
NumberOfDivisions
Domain: any integer number (small)
Default value:20
Meaning:this is the number of divisions in which the full range between MinimumValue and MaximumValue is divided, with the use of measuring marks. Division marks are usually accompained by text labels, which indicate the corresponding values there assumed by the quantity you want to represent.
NumberOfSubdivisions
Domain: any integer number (small)
Default value:2
Meaning:this is the number of subdivisions in which every division is furtherly divided. Subdivision marks are not accompained by text labels.
RedColor
Domain: any color
Default value:0x000000FF (red)
Meaning: this is the actual color used to fill the fourth section of the instrument graduated bar (which is usually drawn in red in real instruments). This colored section will be actually visible only if the value assumed by the RedStartValue property is less than MaximumValue.
RedStartValue
Domain: a real number between MinimumValue and MaximumValue
Default value:90
Meaning:this is the starting value for the fourth section of the instrument bar (which is usually drawn in red, or the color indicated by the RedColor property). If you try to set this property to a value that is out of the MinimumValue-MaximumValue range, it will be set to the nearest bounding value. This colored section ends at the value assumed by MaximumValue.
RelativeCaptionX
Domain: any real number (recommended between 0 and 1)
Default value: 0.5
Meaning: this is the ratio between the caption X coordinate (refer to the diagram) and the bounding box width. Increase this value to move the caption text to the right, decrease it to move it to the left. Choose an appropriate value, with respect to the chosen CaptionFont and Caption string, in order not to overflow the control bounding box borders.
This value can be dynamically varied to create text-scrolling animation effects.
RelativeCaptionY
Domain: any real number (recommended between 0 and 1)
Default value: 0.7
Meaning: this is the ratio between the caption Y coordinate (refer to the diagram) and the bounding box height. Increase this value to move the caption text to the bottom, decrease it to move it to the top of the control bounding box. Choose an appropriate value, with respect to the chosen CaptionFont and Caption string, in order not to overflow the control bounding box borders.
This value can be dynamically varied to create text-scrolling animation effects.
RelativeCenterX
Domain: any real number (recommended between 0 and 1)
Default value: 0.5
Meaning: this is the ratio between the center X coordinate (refer to the diagram) and the bounding box width. Increase this value to move the whole instrument (the graduated circle, the pointer, the division and subdivision marks and the associated text labels) to the right, decrease it to move it to the left. Choose an appropriate value, with respect to the chosen RelativeIndernalRadius and RelativeExternalRadius in order not to overflow the control bounding box borders.
This value can be dynamically varied to create animation effects.
RelativeCenterY
Domain: any real number (recommended between 0 and 1)
Default value: 0.5
Meaning: this is the ratio between the center Y coordinate (refer to the diagram) and the bounding box height. Increase this value to move the whole instrument (the graduated circle, the pointer, the division and subdivision marks and the associated text labels) to the bottom, decrease it to move it to the top of the control bounding box. Choose an appropriate value, with respect to the chosen RelativeIndernalRadius and RelativeExternalRadius in order not to overflow the control bounding box borders.
This value can be dynamically varied to create animation effects.
RelativeEnclosingCircleRadius
Domain: any real number (suggested between 0 and 1)
Default value: 0.98
Meaning: this is the ratio between the enclosing circle radius as reported on the diagram and the minimum of the two bounding box sizes. Increase this value to enlarge this circle (possibly making it overfilling the bounding box), decrease this value to make it smaller:

if this value is less than 0.5, the enclosing circle will be fully visible and never truncated;
if this value is exactly 0.5, the enclosing circle will occupy the maximum possible surface without being truncated by the bounding box borders;
if this value is greater than 0.5, the enclosing circle will be partially truncated and its circumference will be visible only near the bounding box angles;
if this value is near to 1, the enclosing circle circumference, will be all out of the bounding box, and the enclosing circle will be actually used to paint the instrument back plane.

RelativeExternalRadius
Domain: any real number (suggested between 1 and 2)
Default value: 1.1
Meaning: this is the ratio between the external circle radius and the internal circle radius (refer to the diagram).

set this property to 1 in order to reduce the instrument graduated bar to a single line. This annihilates the division and subdivision marks, and the colored sections, visibly simplifying the instrument;
set this property to approximately 1.1 to obtain a normal graduated bar;
set this property to a big value (approx. 10) to make the graduated bar overflow the instrument, therefore obtaining an interesting graphic effect;
it is inadvisable to set this property to a value less than 1.

RelativeIndexBackLength
Domain: any real number (suggested between 2 and -2)
Default value: 0.3
Meaning: this is the ratio between the index back length and the internal circle radius (refer to the diagram). Experiment your own combinations of RelativeIndexBackLength, RelativeIndexLength and TailAngle: setting this properties to suitable values, you can obtain an index (indicating isosceles triangle) pointing from the center of the instrument towards the exterior, or the opposite.
RelativeIndexLength
Domain: any real number (suggested between 2 and -2)
Default value: 1.2
Meaning: this is the ratio between the index length and the internal circle radius (refer to the diagram). Same considerations as the preceeding property apply.
RelativeInternalRadius
Domain: any real number (suggested between 0.1 and 0.5)
Default value: 0.35
Meaning: this is the ratio between the internal circle radius and the minimum of the two bounding box sides (refer to the diagram). The internal circle is one of the two circles whose sectors make up the graduated bar. Increase this number to enlarge the graduated bar, decrease it to make it smaller.
RelativeTextRadius
Domain: any real number (suggested between 0.5 and 2)
Default value: 1.2
Meaning: this is the ratio between the text radius and the internal circle radius (refer to the diagram). The text radius is the radius of the circle on which centers of the text labels associated to division measuring marks are positioned.
ScaleCircleColor
Domain: any color
Default value: 0x00FFFFFF (white)
Meaning: this is the color used to draw the circle sectors which make up the instrument graduated bar.
StartAngle
Domain: a meaningful real number
Default value: 225
Meaning: this is the angle, expressed in degrees, with respect to the instrument X axis (as indicated on the diagram; positive if counterclockwise, negative clockwise) in which the instrument graduated bar start. The instrument graduated bar extends from the StartAngle to the EndAngle along a clockwise direction.
StepValue
Domain:any real number (recommended less than or equal in modulus to the difference between MaximumValue and MinimumValue).
Default value:1
Meaning: this is the increment value added to Value every time the StepIt method is invoked. You can set a negative increment, thus causing a decrement every time StepIt is called.
SubdivisionLineThickness
Domain: any integer number (small)
Default value: 2
Meaning: this is the thickness of the small segments which represent the subdivision measuring marks. These marks are not usually accompained by text labels, whereas division ones do.
TailAngle
Domain: a meaningful real number
Default value: 165
Meaning: this is the angle (expressed in degrees) reported on the diagram as tail angle. Looking at the diagram it can be very easy to understand how variations to this parameter can affect the shape and size of the instrument index (the pointer).
Value
Domain: any real number (recommended betweem MaximumValue and MinimumValue).
Default value: 0
Meaning: this is the actual value you want to represent with the control. This value can be greater than MaximumValue and less than MinimumValue: in this cases the instrument will behave exactly like real istruments, which can be brought out of range (eventually damaging them): the index (the pointer) will move on, reaching zones out of the graduated bar and possibly finishing in an unexpected position after completing some revolutions.
ValueFormatString
Domain: any appropriate format string (see below)
Default value: %.0f
Meaning: : this string tells to the control how to format the text inside the labels located near the division measuring marks; this is a standard C "printf()-style" format string, but do not worry if you do not know C programming language, every information you will need is hereby given.

If you do not want text labels on your control, you can simply set this property to an empty string.
If you want to specify simple text strings (constant), set this property to the desired string (strings are replicated many times unchanged).
Otherwise, you can use a format string composed by a preceeding text, then the placeholder for the value and a following text. The placeholder itself is composed of

a leading percent sign, followed by
an (optional) padding size indicator (the number of total characters which compose the number representation, including digits, spaces and punctuation); if you put a zero "0" before this indicator, the padding character is the zero, otherwise the space is used;
an (optional) precision indicator,preceeded by a dot (the number of digits after the decimal point; set it to 0 if you want integer values);
and an "f" character, which stands for "floating point value".

Examples are provided in the following table. Since the percent character is used to indicate the placeholder, if you want to represent the percent sign itself, you will have to use two percent signs.

Format string Result
%f 50.000000
value=%f value=50.000000
value=%.1f value=50.0
%.2f percent 50.00 percent
%06.2f 050.00
%.0f %% 50 %
blah %3.0f blah blah 50 blah

YellowColor
Domain: any color
Default value: 0x0000FFFF (yellow)
Meaning: this is the actual color used to fill the third section of the instrument graduated bar (which is usually drawn in yellow in real instruments). This section will be actually visible only if the value assumed by the YellowStartValue property is less than RedStartValue and less than MaximumValue.
YellowStartValue
Domain: a real number between MinimumValue and MaximumValue
Default value: 75
Meaning: this is the starting value for the third section of the instrument graduated bar (which is usually drawn in yellow, or the color indicated by the YellowColor property). If you try to set this property to a value that is out of the MinimumValue-MaximumValue range, it will be set to the nearest bounding value. This colored section ends at the beginning of the following one or, to be more precisely, at the RedStartValue. If you do not want a yellow section, set this property to the same value of RedStartValue.

Methods

SetLicense(long LicenseNumber)
Parameters: LicenseNumber, a long integer number which represent your license number.
Return value: a boolean value that represents the result of the authentication.
Meaning: this method is used to activate the full-version control. You should call this method before calling any other method, passing the license number you obtained at purchase time as LicenseNumber parameter, otherwise the control will not draw itself on the screen.
Attention: you do not need to use this method using the trial version of the control.
StepIt
Parameters: none
Return value: none
Meaning: calling this method, you cause the increment of the Value property by StepValue.

Version History

Version 1.1
Fixed a variable initialization bug which, under certain development environments, caused a crash the second time the control is initialized.

Version 1.0

Initial release.

Purpose
	Precision Round Gauge is a powerful OCX control for you application which displays a value using an indicator on a curved graduated bar that covers up to an angle of 360°.
Optimization
	Precision Round Gauge was written entirely in C++ and is composed of strongly optimized code. The only required libraries are the MFC and MSVCRT DLLs, that are shipped with every version of Microsoft Windows. You do not need to add any additional component to your application distribution kit.
Small size
	Precision Round Gauge is only 50k in size ! This means that it is very fastly loaded at runtime into your application and it does not significantly increase your final application size.
High customisability
	Precision Round Gauge has 42 parameters you can set. For example it is possible to set the color of every single graphical element, the font of every written text, the number of divisions, the geometry and the layout of the components, the line thickness and so on.
Graphics
	Precision Round Gauge makes no use of fixed-size bitmaps ! Every component you see, is dynamically scaled according to the container window size and to user's choices !
Flicker-free refresh
	Precision Round Gauge makes use of a double-buffering technology in order to avoid unpleasant flickering effects: every graphic manipulation is done in memory and only eventually the final result is transferred to the video buffer, using all the available hardware optimizations that the graphic card provides for the BitBlt.
Any special requirement ?
	If you are developing an application and found Precision Round Gauge nearly perfect for you needs except for small details, please feel free to contact us: let's talk about it !
Documentation
	All the documentation you may need on Precision Analog Meter is on line ! We have prepared a detailed quoted and printable diagram, available in multiple formats, to which you can refer to better exploit the full power of the geometry parameters.

SetLicense(long LicenseNumber)
	Parameters: LicenseNumber, a long integer number which represent your license number. Return value: a boolean value that represents the result of the authentication. Meaning: this method is used to activate the full-version control. You should call this method before calling any other method, passing the license number you obtained at purchase time as LicenseNumber parameter, otherwise the control will not draw itself on the screen. Attention: you do not need to use this method using the trial version of the control.
StepIt
	Parameters: none Return value: none Meaning: calling this method, you cause the increment of the Value property by StepValue.

Version 1.1
	Fixed a variable initialization bug which, under certain development environments, caused a crash the second time the control is initialized.
Version 1.0
	Initial release.