CONTROL text, id, class, style, x, y, width, height
This statement defines a user-defined control window.
The text field takes an ASCII string that specifies the text to be displayed. The string must be enclosed in double quotation marks.
The id field takes a unique integer value that identifies the control.
The class field takes a predefined name, character string, or 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 predefined name supplied by the application, it must be an ASCII string enclosed in double quotation marks.
The style field takes a predefined name or integer value that specifies the style of the given control. The exact meaning of style depends on the class value. Two lists following this description show the control classes and corresponding styles.
The x and y fields take integer values that specify the x and y coordinates of the upper-left corner of the control. The horizontal units are 1/4 of the dialog base width unit; the vertical units are 1/8 of the dialog base height unit. The current dialog base units are computed from the height and width of the current system font. The GetDialogBaseUnits function returns the dialog base units in pixels. The coordinates are relative to the origin of the dialog box.
The width and height fields take integer values that specify the width and height of the control. The width units are 1/4 of the dialog base width unit; the height units are 1/8 of the dialog base height unit.
Summary: Comments
The x, y, width, and height fields can use the addition operator (+) for relative positioning. For example, 15 + 6 can be used for the x field.
The six control classes are described in the following sections.
A button control is a small rectangular child window that represents a “button” 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. Button control styles are described below.
BS_PUSHBUTTON
A small elliptical button containing the given text. The control sends a message to its parent whenever the user clicks the mouse inside the rectangle.
BS_DEFPUSHBUTTON
A small elliptical button with a bold border. This button represents the default user response. Any text is displayed within the button. Windows sends a message to the parent window when the user clicks the mouse in this button.
BS_CHECKBOX
A small rectangular button that can be checked; its border becomes bold when the user clicks the mouse in it. Any text appears to the right of the button.
BS_AUTOCHECKBOX
Identical to BS_CHECKBOX except that the button automatically toggles its state whenever the user clicks it.
BS_RADIOBUTTON
A small circular button whose border becomes bold when the user clicks the mouse in it. In addition, to make the border bold, Windows sends a message to the button's parent notifying it that a click occurred. On the next click, Windows makes the border normal again and sends another message.
BS_AUTORADIOBUTTON
Identical to BS_RADIOBUTTON except that when the button is checked, the application is notified with BN_CLICKED, and all other radio buttons in the group are unchecked.
BS_LEFTTEXT
Text appears on the left side of the radio button or check box. Use this style with BS_CHECKBOX, BS_3STATE, or BS_RADIOBUTTON styles.
BS_3STATE
Identical to BS_CHECKBOX except that a button can be grayed as well as checked or unchecked. The grayed state is typically used to show that a check box has been disabled.
BS_AUTO3STATE
Identical to BS_3STATE except that the button automatically toggles its state when the user clicks it.
BS_GROUPBOX
A rectangle into which other buttons are grouped. Any text is displayed in the rectangle's upper-left corner.
BS_OWNERDRAW
An owner-draw button. The parent window is notified when the button is clicked. Notification includes a request to paint, invert, and disable the button.
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 list-box 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.
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 AnsiToOem 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.
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 ANSI 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.
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 specified
Shows as many lines as possible and scrolls vertically when the user presses the ENTER key. (This is actually the carriage-return character, which the edit control expands to a carriage-return/line-feed combination.)
ES_AUTOVSCROLL not specified
Shows as many lines as possible and beeps if the user presses ENTER when no more lines can be displayed.
ES_AUTOHSCROLL specified
Scrolls horizontally when the insertion point goes past the right edge of the control. To start a new line, press the ENTER key.
ES_AUTO-HSCROLL not specified
Wraps words to the beginning of the next line when necessary. A new line is also started if the user presses ENTER. If the window size changes, the wordwrap position changes, and the text is redisplayed.
Multiple-line 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 above, and process any scroll messages sent by the parent window.
ES_AUTOVSCROLL
Scrolls text automatically up one page when the user presses the ENTER key 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 the ENTER key, the control scrolls all text back 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 AnsiToOem function to convert an ANSI string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.
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 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 list-box control to scroll lists that are too long or too wide for the control window. Listbar control styles are described below.
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_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, Windows 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 draw-ing 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 when the list box has input focus. This allows an application to perform special processing on the keyboard input.
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.
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.
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.
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 (&) characters and underlines the next character in the string. Unless this style is specified, Windows will interpret any (&) 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 (&) 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 Windows color scheme.
SS_GRAYRECT
A rectangle filled with the color used to fill the screen background. This color is gray in the default Windows color scheme.
SS_WHITERECT
A rectangle filled with the color used to fill window backgrounds. This color is white in the default Windows color scheme.
SS_BLACKFRAME
Box with a frame drawn with the same color as window frames. This color is black in the default Windows 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 Windows color scheme.
SS_WHITEFRAME
Box with a frame drawn with the same color as window backgrounds. This color is white in the default Windows color scheme.
SS_USERITEM
User-defined item.