TRadioDial
Component
Description
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.
Operation
There are several ways to operate the component.
Mouse
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.
Keyboard
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.
Code
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.
Appearance
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.
Properties
Additionally to the normal properties most components have, TRadioDial has the following properties:
Angle property
Contains the current angle of the pointer.
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.
Bitmap property
Contains the bitmap on which the dial face is drawn.
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.
ButtonEdge property
Contains the width of the dial's edge.
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.
rcMaxEdge = 10;
rcMinEdge = 2;
Center property
Contains the center point of the dial.
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.
DefaultPos property
Contains the default position of the control.
Use DefaultPos to set the standard Position for the component. The user can select this position by double-clicking the dial.
Frequency property
Specifies the increment between tick marks on the radio control.
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.
LargeChange property
Contains the change in position when Shift is clicked.
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.
Max property
Contains the upper limit for the value the position can take.
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.
MaxAngle property
Contains the upper limit for the value the angle can take.
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.
Min property
Contains the lower limit for the value the position can take.
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.
MinAngle property
Contains the lower limit for the value the angle can take.
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.
PointerColor property
Contains the color of the pointer.
Set PointerColor to specify the color of the pointer on the dial.
PointerSize
Contains the relative size of the pointer.
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.
PointerShape property
Contains the pointer shape.
Set PointerShape to specify the geometric shape of the dial pointer.
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 |
Position property
Contains the current position of the pointer.
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.
Radius property
Contains the radius of the dial.
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.
rcMinRadius = 15;
RepeatDelay property
Contains the delay before a mouse click is auto-repeated.
Use RepeatDelay to get or set the delay in milliseconds between when the dial is clicked and the auto-repeat function will set in.
RepeatRate property
Contains the repeat rate with which mouse clicks are auto-repeated.
Use RepeatRate to get or set the time in milliseconds between two repeats of the auto-repeat function.
SmallChange property
Contains the smallest position change when using the keyboard.
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.
TickStyle property
Specifies how tick marks are placed around the dial.
Set TickStyle to specify whether the radio control should display tick marks, and if so, how those tick marks are set.
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. |
Methods
There are two additional methods:
SetTick procedure
Adds a tick mark around the dial at a specified position.
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.
tlLongLen = 10;
tlMiddleLen = 6;
tlShortLen = 4;
type
TTickLength = (tlShort, tlMiddle, tlLong);
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. |
AngleToPoint function
Calculates a point to an angle
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.
Events
There are two important events:
OnChange event
Is called on each value change.
This event is called whenever Position and/or Angle change.
OnDrawPointer event
Is called each time pointer must be drawn.
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.
