TRadioControl
 
Properties Methods Events

Description

A radio control represents a position along a continuum 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.
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 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 is 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 the side you click on.
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.

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. 

Back to top
Properties

Additionally to the normal properties most components have, TRadioControl has the following properties: 

property Angle: TRadioAngle;
The Angle property contains the angle of the pointer 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 MinAngle value is at the bottom left at 30°, the 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;
property Bitmap: TBitmap;
Use the Bitmap in the event handler for the OnDrawPointer event. It contains the bitmap, on which the dial face is drawn. 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.

property ButtonEdge: Integer default 2;
ButtonEdge is the width of the edge of the dial. It can have a value between rcMinEdge and rcMaxEdge. The Radius property is not changed by this, because Radius is controls size of the entire button, so the edge is included. 
const
  rcMaxEdge = 10;
  rcMinEdge = 2;
property Center: TPoint;
Use Center in the event handler for the OnDrawPointer event to draw a custom pointer. It contains the center point of the dial. It is important for the AngleToPoint method.

Note: This property can only be used at run time and is read-only.

property DefaultPos: Integer;
Use DefaultPos to set the standard Position for the component. The user can select this position by double-clicking the dial.
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.

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.

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.
property MaxAngle: TRadioAngle default 3300;
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.
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.
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.
property PointerColor: TColor default clBtnText;
Set PointerColor to specify the color of the pointer on the dial.
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.
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 Meaning
psLine The pointer is a single line
psTriangle The pointer is a triangle
psDot The pointer is a round dot
psOwnerDraw The pointer is drawn in the OnDrawPointer event
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 The Angle property is updated and the OnChange event is called.

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;
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.
property RepeatRate: default 100;
Use RepeatRate to get or set the time in milliseconds between two repeats of the auto-repeat function.
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.

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 Meaning
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.
 
Back to top
Methods

There are two additional methods: 

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 lenghts, a tick mark can have. 
const
  tlLongLen = 10;
  tlMiddleLen = 6;
  tlShortLen = 4;

type
  TTickLength = (tlShort, tlMiddle, tlLong);

Length has these possible values: 
Value Meaning
tlShort A tick is tlShortLen pixels.
tlMiddle A tick is tlMiddleLen pixels.
tl Long A tick is tlLongLen pixels.

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.
 
Back to top
Events

There are two important events: 

property OnChange: TNotifyEvent;
This event is called whenever Position and/or Angle change.
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: TRadioControl; ARect: TRect)
                      of object;

 
Back to top