The button components only have about three properties of note. The ModalResult Property
The ModalResult property is used to provide built-in form closing for forms displayed with ShowModal(). By default, ModalResult is set to mrNone (which is #defined as 0). Use this value for buttons that are used as regular buttons on the form and that do not close the form. If you use any nonzero value for ModalResult, pressing the button will close the form and return the ModalResult value. For example, if you place a button on a form and set the ModalResult property to mrOk, pressing the button will close the form, and the return value from ShowModal() will be mrOk (1). Given that, then, you can do something like the following:
int result = MyForm->ShowModal(); if (result == mrOK) DoSomething(); if (result == mrCancel) return;
Table 8.7 lists the ModalResult constants that VCL defines.
Table 8.7. VCL ModalResult constants.
Value mrNone mrOk mrCancel mrAbort mrRetry mrlgnore mrYes mrNo mrAll
You don't have to use one of the predefined ModalResult constants for your buttons. You can use any value you like. Let's say, for example, you had a custom dialog box that could be closed by using a variety of buttons. You could assign a different ModalResult value to each button (100, 150, and 200, for example), and you would then know which button closed the dialog box. Any nonzero number is valid, up to the maximum value of an int.
You can get a program called ButtnTst from http://www.mcp.com/sams/codecenter.html; it demonstrates the use of ModalResult. The program allows you to execute a form containing several buttons. When you click a button, the ModalResult will be reported back on the main form.
The Default property is another key property of buttons. Windows has a standard mechanism for dealing with dialog boxes. One of the features of this mechanism is as follows: If a control other than a button has keyboard focus and the user presses the Enter key on the keyboard, the dialog box will behave as if the user had clicked the default button. The default button is the button that has the BS_DEFPUSHBUTTON style set (usually the OK button). This feature has been the bane of programmers and the curse of data-entry personnel for years. The Default property is used to set a button as the default button for a form. The default value for this property is false. To make a button the default button, set its Default property to true. If you don't specifically set any button's Default property to true, the form will not close when the user presses the Enter key.
When the user closes the form by pressing the Enter key, the OnClick handler of the default button (if one exists) will be called before the form closes.
The Cancel property works with the Esc key in much the same way as the Default property works with the Enter key. When the user presses the Esc key to close a form, the return value from ShowModal() will be the ModalResult value of the button whose Cancel property is set to true. If no button has its Cancel property set to true, mrCancel will be returned if the user uses the Esc key to close the form (mrCancel is equal to 2; see Table 8.7).
Closing a form by clicking the system close box or by pressing Alt+F4 will result in mrCancel being returned from ShowModal() as you would expect. Pressing the Esc key, however, will result in a return value of the ModalResult property being set to whatever button has the Cancel property set to true. The OnClick handler for the Cancel button will be called before the form closes. No OnClick handler is called if the user uses the system close box or Alt+F4 to close the form. Be sure to anticipate the different ways users might use (or abuse) your forms.
You may have more than one button with a Default property set to true. Likewise, you may have more than one button with the Cancel property set to true. However, when the user presses Enter on the keyboard, the first button in the tab order that has its Default property set to true will be invoked. Similarly, when the user presses the Esc key to close the form, the return value from ShowModal() will be the ModalResult value of the first button in the tab order that has its Cancel property set to true.
Earlier I discussed the Enabled property when I discussed components in general. This property is used a lot with buttons to enable or disable the button depending on the current state of the program or of a particular form. When a button is disabled (its Enabled property is set to false), its text is grayed out, and the button does not function. In the case of buttons with bitmaps on them (BitBtn and SpeedButton), the bitmap will also be grayed out automatically.
Button components have only one method of interest: the Click() method, which simulates a mouse click. When you call Click() for a button, the OnClick event of the button is executed just as if the user had clicked the button. As for events, typically only the OnClick event is used.
Now let's take a look at the different button components C++Builder provides.
Was this article helpful?