CONTROL Control

Article
06/30/2006

This resource-definition statement creates a user-defined control.

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.

Button Control Class

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 Control Class

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.

Edit Control Class

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.

Listbox Control Class

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.

Scroll Bar Control Class

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 Control Class

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 );

The SS_CENTERIMAGE style cannot be set by itself. It must always be set in combination--through a bitwise OR--with the SS_BITMAP style or the SS_ICON 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. Windows CE does not support the SS_SUNKEN, SS_RIGHTJUST, and SS_REALSIZEIMAGE styles.

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 or SS_ICON style will remain 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 upper-left corner of the bitmap. The SS_CENTERIMAGE style cannot be set by itself. It must always be set in combination--through a bitwise OR--with the SS_BITMAP style or the SS_ICON style. Do not use SS_CENTERIMAGE for a static control that contains text.
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.

Last updated on Tuesday, July 13, 2004