Specifies a redefined name, character string, or a 16-bit unsigned integer value that defines the class. This can be any one of the control classes; for a list of the control classes, see the first list following this description. 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 specifies the style of the given control. The exact meaning of style depends on the class value. The sections following this description show the control classes and corresponding styles.
For more information on the text, id, x, y, width, height, style, and extended-style parameters, see Common Control Parameters.
The six possible control classes are described in the following sections.
The Button Control Class
A button control is a small rectangular child window that the user can turn on or off by clicking it with the mouse. 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.
A button can have only one of the following styles, with the exception of BS_LEFTTEXT, which can be combined with check boxes and radio buttons:
Style
Meaning
BS_3STATE
Creates a button that is the same as a check box, except that the box can be grayed (dimmed) as well as checked. The grayed state is used to show that the state of the check box is not determined.
BS_AUTO3STATE
Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and normal.
BS_AUTOCHECKBOX
Creates a button that is the same as a check box, except that an X appears in the check box when the user selects the box; the X disappears (is cleared) the next time the user selects the box.
BS_AUTORADIOBUTTON
Creates a button that is the same as a radio button, except that when the user selects it, the button automatically highlights itself and clears (removes the selection from) any other buttons in the same group.
BS_CHECKBOX
Creates a small square that has text displayed to its right (unless this style is combined with the BS_LEFTTEXT style).
BS_DEFPUSHBUTTON
Creates a button that has a heavy black border. The user can select this button by pressing the ENTER key. This style is useful for enabling the user to quickly select the most likely option (the default option).
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_LEFTTEXT
Places text on the left side of the radio button or check box when combined with a radio button or check box style.
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 that has text displayed to its right (unless this style is combined with the BS_LEFTTEXT style). Radio buttons are usually used in groups of related but mutually exclusive choices.
The 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 a "pop box" 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 the list box is visible, typing characters into the selection box will cause the first entry that matches the characters typed to be highlighted. Conversely, selecting an item in the list box displays the selected text in the selection field. Combo box control styles are described below.
Style
Meaning
CBS_SIMPLE
Displays the list box at all times. The current selection in the list box is displayed in the edit control.
CBS_DROPDOWN
Similar to CBS_SIMPLE except that the list box is not displayed unless the user selects an icon next to the selection field.
CBS_DROPDOWNLIST
Similar to CBS_DROPDOWN except that the edit control is replaced by a static text item which displays the current selection in the list box.
CBS_OWNERDRAWFIXED
Specifies a fixed-height owner-draw combo box. The owner of the list box is responsible for drawing its contents; the items in the list box are all the same height.
CBS_OWNERDRAWVARIABLE
Specifies a variable-height owner-draw combo box. The owner of the list box is responsible for drawing its contents; the items in the list box can have different heights.
CBS_AUTOHSCROLL
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_SORT
Sorts strings entered into the list box.
CBS_HASSTRINGS
Specifies an owner-draw combo box that contains items consisting of strings. The combo box maintains the memory and pointers for the strings so that the application can use the LB_GETTEXT message to retrieve the text for a particular item.
CBS_OEMCONVERT
Converts text entered in the combo box edit control from the ANSI character set to the OEM character set and then back to ANSI. This ensures proper character conversion when the application calls the CharToOem function to convert an ANSI string in the combo box to OEM characters. This style is most useful for combo boxes that contain filenames and applies only to combo boxes created with the CBS_SIMPLE or CBS_DROPDOWN styles.
The 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 clicking the mouse inside it or pressing the TAB key. The user can enter text when the control displays a flashing insertion point. The mouse can be used to move the cursor and select characters to be replaced, or to position the cursor for inserting characters. The BACKSPACE key can be used to delete characters.
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. Edit control styles are described below.
Style
Meaning
ES_LEFT
Justifies the text to the left.
ES_CENTER
Centers the text. This style is valid in multiline edit controls only.
ES_RIGHT
Justifies the text to the right. This style is valid in multiline edit controls only.
ES_LOWERCASE
Converts all characters to lowercase as they are typed into the edit control.
ES_UPPERCASE
Converts all characters to uppercase as they are typed into the edit control.
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_MULTILINE
Multiple-line edit control. (The default is single-line.) Shows as many lines of text as possible. The following four styles specify options for horizontal and vertical scrolling.
ES_AUTOVSCROLL
If used, shows as many lines as possible and scrolls vertically when the user presses ENTER.
Otherwise, shows as many lines as possible and beeps if the user presses ENTER when no more lines can be displayed.
ES_AUTOHSCROLL
If used, scrolls horizontally when the insertion point goes past the right edge of the control. To start a new line, press ENTER.
Otherwise, wraps words to the beginning of the next line when necessary. A new line is also started if the user presses ENTER.
A multiline edit control with scroll bars processes its own scroll-bar messages.
ES_AUTOVSCROLL
Scrolls text automatically up one page when the user presses ENTER on the last line.
ES_AUTOHSCROLL
Scrolls text automatically to the right by 10 characters when the user types a character at the end of the line. When the user presses ENTER, the control scrolls all text to position 0.
ES_NOHIDESEL
Overrides the default action, in which an edit control hides the selection when the control loses the input focus. Inverts the selection instead.
ES_OEMCONVERT
Converts text entered in the edit control from the ANSI character set to the OEM character set and then back to ANSI. This ensures proper character conversion when the application calls the CharToOem function to convert an ANSI string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.
The Listbox Control Class
Listbox controls consist of a list of character strings. The control is used whenever an application needs to present a list of names, such as filenames, that the user can view and select. The user can select a string by pointing to the string with the mouse and clicking a mouse button. 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 listbox control to scroll lists that are too long or too wide for the control window. Listbox control styles are described below.
Style
Meaning
LBS_STANDARD
Strings in the list box are sorted alphabetically and the parent window receives an input message whenever the user clicks or double-clicks a string. The list box contains borders on all sides.
LBS_DISABLENOSCROLL
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
The user can select multiple items using the mouse with the SHIFT and/or the CONTROL key or special key combinations.
LBS_HASSTRINGS
An owner-draw list box contains items consisting of strings. The list box maintains the memory and pointers for the strings so the application can use the LB_GETTEXT message to retrieve the text for a particular item.
LBS_NOTIFY
The parent receives an input message whenever the user clicks or double-clicks a string.
LBS_MULTIPLESEL
The string selection is toggled each time the user clicks or double-clicks the string. Any number of strings can be selected.
LBS_MULTICOLUMN
The list box contains multiple columns. The list box can be scrolled horizontally. The LB_SETCOLUMNWIDTH message sets the width of the columns.
LBS_NOINTEGRALHEIGHT
The size of the list box is exactly the size specified by the application when it created the list box. Normally, the system sizes a list box so that the list box does not display partial items.
LBS_SORT
The strings in the list box are sorted alphabetically.
LBS_NOREDRAW
The list-box display is not updated when changes are made. This style can be changed at any time by sending a WM_SETREDRAW message.
LBS_OWNERDRAWFIXED
The owner of the list box is responsible for drawing its contents; the items in the list box are all the same height.
LBS_OWNERDRAWVARIABLE
The owner of the list box is responsible for drawing its contents; the items in the list box are variable in height.
LBS_USETABSTOPS
The list box is able to recognize and expand tab characters when drawing its strings. The default tab positions are set at every 32 dialog units. (A dialog unit is a horizontal or vertical distance. One horizontal dialog unit is equal to 1/4 of the current dialog base width unit. The dialog base units are computed from the height and width of the current system font. The GetDialogBaseUnits function returns the size of the dialog base units in pixels.)
LBS_WANTKEYBOARDINPUT
The owner of the list box receives WM_VKEYTOITEM or WM_CHARTOITEM messages whenever the user presses a key while the list box has input focus. This allows an application to perform special processing on the keyboard input.
The 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 clicks the mouse in 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. Scroll-bar control styles are described below.
Style
Meaning
SBS_VERT
Vertical scroll bar. If neither SBS_RIGHTALIGN nor SBS_LEFTALIGN is specified, the scroll bar has the height, width, and position given in the CreateWindow function.
SBS_RIGHTALIGN
Used with SBS_VERT. The right edge of the scroll bar is aligned with the right edge of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The scroll bar has the default width for system scroll bars.
SBS_LEFTALIGN
Used with SBS_VERT. The left edge of the scroll bar is aligned with the left edge of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The scroll bar has the default width for system scroll bars.
SBS_HORZ
Horizontal scroll bar. If neither SBS_BOTTOMALIGN nor SBS_TOPALIGN is specified, the scroll bar has the height, width, and position given in the CreateWindow function.
SBS_TOPALIGN
Used with SBS_HORZ. The top edge of the scroll bar is aligned with the top edge of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The scroll bar has the default height for system scroll bars.
SBS_BOTTOMALIGN
Used with SBS_HORZ. The bottom edge of the scroll bar is aligned with the bottom edge of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The scroll bar has the default height for system scroll bars.
SBS_SIZEBOX
Size box. If neither SBS_SIZEBOXBOTTOMRIGHTALIGN nor SBS_SIZEBOXTOPLEFTALIGN is specified, the size box has the height, width, and position given in the CreateWindow function.
SBS_SIZEBOXTOPLEFTALIGN
Used with SBS_SIZEBOX. The top-left corner of the size box is aligned with the top-left corner of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The size box has the default size for system size boxes.
SBS_SIZEBOXBOTTOMRIGHTALIGN
Used with SBS_SIZEBOX. The bottom-right corner of the size box is aligned with the bottom-right corner of the rectangle specified by the x, y, width, and height values given in the CreateWindow function. The size box has the default size for system size boxes.
The 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 take no input and provide no output. Static control styles are described below.
Style
Meaning
SS_LEFT
A simple rectangle displaying the given text flush left. 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.
SS_CENTER
A simple rectangle displaying the given text centered. 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.
SS_RIGHT
A simple rectangle displaying the given 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.
SS_LEFTNOWORDWRAP
A simple rectangle displaying the given text flush left. Tabs are expanded, but words are not wrapped. Text that extends past the end of a line is clipped.
SS_SIMPLE
A simple rectangle with a single line of text flush left. The line of text cannot be shortened or altered in any way. (The control's parent window or dialog box must not process the WM_CTLCOLOR message.)
SS_NOPREFIX
Removes any ampersand (&) characters and underlines the next character in the string. Unless this style is specified, the system will interpret any ampersand characters in the control's text to be accelerator prefix characters. If a static control is to contain text where this feature is not wanted, SS_NOPREFIX may be added. This static-control style may be included with any of the defined static controls. You can combine SS_NOPREFIX with other styles by using the bitwise OR (|) operator. This is most often used when filenames or other strings that may contain an ampersand need to be displayed in a static control in a dialog box.
SS_ICON
An icon displayed in the dialog box. The given text is the name of an icon (not a filename) defined elsewhere in the resource file. For the ICON statement, the width and height parameters in the CreateWindow function are ignored; the icon automatically sizes itself.
SS_BLACKRECT
A rectangle filled with the color used to draw window frames. This color is black in the default color scheme.
SS_GRAYRECT
A rectangle filled with the color used to fill the screen background. This color is gray in the default color scheme.
SS_WHITERECT
A rectangle filled with the color used to fill window backgrounds. This color is white in the default color scheme.
SS_BLACKFRAME
Box with a frame drawn with the same color as window frames. This color is black in the default color scheme.
SS_GRAYFRAME
Box with a frame drawn with the same color as the screen background (desktop). This color is gray in the default color scheme.
SS_WHITEFRAME
Box with a frame drawn with the same color as window backgrounds. This color is white in the default color scheme.