A radio control represents a position along a range using a turn dial and, optionally, tick marks. A radio control can also display a selected range marked by triangular ticks at the starting and ending positions of the selection.
During program execution, the dial can be turned to the desired position by dragging it with the mouse or by clicking the mouse on the button. To use the keyboard to move the dial, press the arrow keys or the PageUp and PageDown keys.
There are several ways to operate the component.
You can drag the pointer of the control with the mouse. If you click on the button, the angle will be changed up or down by the value of SmallChange, depending on the side you click on. If you press the Shift key while clicking, the changes will be of size LargeChange. If you hold down the mouse button, an auto repeat function will start. The delay before the start of autorepeat in microseconds is in the RepeatDelay property, the repeat rate i s defined in RepeatRate. If you press Ctrl while clicking, the position pointer will either move to the MinAngle or to the MaxAngle position, depending on which side you click.
You can also change the position with the arrow keys. The change is SmallChange. If you use the PgUp or PgDn keys, the change will be defined by LargeChange.
The current value of the RadioControl is defined by the Position property. This can have values between Min and Max. The corresponding angle can be found in the Angle property. The angle can be varied between MinAngle and MaxAngle. The standard position is DefaultPos.
You can change the appearance of the control in several ways. You can set the color and the shape of the pointer with the PointerColor and PointerShape properties, respectively. You can alos control the size of the pointer with the PointerSize property, which is expressed as a percentage of the radius.You can set the radius of the dial with the Radius property and the size of the edge with ButtonEdge.
With the Borderstyle property you can put a border around the control. With Ctl3D you can make this border have a recessed 3D appearance.
The ticks around the control can either be placed automatically or manually, which is controlled by the TickStyle property. The number of ticks is defined in the Frequency property. if you want to set extra ticks manually, you can use the SetTick method.
Additionally to the normal properties most components have, TRadioDial has the following properties:
Contains the current angle of the pointer.
property Angle: TRadioAngle;
The angle is expressed in tenths of degrees, clockwise, starting at the bottom of the dial. This orientation corresponds with the orientation of most turn dials. This means the default MinAngle value is at the bottom left at 30°, the default MaxAngle at the bottom right, at 330° from the negative Y axis. If you change the value of Angle, the Position is updated automatically. Every change will fire the OnChange event.
type
TRadioAngle = 0..3600;
Contains the bitmap on which the dial face is drawn.
property Bitmap: TBitmap;
Use the Bitmap in the event handler for the OnDrawPointer event. To draw your own pointer, you’ll need the Canvas property of the bitmap.
Note: This property can only be used at run time and is read-only.
Contains the width of the dial’s edge.
property ButtonEdge: Integer default 2;
ButtonEdge can have a value between rcMinEdge and rcMaxEdge. The Radius property is not changed by this, because Radius controls size of the entire button, so the edge is included.
const
rcMaxEdge = 10;
rcMinEdge = 2;
Contains the center point of the dial.
property Center: TPoint;
Use Center in the event handler for the OnDrawPointer event to draw a custom pointer. It is important for the AngleToPoint method.
Note: This property can only be used at run time and is read-only.
Contains the default position of the control.
property DefaultPos: Integer;
Use DefaultPos to set the standard Position for the component. The user can select this position by double-clicking the dial.
Specifies the increment between tick marks on the radio control.
property Frequency: Integer default 10;
Use Frequency to specify the spacing of the tick marks, using the logical units used by the Position property. For example, a Frequency of 5 sets a tick mark at every fifth possible increment. To provide visual feedback about the units used by the radio control, set Frequency to SmallChange or LargeChange.
Note: If the value of the TickStyle property is not set to tsAuto, the value of Frequency is ignored.
Contains the change in position when Shift is clicked.
property LargeChange: Integer default 2;
Set LargeChange to specify how much to change the value of Position when the user clicks on the dial while pressing Shift simultaneously. The Max and Min properties define the total range over which Position can vary.
For example, if Max is 30000 and Min is 0, the scale pointer can assume 30,000 positions. If the LargeChange property setting is 10000 and the Position property is 0, the user can click the dial three times after the thumb tab before it moves all the way to the end of the scale.
LargeChange should correspond to the portion of this range that the user sees as a useful change, expressed in the logical units used by the Max, Min, and Position properties.
Contains the upper limit for the value the position can take.
property Max: Integer default 100;
Use Max to set an upper limit to the value that can be represented using the radio control. The scale pointer indicates the current Position in a range between Min and Max.
Contains the upper limit for the value the angle can take.
property MaxAngle: TRadioAngle;
Use MaxAngle to set an upper limit to the scale position that can be represented using the radio control. The pointer indicates the current Angle in a range between MinAngle and MaxAngle.
Contains the lower limit for the value the position can take.
property Min: Integer default 0;
Use Min to set a lower limit to the value that can be represented using the radio control. The scale pointer indicates the current Position in a range between Min and Max.
Contains the lower limit for the value the angle can take.
property MinAngle: TRadioAngle default 300;
Use MinAngle to set a lower limit to the scale position that can be represented using the radio control. The pointer indicates the current Angle in a range between MinAngle and MaxAngle.
Contains the color of the pointer.
property PointerColor: TColor default clBtnText;
Set PointerColor to specify the color of the pointer on the dial.
Contains the relative size of the pointer.
property PointerSize: Integer default 33;
Set PointerSize to specify the size of the dial pointer relative to the radius of the dial. The size is expressed as a percentage of the Radius property.
Contains the pointer shape.
property PointerShape: TRadioPointerShape default psLine;
Set PointerShape to specify the geometric shape of the dial pointer.
type
TRadioPointerShape = (psLine, psTriangle, psDot, psOwnerDraw);
PointerShape has these possible values:
Value | Description |
---|---|
psLine | The pointer is a single line |
psTriangle | The pointer is a triangle |
psDot | The pointer is a filled circle |
psOwnerDraw | The pointer is drawn in the OnDrawPointer event |
Contains the current position of the pointer.
property Position: default 0;
Read Position to determine the current value represented by the radio control. Position is a value in the range between Min and Max (inclusive). Set Position to programmatically move the dial pointer of the radio control to a new value.
Note: On every position change, the Angle property is updated and the OnChange event is called.
Contains the radius of the dial.
property Radius: Integer;
Use Radius to control the size of the dial on the component. There is a minimum radius the dial can have, which is defined by the rcMinRadius constant.
const
rcMinRadius = 15;
Contains the delay before a mouse click is auto-repeated.
property RepeatDelay: default 400;
Use RepeatDelay to get or set the delay in milliseconds between when the dial is clicked and the auto-repeat function will set in.
Contains the repeat rate with which mouse clicks are auto-repeated.
property RepeatRate: default 100;
Use RepeatRate to get or set the time in milliseconds between two repeats of the auto-repeat function.
Contains the smallest position change when using the keyboard.
property SmallChange: Integer default 1;
Set SmallChange to specify how much to change the value of Position when the user clicks on the dial. The Max and Min properties define the total range over which Position can vary.
For example, if Max is 100 and Min is 0, the pointer can assume 100 positions. If the SmallChange property setting is 5 and the Position property is 0, the user can click the down or right arrow button 20 times before the pointer is moved all the way to the end of the scale.
SmallChange should correspond to the portion of this range that the user sees as one item or tick, expressed in the logical units used by the Max, Min, and Position properties.
Specifies how tick marks are placed around the dial.
property TickStyle: TTickStyle;
Set TickStyle to specify whether the radio control should display tick marks, and if so, how those tick marks are set.
type
TTickStyle = (tsNone, tsAuto, tsManual);
TickStyle has these possible values:
Value | Description |
---|---|
tsNone | No tick marks are displayed. |
tsAuto | Tick marks are automatically displayed at increments equal to the value of the Frequency property. |
tsManual | Tick marks are displayed at the Min and Max values. Additional tick marks can be set using the SetTick method. |
There are two additional methods:
Adds a tick mark around the dial at a specified position.
procedure SetTick(Value: Integer; Length: TTickLength); virtual;
Use SetTick to place a tick mark on the bar at the position that corresponds to the Value parameter. Tick marks specified in this manner are only displayed when the TickStyle is set to tsManual.
The Length parameter defines one of three possible lengths a tick mark can have.
const
tlLongLen = 10;
tlMiddleLen = 6;
tlShortLen = 4;
type
TTickLength = (tlShortLen, tlMiddleLen, tlLongLen);
Length has these possible values:
Value | Description |
---|---|
tlShort | A tick is tlShortLen pixels. |
tlMiddle | A tick is tlMiddleLen pixels. |
tlLong | A tick is tlLongLen pixels. |
Calculates a point to an angle
function AngleToPoint(AnAngle: TRadioAngle; ACenter: TPoint; ARadius: Integer): TPoint;
Use AngleToPoint to calculate the point, which is at a given angle and radius from a center point. This method was specifically designed to be used in the OnDrawPointer event.
There are two important events:
Is called on each value change.
property OnChange: NotifyEvent;
This event is called whenever Position and/or Angle change.
Is called each time pointer must be drawn.
property OnDrawPointer: TRadioDrawEvent;
This event is called, when the user should draw the position pointer. This event will only be generated, if the PointerShape property has the psOwnerDraw value.
During this event, the drawing is restricted to the face of the dial button.
To draw the pointer, you can use the Bitmap, Position, Angle, Radius, ButtonEdge, Center, PointerColor and PointerSize properties and the AngleToPoint method.
type
TRadioDrawEvent = procedure(Sender: TRadioDial; ARect: TRect) of object;
These links are being provided as a convenience and for informational purposes only; they do not constitute an endorsement or an approval of any of the products, services or opinions of the corporation or organization or individual. I bear no responsibility for the accuracy, legality or content of the external site or for that of subsequent links. Contact the external site for answers to questions regarding its content.
The coding examples presented here are for illustration purposes only. The author takes no responsibility for end-user use. All content herein is copyrighted by Rudy Velthuis, and may not be reproduced in any form without the author's permission. Source code written by Rudy Velthuis presented as download is subject to the license in the files.