VCL Controls: The UpDown

Introduction

A spin button, also called UpDown, is a Windows control equipped with two opposite arrow buttons or . The user clicks one of the arrow buttons at one time to increase or decrease the current value of the control. The value held by the control is also called its position.

The values of a spin button range from a minimum to a maximum. When the up or right arrow is clicked, the value of the control increases. If the user clicks and holds the mouse on the up or right pointing pointing arrow button, the value of the control keeps increasing until it reaches its maximum and then stops. The opposite behavior applies when the user clicks or holds the mouse on the down or left-pointing arrow button.

Because a spin button is only equipped with arrows, it does not inherently show its value. Therefore, this control is usually accompanied by another, text-based, control, usually an edit box, that indicates its position .

1. Start a new project with its default form
2. Save it in a new folder called ColorPreview1
3. Save the unit as Exercise and save the project as ColorPreview
4. Change the Caption of the form to Color Previewer and change its name to frmMain
5. Set the BorderStyle of the form to bsDialog
6. Open Image Editor. Create a new 32 x 32 icon and design it as follows:
    
   
7. Design its equivalent 16 x 16 icon as follows:
    
   
8. Save the icon as previewer in the folder of the current project
9. In C++ Builder, access the project options (Project -> Options) dialog box
10. Change the Title to Color Previewer and set the icon to the above
     
    
11. Click OK
12. From the Standard tab of the Component Palette, click Panel and draw a wide panel in the top section of the form. Delete its caption
13. Change its Name to pnlPreview
14. Using its Color property in the Object Inspector, change its color to clSilver
15. Add a BitBtn to the form and set its Kind to bkClose
     
    
16. Save All

To create an UpDown button, you can use the UpDown control from the Win32 tab of the Component Palette. Although not required, this control should be accompanied by another object that would display the current value of the updown control. The most commonly used accompanying object is an edit control but you can use any control you judge appropriate.

After adding the UpDown control on a container such as a form, use the Object Inspector to control its properties. The most usual way to add the Edit control is to position it on the left side of the UpDown button If using an edit box or a label, the accompanying control is usually positioned to the left of the updown object:

The UpDown control appears with two arrow buttons pointing up and down, respectively. This feature is controlled by the Orientation property. An alternative is to point the arrows to left and right. To do this, use the Orientation property to set the arrows to your liking.

Probably the most important piece of information you would need from an updown control is the value it is holding at a particular time. As mentioned already, the updown control navigates from a minimum to a maximum values. The values of the control are short integer numbers. These numbers range from a minimum controlled by the Min property to a maximum value controlled by the Max property. By default, a freshly added UpDown control on a form has its Min and Max values set to 0 and 100 respectively. You can set the minimum value of the control to –32768 and the maximum to 32767. These values are set using the Min and Max fields of the Object Inspector. You can change them programmatically as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	UpDown1->Min = -224;
	UpDown1->Max = -1;
}
//---------------------------------------------------------------------------

If you use numbers in the thousands, the control that accompanies the UpDown (such as the edit control) will display the values using the comma to separate the thousands. This is because the UpDown control is configured, by default, to separate the thousands. If you do not want this feature, change the value of the Thousands property from true to false.

When using the UpDown button, the user clicks one of the arrows of the control to increase or decrease the value. By default, the value increases or decreases by 1. If you want the value to augment by more than 1, set an integer value using the Increment property. To set the Increment value programmatically, you can use code as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	UpDown1->Max = 125;
	UpDown1->Min = 10;
	UpDown1->Increment = 5;
}
//---------------------------------------------------------------------------

When an UpDown control is accessed, the value it holds can be set by its Position. You can use this property to specify what value the control would use at startup. It should be an integer between the Min and the Max values. You can also set it programmatically as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	UpDown1->Max = 125;
	UpDown1->Min = 10;
	UpDown1->Increment = 5;
	UpDown1->Position = 55;
}
//---------------------------------------------------------------------------

The Position property also allows you to find out the value of the UpDown control at any time. After setting the Increment value, when the user clicks the arrow buttons, the value would increase accordingly. When the maximum value is reached, the control would use the Wrap property to find out what to do:

• If the Wrap Boolean property is set to false (the default), the increment would stop at the Max value even if Max is not divisible by the Increment value. The same goes for the Min value
• If the Wrap property is set to true and if the user increases the value of the control, the incrementing would stop to the last value divisible by the Increment value but less than the Max. The same would apply when decrementing the value of the control.

As mentioned already, an updown control does not visually display its value. Therefore, you can add a text-based or other control to it. This accompanying object is specified using the Associate property. The associated control would display the current value of the UpDown control. To associate a control to the UpDown control, first create or add the desired control to your application. Then, at design time on the Object Inspector, you can click the Associate field to display its combo box. Click the arrow and select the desired control. You can also associate a control programmatically using code such as this:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	UpDown1->Associate = Edit1;
}
//---------------------------------------------------------------------------

The UpDown control usually has its associated control on the left side. This is controlled by the AlignButton property. Alternatively, you can ask it to have the accompanying control on its right side by setting the AlignButton property to udRight. At design time, both controls still display as they are designed. If you change the AlignButton value, the control would apply the value only at runtime.

One of the nicest features that make the UpDown button easy to use is that the user can change its values by pressing the up and down arrow keys of the keyboard. This ability is by default set to true from the Boolean ArrowKeys property. If you want to prevent the user from using the keyboard to increase or decrease the value of the UpDown control, set the ArrowKeys property to false.

1. From the Standard tab of the Component Palette, click the Edit control and click under the panel on the form
2. Change the name of the new edit control to edtRed and set the content of the Text field to 192
3. On the Win32 tab, click the UpDown control and click on the right side of the edit box on the form
4. On the Object Inspector, change its name to updRed
5. Make sure the AlignButton field displays udRight
   Click Associate and select edtRed
6. Make sure the Increment field display 1.
   Change the Max value to 255 and accept the Min value as 0
7. Change the Position value to 192
8. On the form, select both the edit and the updown controls. Press Ctrl + C to top. Then press Ctrl + V to paste
9. Change the name of the new edit control to edtGreen
10. Change the name of the new updown control to updGreen and set its Associate property to edtGreen (it should be set already but check it)
11. Paste again
12. Change the name of the new edit control to edtBlue
13. Change the name of the new updown control to updBlue and make sure its Associate property is set to edtBlue
    
    
14. To test the new controls, press F9
15. Close it and return to Bcb

The UpDown control is based on the TUpDown class. This class has only two methods: a constructor and a destructor. The TUpDown constructor is used to dynamically create an UpDown button. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TUpDown *Counter = new TUpDown(this);
	Counter->Parent = this;
	TEdit *Displayer = new TEdit(this);
	Displayer->Parent = this;
	Displayer->Left = 16;
	Displayer->Top = 16;
	Displayer->Width = 32;
	Counter->Left = Displayer->Left + Displayer->Width;
	Counter->Top = Displayer->Top;
	Counter->Min = 12;
	Counter->Max = 248;
	Counter->Increment = 2;
	Counter->Position = 36;
	Counter->Associate = Displayer;
}
//---------------------------------------------------------------------------

The main event of the UpDown control occurs when the user clicks one of the arrows. Whether the user clicks the up pointing arrow to increase or the down pointing arrow to decrease the value or position of the control, the OnClick() event is fired. The pointing arrows are represented using the TUDBtnType enumerator that has two values. The up or right pointing arrow is recognized as btNext while the down or left pointing arrow is referred to as btPrev.

When the user clicks one of the arrows, you can write code to perform an action depending on the button that was clicked. Using this OnClick() event, you do not have to associate the UpDown control with an edit box to display integers; you can use the event to format the value or configure any other behavior you see fit. For example, instead of displaying an integer, you can display a floating number, a string, anything, that is traditionally not allowed.

When the user clicks one of the arrows of the UpDown control, the operating system is notified just before this action occurs. This notification is done through the OnChanging() event. This allows you to perform a last minute configuration before the value or position of the control changes. You can also use this event to deny changing the value of the control.

The OnChangingEx() event also fires just before the value of the UpDown control changes. This time, you can set a new value for the control if the change is successful.

It is important and professionally convenient to make sure that the user can use the up and down arrow keys of the keyboard to increase or decrease the value of the UpDown control. If the user presses and holds the up arrow key, the UpDown control would be incrementing its value until either the user releases the key or the control reaches its maximum limit. Here is an example of how to track the OnMouseUp mouse event of the UpDown control:

Practical Learning: Configuring an UpDown control