Windows Controls: The Command Button

	Windows Controls: The Command Button

Introduction to the Command Button

Description

A command button is an enhanced version of the regular button. It displays a green arrow icon on the left, followed by a caption in regular size. Under the main caption, it can display another smaller caption that serves as hint to provide more information. Here are two examples from the Add Printer dialog box:

Add Printer

Creating a Command Button

To create a command button, on the Toolbox, click the Command Button object and click the dialog box you are designing. Here is an example:

The command button

After adding it, you can resize it to the dimensions of your choice.

To programmatically create a command button, get a pointer to CButton and initialize it with the new operator. Call its Create() member function to specify the initial characteristics of the button. Among the styles of the control, you must add BS_COMMANDLINK. Here is an example:

BOOL CExerciseDlg::OnInitDialog()
{
    CDialogEx::OnInitDialog();

    // Set the icon for this dialog.  The framework does this automatically
    //  when the application's main window is not a dialog
    SetIcon(m_hIcon, TRUE);			// Set big icon
    SetIcon(m_hIcon, FALSE);		// Set small icon

    // TODO: Add extra initialization here
    CButton *btnSubmit = new CButton;
    CRect rctButton(10, 12, 250, 64);

    btnSubmit->Create(_T("Submit"),
	              WS_CHILD | WS_VISIBLE | BS_COMMANDLINK,
		      rctButton,
		      this,
		      12004);

    return TRUE;  // return TRUE  unless you set the focus to a control
}

Characteristics of a Command Button

Introduction

A command button is primarily a Win32 button. It is based on the MFC's CButton class. As a normal MFC control, after adding a command button to a dialog box, you can accept or change the ID of the control. After adding the command button, if necessary (most of the time, for a command button), you should add a control variable to it so you can programmatically configure its characteristics. This is because many of its properties are not available in the Properties window.

Like a regular button, a command button can display a caption. Of course, you can visually specify it using the Caption field in the Properties window. Here is an example:

The caption of a command button

The caption appears in bold characters on the right side of the picture. By Microsoft Windows standards, you cannot change the alignment of the picture.

A Default Command Button

If you want your command button to be the default, at design time, set its Boolean Default Button field to True in the Properties window. If you are programmatically creating the button, add the BS_DEFCOMMANDLINK style.

When a command button is set as the default, after using the dialog box, if the user presses Enter, the action of the default button executes.

The Note of a Command Button

Besides the regular caption, you can add a sentence under it. To support this, the CButton class is equipped with a member function named SetNote. Its syntax is:

BOOL SetNote(LPCTSTR lpszNote);

To specify the note, call this member function and pass the desired string to it. Here is an example:

BOOL CExerciseDlg::OnInitDialog()
{
    CDialogEx::OnInitDialog();

    // Set the icon for this dialog.  The framework does this automatically
    //  when the application's main window is not a dialog
    SetIcon(m_hIcon, TRUE);			// Set big icon
    SetIcon(m_hIcon, FALSE);		// Set small icon

    // TODO: Add extra initialization here
    m_CommandButton.SetNote(_T("Find the trigonometric values of a known constant"));

    return TRUE;  // return TRUE  unless you set the focus to a control
}

This would produce:

The caption of a command button

To know the current note of an existing command button, call the GetNote() member function of the CButton class. That function is overloaded with two versions whose syntaxes are:

CString GetNote() const;
BOOL GetNote(LPTSTR lpszNote, UINT* cchNote) const;

The first version doesn't take any argument and it produces the note. The second version takes an array variable as a string and it is that argument that will produce the note. The size argument is the size of the note. To get the actual length of the note, you can call the GetNoteLength() member function. Its syntax is:

UINT GetNoteLength() const;

The Borders of a Command Button

When a command has focus, it shows some borders. This is also the case if the button appears by itself in a dialog box. When a command button has been clicked, it becomes surrounded by a black rectangle:

The caption of a command button

As a normal button, when a command button has focus, its body shows a dotted rectangle:

The caption of a command button

When there are many buttons, the button that has focus shows some borders and the other button does not. When the mouse passes over the button that doesn't have focus, its borders are raised:

The caption of a command button

Alternatively, if you want the command button to permanently show borders, you can visually set the Modal Frame field to True in the Properties window. Here is an example of what it would produce:

You can also use a combination of the Client Edge, the Static Edge, and the Modal Frame fields.