OCX Controls & software technologies

Precision Analog Meter

Version 1.1

Overview

Purpose

Precision Analog Meter is a powerful OCX control for you application which displays a value using an indicator on a curved scale that covers up to an angle of 180°.

Optimization

Precision Analog Meter 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 Analog Meter is only 50k in size ! This means that it is very fastly loaded into your application and it does not significantly increase your final application size.

High customisability

Precision Analog Meter has 30 parameters you can freely set to fully customise the graphic appearance and functionality of the control. For example it is possible to set the color of every single graphical element, the font and the format of every written text, the number of divisions, the geometry and the layout of the components, the line thickness and so on.

Graphics

Precision Analog Meter 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 Analog Meter 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.

Unicode version available

Even if the standard version of Precision Analog Meter is able to handle DBCS and MBCS to help you creating localized projects under Windows 9X, a unicode version is available for your strongly localized projects under Windows NT. Choose the version of Precision Analog Meter that best fits to your needs !

High speed version available

Are you developing a realtime application ? We could provide you with a high performance, simplified-graphics version of our control (without double-buffering) that can reach an update frequency of 100 Hz and more !

Any special requirement ?
If you are developing an application and found Precision Analog Meter 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.

Trial Version & Licensing

A trial version is available: it includes all the functionality with only the following restrictions:

a red cross will appear in the middle of the bounding box control;
a nag screen will keep you waiting three seconds;
it will not be possible to change the control caption, it will instead be fixed to "Trial Version"
only the first 33 operations will be performed, every succeeding request will be ignored;
You can freely evaluate the trial version by including it in your projects as if it was the full-functionality version. When you will decide to buy it, you will only have to register the full-functionality version in place of the trial version, with no modifications to your program (you even won't need to recompile it).
A container test project (called TryAnalogMeter) is provided in order to let you experiment with some of the control properties.
Once you decide to purchase the full version of the control, a license number will be provided, which can be used to unlock the control at run-time.

Quick start

You can start using Precision Analog Meter 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 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

BackgroundImage

Domain: any picture
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, the 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 set the ShadedAreaRelativeSize to zero, the image you select will be fully visible, otherwise borders will be partially covered by the shaded borders which represent the sunken bevel.
If you only want a solid color on the back plane, do not select any image.

BottomCoverColor

Domain:any color
Default value:0x00000000 (black)
Meaning: this is the color used to fill the rectangle which covers the lower part of the control. Warning: if the BottomCoverRelativeHeight property is set to zero, the bottom cover rectable is not visible, and this parameter is ignored.
BottomCoverLabelFont
Domain: any font
Default value:MS Sans Serif, 12, Normal
Meaning: this is the font of the text label which is drawn upon the bottom cover. The text label is centered in the bottom cover, therefore you should choose a value for this property which is appropriate for the current value of BottomCoverRelativeHeight, in order not to overfill the bottom cover rectangle.
BottomCoverRelativeHeight
Domain: a real number between 0 and 1
Default value:0.2
Meaning: this is the ratio between the bottom cover height and the control bounding box height (as you can see on the diagram). If you set this property to zero, the bottom cover will not be visible; if it is set to 0.5 it covers the lower half of the control, and so on.
BottomCoverTextColor
Domain: any color
Default value:0x00FFFFFF (white)
Meaning: this is the color in which the label text on the on the bottom cover is drawn.
Caption
Domain: any string
Default value:... (it depends on your development enviroment)
Meaning: this is the text which is displayed on the middle of the bottom cover.
GreenColor
Domain: any color
Default value:0x0000FF00
Meaning: this is the actual color used to fill the second section of the instrument 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:0x000000FF (red)
Meaning: the color used to draw the instrument index (the line which indicates the current value you want to represent).
IndexThickness
Domain: any integer number (small)
Default value:1
Meaning: this is the thickness of the line which represents the instrument index.
InstrumentBackGroundColor
Domain: any color
Default value:
Meaning: normally this is the color used to fill the back plane of the control. If you select an image into the BackgroundImage property, this value is only used as the inner color of the color gradients located at the bounding box borders, which represent the sunken bevel.
MaximumValue
Domain: any real number
Default value:100
Meaning: this is the maximum value that the quantity you want to represent can assume.
MinimumValue
Domain: any real number
Default value:0
Meaning:this is the minimum value that the quantity you want to represent can assume.
NumberOfDivisions
Domain: any integer number (small)
Default value:10
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 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.
RelativeIndexLength
Domain: any real number
Default value:1.1
Meaning: this is the ratio between the index length and the radius of the scaled circle (refer to the diagram).
RelativeTextRadius
Domain: any real value
Default value:0.96
Meaning: this is the ratio between the text circle radius and the scaled circle radius. The text circle is the circle on which all the centers of the division mark text labels are positioned. This property is set by default to a value slightly less than 1 in order to place text just inside the scaled circle.
ScaleColor
Domain: any color
Default value:0x00000000 (black)
Meaning: this is the color used to draw the instrument bar and the division and subdivision marks.
ScaledCircleRelativeDiameter
Domain: any real value
Default value: 1.2
Meaning: this is the ratio between the scaled circle diameter (refer to the diagram) and the maximum side of the control bounding box. You will have to reduce this value if you want to make the instrument cover 180 degrees, and increase it if you want to make the instrument seem a linear scale (if this value is really big (> 100), the circle sector which represent the visible scaled circle will tend to a line, its radius will tend to infinity and the covered angle will tend to zero).
ScaledCircleRelativeShifting
Domain: any real value
Default value: 0.2
Meaning: multiplying this value by the minimum side of the bounding box you can obtain the scaled circle shifting (towards the bottom of the instrument), as reported on the diagram.
ScaleRelativeWidth
Domain: any real value
Default value: 0.06
Meaning: this quantity is the width of the instrument bar (and therefore the length of the division measuring marks) expressed as a ratio with respect to the scaled circle radius. Putting this value to 0.06 means that the distance between the two circle sectors which constitute the instrument bar is 6 percent of the bar internal circle radius.
ScaleThickLineWidth
Domain: any integer number (small)
Default value: 2
Meaning: this is the thickness (in pixels) of the lines which constitute the instrument bar: the internal circle sector, the external circle sector, the two segments which join the extreme points of these two sectors.
ScaleThinLineWidth
Domain: any integer number (small)
Default value: 1
Meaning: this is the thickness (in pixels) of the lines which represent division and subdivision measuring marks.
ShadedAreaRelativeSize
Domain: any real number (recommended between 0 and 0.5)
Default value: 0.1
Meaning: this is is the ratio between the shaded area width and bounding box minimum size (refer to the diagram). The border is filled with a color gradient going from the InstrumentBackGroundColor to black (or white, according with the simulated light direction) and simulates the highlight and the shadow due to a sunken bevel. Increase this value to make the control seem deeper; decrease it to achieve opposite effects.
SmallScaleFont
Domain: any font
Default value: Arial, 6, Normal
Meaning: this is the font used to draw the text labels corresponding to division measuring marks.
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.
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 index will slightly move out of the instrument bar, in order to show overflow or underflow conditions.
ValueFormatString
Domain: any appropriate format string (see below)
Default value: %.1f
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 a text label on your control, you can simply set this property to an empty string.
If you want to specify a simple text string (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

VisibleScaleRelativeSize
Domain: any real number
Default value: 1.2
Meaning: this is the ratio between the visible scale size (as shown on the diagram) and the bounding box width; since this quantity could not appear much intuitive, we suggest you to make some trials and observe the effect of its variation.
YellowColor
Domain: any color
Default value:0x0000FFFF (red)
Meaning: this is the actual color used to fill the third section of the instrument 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 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.

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 Analog Meter is a powerful OCX control for you application which displays a value using an indicator on a curved scale that covers up to an angle of 180°.
Optimization
	Precision Analog Meter 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 Analog Meter is only 50k in size ! This means that it is very fastly loaded into your application and it does not significantly increase your final application size.
High customisability
	Precision Analog Meter has 30 parameters you can freely set to fully customise the graphic appearance and functionality of the control. For example it is possible to set the color of every single graphical element, the font and the format of every written text, the number of divisions, the geometry and the layout of the components, the line thickness and so on.
Graphics
	Precision Analog Meter 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 Analog Meter 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.
Unicode version available
	Even if the standard version of Precision Analog Meter is able to handle DBCS and MBCS to help you creating localized projects under Windows 9X, a unicode version is available for your strongly localized projects under Windows NT. Choose the version of Precision Analog Meter that best fits to your needs !
High speed version available
	Are you developing a realtime application ? We could provide you with a high performance, simplified-graphics version of our control (without double-buffering) that can reach an update frequency of 100 Hz and more !
Any special requirement ?
	If you are developing an application and found Precision Analog Meter 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.
Trial Version & Licensing
	A trial version is available: it includes all the functionality with only the following restrictions: a red cross will appear in the middle of the bounding box control; a nag screen will keep you waiting three seconds; it will not be possible to change the control caption, it will instead be fixed to "Trial Version" only the first 33 operations will be performed, every succeeding request will be ignored; You can freely evaluate the trial version by including it in your projects as if it was the full-functionality version. When you will decide to buy it, you will only have to register the full-functionality version in place of the trial version, with no modifications to your program (you even won't need to recompile it). A container test project (called TryAnalogMeter) is provided in order to let you experiment with some of the control properties. Once you decide to purchase the full version of the control, a license number will be provided, which can be used to unlock the control at run-time.

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.