Creating a Button (Windows Embedded CE 6.0)
1/6/2010
A button is a window control that a user can turn either on or off to provide input to an application. Buttons can be used either alone or in groups, and buttons can appear either with or without a label. Buttons belong to the BUTTON window class.
Windows Embedded CE provides four kinds of buttons: check box, push button, radio button, and group box. Each button type has one or more styles that affect its appearance, behavior, or both. For a list of supported button styles, see Window and Control Styles. If the WS_EX_LAYOUTRTL window style is set, the button control has to be mirrored. The reading order can be also be controlled by WS_EX_RTLREADING window style.
A check box contains one or more items that appear checked when they are selected. More than one item in a check box can be selected at one time. Applications display check boxes in a group box to enable a user to choose from a set of related, but independent, options. When a user selects a check box, the check box receives the keyboard focus from Windows Embedded CE, which sends the parent window of the check box a WM_COMMAND message that contains the BN_CLICKED notification code. The parent window does not acknowledge this message if the message is sent from an automatic check box or automatic three-state check box, because Windows Embedded CE sets the check state for those styles. The parent window must acknowledge the message if the message is sent from an application-defined check box or three-state check box, because the parent window, and not Windows Embedded CE, is responsible for setting the check state for those styles. Regardless of the style of the check box, Windows Embedded CE repaints the check box after its state is changed. The following screen shot shows three check boxes, one of which is selected.
.gif "Ee500785.f3bf757f-cc55-4189-97dc-bd6e428b5ed5(en-US,WinEmbedded.60).gif")
To create a check box by using the CreateWindow function
Specify the BUTTON window class in the lpClassName parameter of the CreateWindow or the CreateWindowEx function.
Specify one or more styles for the check box in the dwStyle parameter of the CreateWindow or the CreateWindowEx function.
For a complete listing of supported styles, see Window and Control Styles.
To create a check box in a dialog box
Add the following CHECKBOX resource-definition statement to your DIALOG resource.
CHECKBOX text, id, x, y, width, height [[, style [[, extended-style]]]]Here, text is the text that is displayed to the right of the control, and id is the value that identifies the check box. The upper-left corner of the control is positioned at x, y, and its dimension is determined by width and height. Both style and extended-style determine the appearance of the check box. The CHECKBOX resource statement creates a manual check box. That is, your application must check and uncheck the box each time that a user selects the control. If you want Windows Embedded CE to toggle between checked and unchecked states when a user selects the control, use the AUTOCHECKBOX resource statement. For a complete listing of supported styles, see Window and Control Styles.
A push button, also known as a command button, is a small, rectangular control that a user can turn either on or off by tapping it with the stylus. A push button has a raised appearance in its default, or off, state and a pressed-in appearance in its on state. Windows Embedded CE supports owner-drawn push buttons, which are discussed later.
When a user taps a push button, it receives the keyboard focus from Windows Embedded CE, which sends the parent window of the button a WM_COMMAND message that contains the BN_CLICKED notification code. In response, the dialog box closes and the application carries out the operation that is indicated by the button.
Note
Windows Embedded CE does not support the BS_BITMAP, BS_FLAT, BS_ICON, BS_PUSHBOX, BS_TEXT, or BS_USERBUTTON styles. Use the BS_OWNERDRAW style to create the effects that you would achieve otherwise by using the BS_BITMAP, BS_ICON, or BS_USERBUTTON button styles.
The following screen shot shows a push button for the Tabs dialog box.
.gif "Ee500785.02506fe3-6d49-49ae-9c86-b6de3bf50580(en-US,WinEmbedded.60).gif")
To create a push button by using CreateWindow
Specify the BUTTON window class in the lpClassName parameter of the CreateWindow or the CreateWindowEx function.
Specify one or more styles for the push button in the dwStyle parameter of the CreateWindow or the CreateWindowEx function.
For a complete listing of supported styles, see Window and Control Styles.
To create a push button in a dialog box
Add the following PUSHBUTTON resource-definition statement to your DIALOG resource.
PUSHBUTTON "string", id, x, y, width, height [[, style [[, extended-style]]]]Here, string is the text that you want to be displayed inside the push button, and id is the value that identifies the push button. The upper-left corner of the control is positioned at coordinates x, y, and its dimension is determined by the values width and height. Both style and extended-style determine the appearance of the push button.
A radio button, also known as an option button, is similar to a check box in that you can select from one or more options. Unlike a check box, however, when there are multiple radio buttons only one item can be selected, which makes radio buttons mutually exclusive.
When a user selects an automatic radio button, Windows Embedded CE sets the check state of all of the other radio buttons within the same group to unchecked. For standard radio buttons, use the WS_GROUP style to achieve the same effect.
Windows Embedded CE supports most of the styles for a radio button that Windows-based desktop platforms support; it does not support the BS_LEFTTEXT style that places the radio button to the right of the associated text. You can achieve the same effect by using the BS_RIGHTBUTTON style. The following screen shot shows two radio buttons.
.gif "Ee500785.0b72f621-0efb-42ec-aef2-cff5333cecf1(en-US,WinEmbedded.60).gif")
To create a radio button by using CreateWindow
Specify the BUTTON window class in the lpClassName parameter of the CreateWindow or the CreateWindowEx function.
Specify one or more styles for the radio button in the dwStyle parameter of the CreateWindow or the CreateWindowEx function.
For a complete listing of supported styles, see Window and Control Styles.
To create a radio button in a dialog box
Add the following RADIOBUTTON resource-definition statement to your DIALOG resource.
RADIOBUTTON "string", id, x, y, width, height [[, style [[, extended-style]]]]Here, string is the text that you want to be displayed next to the radio button, and id is the value that identifies the radio button. The upper-left corner of the control is positioned at coordinates x, y, and its dimension is determined by the values width and height. Both style and extended-style determine the appearance of the radio button. The RADIOBUTTON resource statement creates a manual radio button. This means that your application must clear other radio buttons in the group manually each time that a user selects a button. If you want Windows Embedded CE to clear other radio buttons automatically when a user selects an option, use the AUTORADIOBUTTON resource statement.
A group box is a rectangular area within a dialog box in which you can group together semantically related controls. Controls are grouped by drawing a rectangular border around them. Any text that is associated with the group box is displayed in its upper-left corner. The purpose of a group box is to organize controls that are related by a common purpose, which is usually indicated by the label. The group box has only one style, which is defined by the BS_GROUPBOX constant. Because a group box cannot be selected, it has no check state, focus state, or push state. An application cannot send messages to a group box.
Because group boxes are opaque in Windows Embedded CE, add them to the template for your dialog box after you add other elements. Anything you add to the template after you add the group box will be hidden under it. By adding group boxes last, you ensure that the group boxes are at the bottom of the z-order and do not hide other controls. The z-order is a stack of overlapping windows. The following screen shot shows a group box.
.gif "Ee500785.7fddc3d1-207c-46cb-adc5-052f2799dbf9(en-US,WinEmbedded.60).gif")
To create a group box by using the CreateWindow function
Specify the BUTTON window class in the lpClassName parameter of the CreateWindow or the CreateWindowEx function.
Specify one or more styles for the group box in the dwStyle parameter of the CreateWindow or the CreateWindowEx function.
For a complete listing of supported styles, see Window and Control Styles.
To create a group box in a dialog box
Add the following GROUPBOX resource-definition statement to your DIALOG resource.
GROUPBOX "title", id, x, y, width, height [[, style [[, extended-style]]]]Here, title is the title of the box, and id is the value that identifies the group box. The upper-left corner of the control is positioned at coordinates x, y, and its dimension is determined by the values width and height. Both style and extended-style determine the appearance of the group box.
The following code example shows how to create several buttons.
#define BUTTONCLASS L"button"
#define BUTTONWIDTH 22 * cxAveChar
#define BUTTONHEIGHT 7 * cyAveChar / 4
#define BUTTONOFFSETLEFT 1
#define BUTTONOFFSETTOP 2 * cyAveChar
#define ID_BUTTON1 0x8801
#define ID_BUTTON2 0x8802
#define ID_BUTTON3 0x8803
#define ID_BUTTON4 0x8804
#define ID_BUTTON5 0x8805
#define ID_BUTTON6 0x8806
#define ID_BUTTON7 0x8807
#define ID_BUTTON8 0x8808
HWND hwndG1B1, hwndG1B2;
HWND hwndG2B1, hwndG2B2, hwndG2B3, hwndG2B4;
HWND hwndG3B1, hwndG3B2;
int cxAveChar, cyAveChar;
HINSTANCE hInst; // The current instance
HWND hwndCB; // The command bar handle
// Create a command bar.
hwndCB = CommandBar_Create(hInst, hWnd, 1);
CommandBar_InsertMenubar(hwndCB, hInst, IDM_MENU, 0);
CommandBar_AddAdornments(hwndCB, 0, 0);
UINT nCmdBarHeight = CommandBar_Height(hwndCB);
// Create various buttons.
hdc = GetDC( hWnd );
TEXTMETRIC tm;
GetTextMetrics( hdc, &tm );
cxAveChar = tm.tmAveCharWidth;
cyAveChar = tm.tmHeight + tm.tmExternalLeading;
ReleaseDC( hWnd, hdc );
// Create a push button.
hwndG1B1 = CreateWindow( BUTTONCLASS, L"Push Button",
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
BUTTONOFFSETLEFT, nCmdBarHeight, BUTTONWIDTH,
BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON1, // 0x8801
hInst, NULL );
// Create a default push button.
hwndG1B2 = CreateWindow( BUTTONCLASS, L"Def Push Button",
WS_CHILD | WS_VISIBLE | BS_DEFPUSHBUTTON,
BUTTONOFFSETLEFT ,
BUTTONOFFSETTOP + nCmdBarHeight , BUTTONWIDTH,
BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON2, // 0x8802
hInst, NULL );
// Create a default radio button.
hwndG3B1 = CreateWindow( BUTTONCLASS, L"Radio Button",
WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
BUTTONOFFSETLEFT,
BUTTONOFFSETTOP + nCmdBarHeight * 2,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON7, // 0x8807
hInst, NULL );
// Create a default auto radio button.
hwndG3B2 = CreateWindow( BUTTONCLASS, L"Auto Radio Button",
WS_CHILD | WS_VISIBLE | BS_AUTORADIOBUTTON,
BUTTONOFFSETLEFT,
BUTTONOFFSETTOP + nCmdBarHeight * 3,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON8, // 0x8808
hInst, NULL );
// Create a default check box.
hwndG2B1 = CreateWindow( BUTTONCLASS, L"Check Box",
WS_CHILD | WS_VISIBLE | BS_CHECKBOX,
BUTTONOFFSETLEFT + 120, nCmdBarHeight,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON3, // 0x8803
hInst, NULL );
// Create a default auto check box.
hwndG2B2 = CreateWindow( BUTTONCLASS, L"Auto Check Box",
WS_CHILD | WS_VISIBLE | BS_AUTOCHECKBOX,
BUTTONOFFSETLEFT + 120,
BUTTONOFFSETTOP + nCmdBarHeight,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON4, // 0x8804
hInst, NULL );
// Create a default three-state button.
hwndG1B1 = CreateWindow( BUTTONCLASS, L"Three State",
WS_CHILD | WS_VISIBLE | BS_3STATE,
BUTTONOFFSETLEFT + 120,
BUTTONOFFSETTOP + nCmdBarHeight * 2,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON5, // 0x8805
hInst, NULL );
// Create a default auto three-state button.
hwndG2B3 = CreateWindow( BUTTONCLASS, L"Auto 3 State",
WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
BUTTONOFFSETLEFT + 120,
BUTTONOFFSETTOP + nCmdBarHeight * 3,
BUTTONWIDTH, BUTTONHEIGHT, hWnd,
(HMENU) ID_BUTTON6, // 0x8806
hInst, NULL );
When a user selects a button, either the OS or the application must change one or more of the state elements of the button. The state of a button can be characterized by its focus state, push state, and check state. Windows Embedded CE automatically changes the focus state for all button types, the push state for push buttons, and the check state for all automatic buttons. The application must make all other state changes, taking into account the type, style, and current state of the button. An application can determine the state of a button by sending it a BM_GETCHECK or a BM_GETSTATE message; the application can set the state of a button by sending it a BM_SETCHECK or a BM_SETSTATE message.