VCL Controls: The Button

 

Command Buttons

 

Introduction

A Button is a Windows control used to initiate an action. From the userís standpoint, a button is useful when clicked, in which case the user positions the mouse on it and presses one of the mouseís buttons.

There are various kinds of buttons. The most common and regular is a rectangular object that the user can easily recognize and use. In some programming environments, the classic button is called a Command Button. There are other controls that can serve as click controls and initiate the same behavior as if a button were clicked. Such controls include a label, a static control, or a panel.

From the programmerís standpoint, a button needs a host; this could be a form, a toolbar, or another container. Once you have decided where the button will reside, you can use the drag ní drop process of Borland C++ Builder to add it to your program.

The Command Button

The most popular button used in Windows applications is a rectangular control that displays a word or a short sentence that directs the user to access, dismiss, or initiate an action or a suite of actions. In C++ Builder, this control is implemented using the Button control from the Standard tab of the Component Palette. Therefore, to add a button to a container, click the Button control and click on the container, which is usually a form. Once you have added the control to your application, you can set its properties using the Object Inspector.

Button Properties

From the userís point of view, the only things important about a button are the message it displays and the action it performs. Therefore, the default property of a button is the Caption: this is the word or group of words that display(s) on top of the control, showing the message that would direct the user as to what the button is used for. By default, after adding a button to a form, the Caption property of the Object Inspector has focus; this allows you to just type a caption.

When adding a button to a form, the Caption field would have focus only if the last action you performed on the Object Inspector was for a control that does not have Caption. If the last control you were working on has a Caption property but you were setting another property, when you add a button, the Caption field would not have focus.

The most popular captions are OK and Cancel. The OK caption is set for a form or a dialog box that informs the user of an error, an intermediary situation, or an acknowledgement of an action that was performed on the dialog that hosts the button. The Cancel caption is useful on a button whose parent (the form) would ask a question or request a follow-up action from the user. Whenever a dialog box allows the user to dismiss it without continuing the action, you should provide a button with a Cancel caption.

The easiest way to change the caption on a control, on the Object Inspector, is to click the word Caption and type the desired text.

After adding a button to a form (by design or with code), you can change its caption with code by calling the TControl::Caption property. For example, you can change the caption of a button as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::ChangeButtonCaption()
{
    Button1->Caption = "Let Me Go!";
}
//---------------------------------------------------------------------------

To the programmer, one of the most important properties of any control is the Name. This allows you and the compiler to know what control you are referring to when the program is running. By default, the first button you add to a form is named Button1, the second would be Button2. Since a program usually consists of many buttons, it would be a good idea to rename your buttons and give them meaningful names. The name should help you identify what the button is used for. To change the name of a control, on the Object Inspector, click the word Name and type a valid C++ name.

When a form is hosting many controls, including buttons, it is a good idea to set the control that has focus when the form opens. This is done using the formís ActiveControl property. By default, as we know about the Tab Order, the order of controls on a container is directed by the order of adding them to the container. Even if a control was added last, and regardless of the Tab Order, you can set a certain control to have focus when the form launches.

To set the ActiveControl, give focus to the form. On the Object Inspector, click the ActiveControl field to reveal its combo box; click its combo box and select a control from the list.

To set the active control programmatically, call the TForm::ActiveControl property (actually, the ActiveControl property belongs to the TCustomForm control). Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::SetTheActiveControl()
{
    ActiveControl = Button3;
}
//---------------------------------------------------------------------------

A very important property of a button is the Default property. The Default is a Boolean property. If you set its value to true, this button would have a thick border; this means that if the user presses Enter any time, the action associated with the button would be executed. This is usually set on a dialog box with a button whose caption displays OK.

Another useful property that you should always set, or whenever possible, is the Cancel. Using a Boolean variable, the Cancel property allows the user to press Esc to perform the same action that would be used to dismiss a dialog box. This is important on a dialog box if the buttonís caption is Cancel or Close.

The position of the control is controlled by the Left and Top properties. The dimensions of the control are set by the Width and Height properties.

If the form that is hosting the button is not the first form or dialog (in other words, if the form is accessed by a call from another form), you can use the ModalResult property to conveniently associate an action. By default, the ModalResul is set to mrNone.

The ModalResult property is an integer that represents a button that the user has clicked on a dependent dialog box. This is a very useful and convenient way to find out what button the user clicked, without going through a lot of code. To use a button as a valid integral ModalResult, set its ModalResult property. When coding the result of the user clicking one of the buttons, call the TForm::ShowModal() method (once again, the ShowModal() method actually belongs to the TCustomForm class) and assign it the corresponding value of the TModalResult integer.

The following example uses two forms. The first form has a button used to call the second. The second form has buttons with different ModalResult values. After the user clicks the button on the first form, the second would display, the program simply finds out what button was clicked, and the programmer can act accordingly:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    if( Form2->ShowModal() == mrOk )
        Caption = "I am OK now";
    else if( Form2->ShowModal() == mrCancel )
        Caption = "Soldier, dismiss!!!";
    else
    {
        Form2->Close();
        Caption = "What happened? Where are you?";
    }
}
//---------------------------------------------------------------------------

Depending on what you are trying to do, sometimes you will not want the user to see a control until another action has occurred. To hide a control, use the Visible property. As a Boolean value, the Visible property toggles the appearance and the disappearance of a control. To set the visibility of a control, give focus to the control. On the Object Inspector, you can click the arrow of the combo box or you can double-click the value of the field until the desired value is set. To programmatically hide a control, use the TControl::Visible property. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::HideTheControl()
{
    Button1->Visible = False;
}
//---------------------------------------------------------------------------

Another useful feature of C++ Builder comes in toggling the appearance and the disappearance of a control. The only thing you have to do with the Visible property is to reverse its state. This will come very handy when using menus and toolbars, etc (imagine how easy it is to hide or display a control or a menu item with one line of code, no pointer, no dynamic creation or declaration of any class). The following example toggles the appearance of a form by checking whether the control (in this case the second form) is displaying or not. If the control (the second form) is visible, it gets hidden and vice-versa:

//---------------------------------------------------------------------------
void __fastcall TForm1::ToggleControlAppearance()
{
    Form2->Visible = !Form2->Visible;
}
//---------------------------------------------------------------------------

Also a Boolean value, the Enabled property allows you to enable or disable a control. When a control is enabled, it can perform and respond to all of its normal operations. A disabled button cannot receive focus and most, if not all, of its properties and actions cannot be performed or acted on. You can set and control the Enabled property the same way you would do with the Visible property.

If you position a (visual) control on a form, if the control is positioned on the top left section of the form, when the user resizes the form, the controlís position would appear static, it would not move. This could be a concern if the control is positioned on the right, the bottom or the lower right section of the form. When the user resizes the form, the buttonís position would not be updated. Sometimes you will want the control to have the same measurement with regard to the bottom, the right, and/or the lower right corner of the form. This ability is controlled by the Anchors property. The anchoring of a control to its parent or host container is controlled using a set property derived from the TAnchors enumerator. By default, when you add a control to a form, it is ďgluedĒ to the top left corner of its container. Since this property is a Set, you can set the controlís position with regards to its containerís right and bottom borders.

Button Events

The most regular action the user performs on a button is to click it. Therefore, the default event on a button is the OnClick. To initiate the OnClick event on a button, double-click it.

One of the most regular actions you will assign to a button is to close its parent form when the user clicks the button. There are different reasons you would want to close a form. If the form that hosts the button displays an intermediary message to the user, you should provide all the necessary code to follow up after the user has clicked the button; this is the case of property sheets or wizard pages, among others. When studying message boxes, we will review other situations of dismissing a dialog box by clicking a button.

There are various ways you can close a dialog box from a button. The simplest way is to call the TCustomForm::Close() method; this dismisses the form. To close a form, you can also use the Win32ís PostQuitMessage() function. This function takes one argument which is an integer. The argument could be set to almost any integer value although it should be WM_QUIT.

Button Methods

The Button cannot boast a lot of methods to customize its behavior. This is because a button does not need more than what you would expect from it: point and click. Probably the only method you would use from a button is the constructor used to dynamically create a button. Most of the other methods used on a button are derived from member variables of the TButton class.

The TWinControl::SetFocus() allows you to give focus to a particular control on the form.

Dynamic Buttons

A dynamic button is one you create at runtime. This happens when you could not or would not create a button at design time.

To create a dynamic button, use the TButton constructor. Declare a pointer to a TButton object and use the new operator to assign the constructor. There are two important pieces of information you need to provide. The instance of the object and the container of the control.

If you decide to create a button locally, in a function or an event, declare an instance of the control and specify its parent. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::CreateAButton()
{
    TButton* Btn = new TButton(this);
    Btn->Parent = this;
}
//---------------------------------------------------------------------------

The problem with a locally created object is that it is available only in the function or event in which it is created. You cannot access it outside the function or event. The alternative is to create the object globally in the header file of its host.

To create an object globally, in the private or the public section of the parentís header file, declare a pointer to the constructor:

private: TButton* Foot;

In the constructor of the host, use the new operator to assign an instance of the objectís contructor:

//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner) : TForm(Owner)
{
    Foot = new TButton(this);
}
//---------------------------------------------------------------------------

Once you have the object initialized, to display it, set its parent and the desired properties:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    Foot->Parent = Form1;
    Foot->Caption = "I'm Running";
    Foot->Left = 220;
    Foot->Top = 205;
}
//---------------------------------------------------------------------------

Bitmap Buttons

A bitmap button is a command button that displays a bitmap and possibly a caption on top. A bitmap button is based on the TBitBtn class. To create a bitmap button, use the BitBtn button from the Additional tab of the Component Palette.

The two primary pieces of information you should provide to a bitmap button is the bitmap it displays and its caption. This can be automatically configured by C++ Builder by using one of the existing buttons. C++ Builder ships with a few combinations of bitmaps and captions for a bitmap button. To use one of these, after adding a BitBtn control to the form, on the Object Inspector, click Kind and select one of the types of buttons. The buttons you create using one of the Kind types have already been configured to properly respond to the dialog box or form on which they are used. This works only if the form or dialog box is added to an existing form. If one of the Kind combinations is not satisfying to you, you can use a bitmap and a caption of your choice. The bitmap is specified using the Glyph property of the Object Inspector.

Speed Buttons

The SpeedButton control provides the ability to create command buttons that behave either like check boxes or radio buttons. Like check boxes, you can create a group of speed buttons so that, out of the group, the selected one would display and keep a clicked state. To implement a radio button effect, you can create speed buttons in a group so that only one in the group would display a clicked state when chosen. Speed Buttons can also display as regular buttons. In fact, a speed buttonís behavior is configured as that of a regular button. The design of the speed button provides the most different aspect of the control.

To create a speed button, use the SpeedButton control from the Additional tab of the Component Palette. The best way to implement the behavior of a group of speed buttons is to place them on a toolbar or a panel control.

 
 

Home Copyright © 2004-2007 FunctionX, Inc.