This resource-definition statement creates a user-defined control.
Syntax
CONTROL text, id, class, style, x, y, width, height [[, extended-style]]
Parameters
class
Specifies a redefined name, character string, or a 16-bit unsigned integer value that defines the class of the control. For more information about possible control classes, see Remarks. If the value is a redefined name supplied by the application, it must be a string enclosed in double quotation marks (“).
style
Specifies a redefined name or integer value that contains the style of the specified control. The exact meaning of style depends on the class value. For more information about possible styles, see Remarks.
Remarks
The six possible control classes are described in the following sections.
A button control is a small rectangular child window that the user turns on or off when selected. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.
The following table shows button styles. A button can have only one of the styles, with the exception of BS_LEFTTEXT, which can be combined with check boxes and radio buttons.
| Style | Description |
| BS_3STATE | Creates a check box in which the box can be unavailable (grayed) as well as checked or unchecked. Use the unavailable state to show that the state of the check box is not determined. |
| BS_AUTO3STATE | Creates a three-state check box in which the state cycles through checked, unavailable, and unchecked each time the user selects the check box. |
| BS_AUTOCHECKBOX | Creates a check box in which the check state automatically toggles between checked and unchecked each time the user selects the check box. |
| BS_AUTORADIOBUTTON | Creates a radio button that, when selected by a user, clears all other buttons in the same group. |
| BS_BOTTOM | Places the text at the bottom of the button rectangle. |
| BS_CENTER | Centers the text horizontally in the button rectangle. |
| BS_CHECKBOX | Creates a small, empty check box with a label displayed to the right of it. To display the text to the left of the check box, combine this flag with the BS_RIGHTBUTTON style. |
| BS_DEFPUSHBUTTON | Creates a push button with a heavy black border. If the button is in a dialog box, the user can select the button by pressing the enter key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely option, or default. |
| BS_GROUPBOX | Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle’s upper-left corner. |
| BS_LEFT | Left-aligns the text in the button rectangle when combined with the radio button or check box style. |
| BS_NOTIFY | Enables a button to send BN_DBLCLK, BN_KILLFOCUS, or BN_SETFOCUS notification messages to its parent window. |
| BS_OWNERDRAW | Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created, and it receives a WM_DRAWITEM message when a visual aspect of the button has changed. The BS_OWNERDRAW style cannot be combined with any other button styles. |
| BS_PUSHBUTTON | Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button. |
| BS_RADIOBUTTON | Creates a small circle with a label displayed to the right of it. To display the text to the left of the circle, combine this flag with the BS_RIGHTBUTTON style. |
| BS_RIGHT | Right-aligns text in the button rectangle. |
| BS_RIGHTBUTTON | Positions a check box’s square on the right side of the button rectangle. |
| BS_TOP | Places text at the top of the button rectangle. |
| BS_VCENTER | Vertically centers text in the button rectangle. |
| WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box. |
Combo box controls consist of a selection field similar to an edit control plus a list box. The list box may be displayed at all times or may be dropped down when the user selects the down arrow next to the selection field. Depending on the style of the combo box, the user can or cannot edit the contents of the selection field.
If you specify the CBS_EX_CONSTSTRINGDATA style when the application inserts a string into the list part of a combo box, the combo box stores the pointer passed to it by the application rather than copying the string. This saves RAM resources when you have a large table of strings in ROM that you want to insert into a combo box.
All combo boxes in Windows CE have the LBS_HASSTRINGS style by default.
The following table shows combo box control styles.
| Style | Description |
| CBS_AUTOHSCROLL | Creates a combo box that automatically scrolls the text in the edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed. |
| CBS_DISABLENOSCROLL | Creates a combo box that displays a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items. |
| CBS_DROPDOWN | Creates a combo box that displays only the edit control by default. The user can display the list box by selecting an icon next to the edit control. |
| CBS_DROPDOWNLIST | Creates a combo box that displays a static text field that displays the current selection in the list box. |
| CBS_LOWERCASE | Converts any uppercase characters typed into the edit control of a combo box to lowercase. |
| CBS_NOINTERGRALHEIGHT | Specifies that the combo box is exactly the size specified by the application when it created the combo box. Usually, Windows CE sizes a combo box so that it does not display partial items. |
| CBS_OEMCONVERT | Converts text typed in the combo box edit control from the Windows character set to the OEM character set and then back to the Windows set. This style is most useful for combo boxes that contain file names. It applies only to combo boxes created with the CBS_DROPDOWN style. |
| CBS_SORT | Creates a combo box that sorts the strings in the list box alphabetically. |
| CBS_UPPERCASE | Converts any lowercase characters typed into the edit control of a combo box to uppercase. |
| WS_TABSTOP | Turns the control into a tab stop which allows the user to select the control by tabbing through the controls in a dialog box. |
An edit control is a rectangular child window in which the user can enter text from the keyboard. The user selects the control and gives it the input focus, by tapping inside it with a stylus or by pressing the TAB key. The user can enter text when the control displays a flashing insertion point.
Edit controls use the fixed-pitch font and display Unicode characters. They expand tab characters into as many space characters as are required to move the cursor to the next tab stop. Tab stops are assumed to be at every eighth character position.
The following table shows edit control styles.
| Style | Description |
| ES_AUTOHSCROLL | Creates an edit control that automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero. |
| ES_AUTOVSCROLL | Creates an edit control that scrolls text up one page when the user presses the ENTER key on the last line. |
| ES_CENTER | Centers the text. This style is valid in multiline edit controls only. |
| ES_COMBOBOX | Indicates that the edit control is part of a combo box. |
| ES_LEFT | Aligns text to the left. |
| ES_LOWERCASE | Converts all characters to lowercase as they are typed into the edit control. |
| ES_MULTILINE | Creates a multiline edit control. The default is a single-line edit control.
When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style. When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed. If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the cursor goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed. Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window. |
| ES_NOHIDESEL | Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus. |
| ES_NUMBER | Allows only digits to be typed into the edit control. |
| ES_OEMCONVERT | Converts text typed in the edit control from the Windows character set to the OEM character set, and then converts it back to the Windows set. This style is most useful for edit controls that contain file names. |
| ES_PASSWORD | Displays all characters as an asterisk (*) as they are typed into the edit control. An application can use the EM_SETPASSWORDCHAR message to change the character that is displayed. |
| ES_READONLY | Prevents the user from typing or editing text in the edit control. |
| ES_RIGHT | Aligns text to the right. This style is valid in multiline edit controls only. |
| ES_UPPERCASE | Converts all characters to uppercase as they are typed into the edit control. |
| ES_WANTRETURN | Specifies that a carriage return be inserted when the user presses the ENTER key while typing text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control. |
| WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box. |
List box controls consist of a list of character strings. The control is used whenever an application needs to present a list of names, such as file names, that the user can view and select. When a string is selected, it is highlighted and a notification message is passed to the parent window. A scroll bar can be used with a list box control to scroll lists that are too long or too wide for the control window.
There are two types of list boxes: single-selection, which is the default, and multiple-selection. In a single-selection list box, the user can select only one item at a time. In a multiple-selection list box, the user can select more than one item at a time. To create a multiple-selection list box, specify the LBS_MULTIPLESEL or the LBS_EXTENDEDSEL style.
Note
Windows CE supports the LBS_EX_CONSTSTRINGDATA style which saves RAM resources when you have a large table of strings in ROM that you want to insert into a list box.
All list boxes in Windows CE have the LBS_HASSTRINGS style by default.
The following table shows list box control styles.
| Style | Description |
| LBS_DISABLENOSCROLL | Creates a list box that shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If this style is not specified, the scroll bar is hidden when the list box does not contain enough items. |
| LBS_EXTENDEDSEL | Creates a list box that enables the user to select multiple items by using special key combinations. |
| LBS_MULTICOLUMN | Creates a multicolumn list box that the user scrolls horizontally. Use the LB_SETCOLUMNWIDTH message to set the width of the columns. |
| LBS_MULTIPLESEL | Creates a list box that turns string selection on or off each time a user selects a string in the list box. A user can select any number of strings simultaneously. |
| LBS_NOINTEGRALHEIGHT | Specifies that the list box will be exactly the size specified by the application when it created the list box. Usually, Windows sizes a list box so that it does not display partial items. |
| LBS_NOREDRAW | Create a list box that does not automatically updated its appearance when changes are made. You can change this style by sending a WM_SETREDRAW message. |
| LBS_NOSEL | Creates a list box in which the user can view list box strings but cannot select them. |
| LBS_NOTIFY | Notifies the parent window whenever the user selects a string in the list box. |
| LBS_SORT | Sorts the strings in the list box alphabetically. |
| LBS_STANDARD | Sorts strings in the list box alphabetically. The parent window receives an input message whenever the user clicks or double-clicks a string. The list box has borders on all sides |
| LBS_USETABSTOPS | Creates a list box that recognizes and expands tab characters when drawing its strings. The default tab positions are 32 dialog box units. A dialog box unit is equal to one-fourth of the current dialog box base-width unit. Windows CE calculates these units based on the height and width of the current system font. |
| LBS_WANTKEYBOARDINPUT | Specifies that the owner of the list box receives WM_VKEYTOITEM messages whenever the user presses a key and the list box has the input focus. This enables an application to perform special processing on the keyboard input. |
| WS_TABSTOP | Turns the control into a tab stop, which enables the user to select the control by tabbing through the controls in a dialog box. |
A scroll bar control is a rectangle that contains a scroll thumb and has direction arrows at both ends. The scroll bar sends a notification message to its parent whenever the user selects the control. The parent is responsible for updating the thumb position, if necessary.
Scroll bar controls have the same appearance and function as the scroll bars used in ordinary windows. But unlike scroll bars, scroll bar controls can be positioned anywhere within a window and used whenever needed to provide scrolling input for a window.
The following table shows scroll bar control styles.
| Style | Description |
| SBS_HORZ | Creates a horizontal scroll bar. The scroll bar has the height, width, and position specified in the CreateWindow function. |
| SBS_VERT | Creates a vertical scroll bar. The scroll bar has the height, width, and position specified in the CreateWindow function. |
Static controls are simple text fields, boxes, and rectangles that can be used to label, box, or separate other controls. Static controls accept no input and provide no output.
In Windows CE, you can use only the SS_CENTERIMAGE style in conjunction with the SS_BITMAP style. Even if you specify SS_ICON, you cannot set the image by calling:
SendMessage( hStatic, STM_SETIMAGE, IMAGE_ICON, (LPARAM) hIcon );
Instead, you have to use:
SendMessage( hStatic, STM_SETIMAGE, IMAGE_BITMAP, (LPARAM) hBitmap );
If you specify SS_CENTERIMAGE, and do not specify either SS_ICON or SS_BITMAP, the static control will behave as though you had specified the SS_BITMAP style.
Windows CE does not support the SS_SIMPLE static control styles, but you can emulate this style by using the SS_LEFT or SS_LEFTNOWORDWRAP style. Windows CE also does not support the SS_BLACKFRAME, SS_BLACKRECT, SS_GRAYFRAME, SS_GRAYRECT, SS_OWNERDRAW, SS_WHITEFRAME, SS_WHITERECT styles but you can use the WM_PAINT message to achieve the same results.
The following table shows static control styles.
| Style | Description |
| SS_BITMAP | Creates a static control that displays a bitmap. The text is the name of a bitmap defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the control automatically sizes itself to accommodate the bitmap. |
| SS_CENTER | Creates a static control with a simple rectangle and centers the error value text in the rectangle. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next centered line. |
| SS_CENTERIMAGE | Specifies that the midpoint of a static control with the SS_BITMAP style remains fixed when you resize the control. The four sides are adjusted to accommodate a new bitmap. If the bitmap is smaller than the control’s client area, the rest of the client area is filled with the color of the pixel in the bitmap’s upper-left corner. |
| SS_ICON | Creates a static control that displays an icon. The text is the name of an icon defined elsewhere in the resource file, not a file name. The style ignores the nWidth and nHeight parameters; the icon automatically sizes itself. |
| SS_LEFT | Creates a static control with a simple rectangle that displays the specified text flush left. Windows CE formats the text before display. The control automatically wraps words that extend past the end of a line to the beginning of the next left-aligned line. |
| SS_LEFTNOWORDWRAP | Specifies a rectangle and left-aligns the text in the rectangle. Tabs are expanded but words are not wrapped. Text that extends past the end of a line is clipped. |
| SS_NOPREFIX | Prevents interpretation of any ampersand (&) characters in the control’s text as accelerator prefix characters.
An application can combine SS_NOPREFIX with other styles by using the bitwise OR ( | ) operator. This can be useful when file names or other strings that may contain an ampersand (&) must be displayed within a static control in a dialog box. |
| SS_NOTIFY | Sends the parent window the STN_CLICKED notification when the user clicks the control. |
| SS_RIGHT | Creates a static control with a simple rectangle that displays the specified text flush right. The text is formatted before it is displayed. Words that would extend past the end of a line are automatically wrapped to the beginning of the next line. |