Command Button

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 regularly used is a rectangular object that the user can easily recognize. In some programming environments, this classic type 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.

From the programmer’s standpoint, a button needs a host, such as a dialog box. To add a button to a dialog box, click it on the Toolbox and click in the desired location on the dialog box.

By default, when you visually create a dialog box, Microsoft Visual C++ adds two buttons: OK and Cancel

If you dynamically create a button instead of visually adding it, you would have to write all of its messages manually.

From the user’s point of view, the only things important about a button are the message it displays and the action it performs. The word or sentence that displays on top of a button is its Caption. By default, after adding a button to a form, the Caption property has focus. Therefore, if you start typing, the caption would be changed. At design time, you can set the caption with the necessary string on the Caption field of the Properties window. At run time, to change the caption of a button, call the CWnd::SetWindowText() method and pass it the necessary string as argument. Here is an example:

If you want to access the properties of a control without using an associated variable, you may have to call the CWnd::GetDlgItem() method. It comes in two versions as follows:

CWnd* GetDlgItem(int nID) const;
void CWnd::GetDlgItem(int nID, HWND* phWnd) const;

When calling this method, the first version allows you to assign a CWnd (or derived class) to it. The second returns a handle to the window passed as pointer. In both cases, you must pass the identifier of the control that you want access to. When using the first version, if the control is not a CWnd object, you must cast it its native class. Then you can manipulate the property (or properties) of your choice. Here is an example that accesses a button and changes its caption:

The second version requires a pointer to a child window that you want to access. 

The most popular button captions are OK and Cancel.

The OK caption is set for 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. Visual C++ makes it particularly easy to add an OK button because in Windows applications, the OK object has a special meaning. To use an OK button, add a button to a form and, from the ID combo box, select the IDOK identifier. What makes this constant special is that the MFC recognize that, when the clicks it, if the dialog box is modal, the user is acknowledging the situation. If this dialog box was called from another window using the DoModal() method, you can find out if the user had clicked OK and take further action. Therefore, when the user clicks OK, the dialog box calls the OnOK() method. Its syntax is:

virtual void OnOK();

Although it looks like a simple method (and it is) the OnOK() carries the constant value IDOK that you can use as a return value of the DoModal() method. Therefore, in one step, you can use the DoModal() method to display a modal dialog box and find out whether the user clicked OK. We will see various examples of this situation in this book.

When a dialog box is equipped with an OK button, you should allow the user to press Enter and perform the OK clicking. This is taken care of by setting the Default Button property to True or checked.

The Cancel caption is useful on a button whose parent (the dialog box) would ask a question or request a follow-up action from the user. A cancel button is also easy to create by simply adding a button to a dialog box and selecting IDCANCEL as its identifier in the ID combo box. Setting a button's identifier to IDCANCEL also allows the user to press Esc to dismiss the dialog box.

The scenarios described for the OK and the Cancel buttons are made possible only if the compiler is able to check or validate the changes made on a dialog box. To make this validation possible, in your class, you must overload the CWnd::DoDataExchange() method. Its syntax is:

virtual void DoDataExchange( CDataExchange* pDX );

This method is used internally by the application (the framework) to find out if data on a dialog box has been changed since the object was displayed. This method does two things it ensure the exchange of data among controls and it validates the values of those controls. In reality, it does not inherently perform data validation, meaning it would not allow or disallow value on a control. Instead, the compiler uses it to create a table of the controls on the dialog box, their variables and values, allowing other controls to refer to it for data exchange and validating. If you want to find out the data a user would have typed or selected in a control, you would have to write the necessary code.

By default, the caption on a button is positioned in the middle and the center of the control. At design time, you can control this position using the Horizontal and the Vertical Alignments on the Properties window:

After creating a control, to make sure that it displays when its host control comes up, set its Visible property to True or checked (the default). Otherwise, if you want it to be hidden for example to wait for an intermediary action from the user, you can set its Visible property to False or unchecked. For example, to display a control, whether it is hidden or not, call the CWnd::ShowWindow() method and pass SW_SHOW as its argument:

In the same way, to hide a control, call it by passing the SW_HIDE constant as argument.

For the user to be able to use a control such as clicking a button, the control must allow it. This characteristic of Windows objects is controlled by the CWnd::EnableWindow() method. Its syntax is:

BOOL EnableWindow(BOOL bEnable = TRUE);

This method is used to enable or disable a control. The default value of the argument bEnable is set to TRUE, which would display a control. To disable a control, set the argument to FALSE. Here is an example:

void CDialog5Dlg::OnLetItBe() 
{
	// TODO: Add your control notification handler code here
	m_Submit.EnableWindow(FALSE);
}

Buttons Messages

The most regular action users perform on a button is to click it. When a user does this, the button sends a BN_CLICKED message. In some but rare circumstances, you may also ask the user to double-click a button. Over all, you will take care of most message handling when the user clicks a button.

There are other messages that you can handle through a button.

To close a dialog box, you can use the Win32 API's PostQuitMessage() function. Its syntax is:

VOID PostQuitMessage(int nExitCode);

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. Here is an example:

Although the MFC provides enough messages associated with the various controls, in some circumstances you will need use a message that is not necessarily associated with the control. In such a case, you can call the CWnd::SendMessage() method. Its syntax is:

LRESULT SendMessage(UINT message, WPARAM wParam = 0, LPARAM lParam = 0);

The first argument of this method can be a Win32 message or constant.  Examples would be WM_CLOSE or WM_ACTIVATE. The wParam and lParam arguments can be additional (Win32) messages.

The WinExec() function is used to run an application. Its syntax is:

UINT WinExec(LPCSTR lpCmdLine, UINT uCmdShow);

The lpCmdLine argument specifies the name or path of the application you want to display. The uCmdShow specifies how the application should be displayed. It uses the same values as the CWnd::ShowWindow() method.