CreateWindow
Syntax
HWND CreateWindow(lpClassName,lpWindowName,dwStyle,X,Y,nWidth,nHeight,hWndParent,hMenu,hInstance,lpParam)
This function creates an overlapped, pop-up, or child window. The CreateWindow function specifies the window class, window title, window style, and (optionally) initial position and size of the window. The CreateWindow function also specifies the window's parent (if any) and menu.
For overlapped, pop-up, and child windows, the CreateWindow function sends WM_CREATE, WM_GETMINMAXINFO, and WM_NCCREATE messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT data structure. If WS_VISIBLE style is given, CreateWindow sends the window all the messages required to activate and show the window.
If the window style specifies a title bar, the window title pointed to by the lpWindowName parameter is displayed in the title bar. When using CreateWindow to create controls such as buttons, check boxes, and text controls, the lpWindowName parameter specifies the text of the control.
| Parameter |
Type/Description |
|
| lpClassName |
LPSTR Points to a null-terminated character string that names the window class. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names specified in Table R.2, “Control Classes.” |
|
| lpWindowName |
LPSTR Points to a null-terminated character string that represents the window name. |
|
| dwStyle |
DWORD Specifies the style of window being created. It can be any combination of the styles given in Table R.3, “Window Styles,” the control styles given in Table 4.4, “Control Styles,” or a combination of styles created by using the bitwise OR operator. |
|
| X |
int Specifies the initial x-position of the window. For an overlapped or pop-up window, the X parameter is the initial x-coordinate of the window's upper-left corner (in screen coordinates). If this value is CW_USEDEFAULT, Windows selects the default position for the window's upper-left corner. For a child window, X is the x-coordinate of the upper-left corner of the window in the client area of its parent window. |
|
| Y |
int Specifies the initial y-position of the window. For an overlapped window, the Y parameter is the initial y-coordinate of the window's upper-left corner. For a pop-up window, Y is the y-coordinate (in screen coordinates) of the upper-left corner of the pop-up window. For list-box controls, Y is the y-coordinate of the upper-left corner of the control's client area. For a child window, Y is the y-coordinate of the upper-left corner of the child window. All of these coordinates are for the window, not the window's client area. |
|
| nWidth |
int Specifies the width (in device units) of the window. For overlapped windows, the nWidth parameter is either the window's width (in screen coordinates) or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a default width and height for the window (the default width extends from the initial x-position to the right edge of the screen, and the default height extends from the initial y-position to the top of the icon area). |
|
| nHeight |
int Specifies the height (in device units) of the window. For overlapped windows, the nHeight parameter is the window's height in screen coordinates. If the nWidth parameter is CW_USEDEFAULT, Windows ignores nHeight. |
|
| hWndParent |
HWND Identifies the parent or owner window of the window being created. A valid window handle must be supplied when creating a child window or an owned window. An owned window is an overlapped window that is destroyed when its owner window is destroyed, hidden when its owner is made iconic, and which is always displayed on top of its owner window. For pop-up windows, a handle can be supplied, but is not required. If the window does not have a parent or is not owned by another window, the hWndParent parameter must be set to NULL. |
|
| hMenu |
HMENU Identifies a menu or a child-window identifier. The meaning depends on the window style. For overlapped or pop-up windows, the hMenu parameter identifies the menu to be used with the window. It can be NULL, if the class menu is to be used. For child windows, hMenu specifies the child-window identifier, an integer value that is used by a dialog-box control to notify its parent of events (such as the EN_HSCROLL message). The child-window identifier is determined by the application and should be unique for all child windows with the same parent window. |
|
| hInstance |
HANDLE Identifies the instance of the module to be associated with the window. |
|
| lpParam |
LPSTR Points to a value that is passed to the window through the CREATESTRUCT data structure referenced by the lParam parameter of the WM_CREATE message. If an application is calling CreateWindow to create a multiple document interface (MDI) client window, lpParam must point to a CLIENTCREATESTRUCT data structure. |
|
Return Value
The return value identifies the new window. It is NULL if the window is not created.
Comments
For overlapped windows where the X parameter is CW_USEDEFAULT, the Y parameter can be one of the show-style parameters described with the ShowWindow function, or, for the first overlapped window to be created by the application, it can be the nCmdShow parameter passed to the WinMain function.
Table R.2 lists the window control classes; Table R.3 lists the window styles; Table R.4 lists the control styles:
Table R.2 Control Classes
| Class |
Meaning |
| BUTTON |
Designates a small rectangular child window that represents a button the user can turn on or off by clicking it. 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. |
| COMBOBOX |
Designates a control consisting 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. |
| EDIT |
Designates 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 it or moving to it by using the TAB key. The user can enter text when the control displays a flashing caret. 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 variable-pitch system font and display ANSI characters. Applications compiled to run with previous versions of Windows display text with a fixed-pitch system font unless they have been marked by the Windows 3.0 MARK utility with the MEMORY FONT option. An application can also send the WM_SETFONT message to the edit control to change the default font. |
Table R.2 Control Classes (continued)
| Class |
Meaning |
| |
Edit controls 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. |
| LISTBOX |
Designates a list of character strings. This 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 it and clicking. When a string is selected, it is highlighted and a notification message is passed to the parent window. A vertical or horizontal scroll bar can be used with a list-box control to scroll lists that are too long for the control window. The list box automatically hides or shows the scroll bar as needed. |
| MDICLIENT |
Designates an MDI client window. The MDI client window receives messages which control the MDI application's child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. To create a scrollable MDI client window which allows the user to scroll MDI child windows into view, an application can also use the WS_HSCROLL and WS_VSCROLL styles. |
| SCROLLBAR |
Designates a rectangle that contains a thumb and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the thumb position, if necessary. Scroll-bar controls have the same appearance and function as scroll bars used in ordinary windows. Unlike scroll bars, scroll-bar controls can be positioned anywhere in a window and used whenever needed to provide scrolling input for a window. |
| |
The scroll-bar class also includes size-box controls. A size-box control is a small rectangle that the user can expand to change the size of the window. |
| STATIC |
Designates a simple text field, box, or rectangle that can be used to label, box, or separate other controls. Static controls take no input and provide no output. |
Table R.3 Window Styles
| Style |
Meaning |
| DS_LOCALEDIT |
Specifies that edit controls in the dialog box will use memory in the application's data segment. By default, all edit controls in dialog boxes use memory outside the application's data segment. This feature may be suppressed by adding the DS_LOCALEDIT flag to the STYLE command for the dialog box. If this flag is not used, EM_GETHANDLE and EM_SETHANDLE messages must not be used since the storage for the control is not in the application's data segment. This feature does not affect edit controls created outside of dialog boxes. |
| DS_MODALFRAME |
Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles. |
| DS_NOIDLEMSG |
Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed. |
| DS_SYSMODAL |
Creates a system-modal dialog box. |
| WS_BORDER |
Creates a window that has a border. |
| WS_CAPTION |
Creates a window that has a title bar (implies the WS_BORDER style). This style cannot be used with the WS_DLGFRAME style. |
| WS_CHILD |
Creates a child window. Cannot be used with the WS_POPUP style. |
| WS_CHILDWINDOW |
Creates a child window that has the WS_CHILD style. |
| WS_CLIPCHILDREN |
Excludes the area occupied by child windows when drawing within the parent window. Used when creating the parent window. |
| WS_CLIPSIBLINGS |
Clips child windows relative to each other; that is, when a particular child window receives a paint message, the WS_CLIPSIBLINGS style clips all other overlapped child windows out of the region of the child window to be updated. (If WS_CLIPSIBLINGS is not given and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.) For use with the WS_CHILD style only. |
Table R.3 Window Styles (continued)
| Style |
Meaning |
| WS_DISABLED |
Creates a window that is initially disabled. |
| WS_DLGFRAME |
Creates a window with a double border but no title. |
| WS_GROUP |
Specifies the first control of a group of controls in which the user can move from one control to the next by using the DIRECTION keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the style group and starts the next group (that is, one group ends where the next begins). Only dialog boxes use this style. |
| WS_HSCROLL |
Creates a window that has a horizontal scroll bar. |
| WS_ICONIC |
Creates a window that is initially iconic. For use with the WS_OVERLAPPED style only. |
| WS_MAXIMIZE |
Creates a window of maximum size. |
| WS_MAXIMIZEBOX |
Creates a window that has a maximize box. |
| WS_MINIMIZE |
Creates a window of minimum size. |
| WS_MINIMIZEBOX |
Creates a window that has a minimize box. |
| WS_OVERLAPPED |
Creates an overlapped window. An overlapped window has a caption and a border. |
| WS_OVERLAPPEDWINDOW |
Creates an overlapped window having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. |
| WS_POPUP |
Creates a pop-up window. Cannot be used with the WS_CHILD style. |
| WS_POPUPWINDOW |
Creates a pop-up window that has the WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION style must be combined with the WS_POPUPWINDOW style to make the system menu visible. |
| WS_SYSMENU |
Creates a window that has a System-menu box in its title bar. Used only for windows with title bars. |
| WS_TABSTOP |
Specifies one of any number of controls through which the user can move by using the TAB key. The TAB key moves the user to the next control specified by the WS_TABSTOP style. Only dialog boxes use this style. |
| WS_THICKFRAME |
Creates a window with a thick frame that can be used to size the window. |
| WS_VISIBLE |
Creates a window that is initially visible. This applies to overlapped and pop-up windows. For overlapped windows, the Y parameter is used as a ShowWindow function parameter. |
| WS_VSCROLL |
Creates a window that has a vertical scroll bar. |
Table R.4 Control Styles
| Style |
Meaning |
| BUTTON Class, |
|
| BS_AUTOCHECKBOX |
Identical to BS_CHECKBOX, except that the button automatically toggles its state whenever the user clicks it. |
| BS_AUTORADIOBUTTON |
Identical to BS_RADIOBUTTON, except that the button is checked, the application is notified by BN_CLICKED, and the checkmarks are removed from all other radio buttons in the group. |
| BS_AUTO3STATE |
Identical to BS_3STATE, except that the button automatically toggles its state when the user clicks it. |
| BS_CHECKBOX |
Designates a small rectangular button that may be checked; its border is bold when the user clicks the button. Any text appears to the right of the button. |
| BS_DEFPUSHBUTTON |
Designates a 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 button. |
| BS_GROUPBOX |
Designates a rectangle into which other buttons are grouped. Any text is displayed in the rectangle's upper-left corner. |
| BS_LEFTTEXT |
Causes text to appear on the left side of the radio button or check-box button. Use this style with the BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE styles. |
Table R.4 Control Styles (continued)
| Style |
Meaning |
| BS_OWNERDRAW |
Designates 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. |
| BS_PUSHBUTTON |
Designates a button that contains the given text. The control sends a message to its parent window whenever the user clicks the button. |
| BS_RADIOBUTTON |
Designates a small circular button that can be checked; its border is bold when the user clicks the button. Any text appears to the right of the button. Typically, two or more radio buttons are grouped together to represent mutually exclusive choices, so no more than one button in the group is checked at any time. |
| BS_3STATE |
Identical to BS_CHECKBOX, except that a button can be grayed as well as checked. The grayed state typically is used to show that a check box has been disabled. |
| CBS_AUTOHSCROLL |
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 which fits within the rectangular boundary is allowed. |
| 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_HASSTRINGS |
An owner-draw combo box contains items consisting of strings. The combo 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. |
| CBS_OEMCONVERT |
Text entered in the combo box edit control is converted 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. |
| CBS_OWNERDRAWFIXED |
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 |
The owner of the list box is responsible for drawing its contents; the items in the list box are variable in height. |
| CBS_SIMPLE |
The list box is displayed at all times. The current selection in the list box is displayed in the edit control. |
| CBS_SORT |
Automatically sorts strings entered into the list box. |
| ES_AUTOHSCROLL |
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 |
Automatically scrolls text up one page when the user presses ENTER on the last line. |
| ES_CENTER |
Centers text in a multiline edit control. |
| ES_LEFT |
Aligns text flush-left. |
| ES_LOWERCASE |
Converts all characters to lowercase as they are typed into the edit control. |
| ES_MULTILINE |
Designates multiple-line edit control. (The default is single-line.) If 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 ES_AUTOVSCROLL is not given, the edit control shows as many lines as possible and beeps if ENTER is pressed when no more lines can be displayed. |
| |
If the ES_AUTOHSCROLL style is specified, the multiple-line edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press ENTER. If ES_AUTOHSCROLL is not given, the control automatically wraps words to the beginning of the next line when necessary; a new line is also started if ENTER is pressed. The position of the wordwrap is determined by the window size. 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_NOHIDESEL |
Normally, an edit control hides the selection when the control loses the input focus, and inverts the selection when the control receives the input focus. Specifying ES_NOHIDESEL deletes this default action. |
| ES_OEMCONVERT |
Text entered in the edit control is converted 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. |
| 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_RIGHT |
Aligns text flush-right in a multiline edit control. |
| ES_UPPERCASE |
Converts all characters to uppercase as they are typed into the edit control. |
| LBS_EXTENDEDSEL |
The user can select multiple items using the SHIFT key and the mouse or special key combinations. |
| LBS_HASSTRINGS |
Specifies an owner-draw list box which 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_MULTICOLUMN |
Specifies a multicolumn list box that is scrolled horizontally. The LB_SETCOLUMNWIDTH message sets the width of the columns. |
| LBS_MULTIPLESEL |
String selection is toggled each time the user clicks or double-clicks the string. Any number of strings can be selected. |
| 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_NOREDRAW |
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_NOTIFY |
Parent window receives an input message whenever the user clicks or double-clicks a string. |
| LBS_OWNERDRAWFIXED |
The owner of the list box is responsible for drawing its contents; the items in the list box are 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_SORT |
Strings in the list box are sorted alphabetically. |
| 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_USETABSTOPS |
Allows a list box to recognize and expand tab characters when drawing its strings. The default tab positions are 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 based on the height and width of the current system font. The GetDialogBaseUnits function returns the current 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. |
| SBS_BOTTOMALIGN |
Used with the SBS_HORZ style. The bottom edge of the scroll bar is aligned with the bottom edge of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The scroll bar has the default height for system scroll bars. |
| SBS_HORZ |
Designates a horizontal scroll bar. If neither the SBS_BOTTOMALIGN nor SBS_TOPALIGN style is specified, the scroll bar has the height, width, and position given in the CreateWindow function. |
| SBS_LEFTALIGN |
Used with the SBS_VERT style. The left edge of the scroll bar is aligned with the left edge of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The scroll bar has the default width for system scroll bars. |
| SBS_RIGHTALIGN |
Used with the SBS_VERT style. The right edge of the scroll bar is aligned with the right edge of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The scroll bar has the default width for system scroll bars. |
| SBS_SIZEBOX |
Designates a size box. If neither the SBS_SIZEBOXBOTTOMRIGHTALIGN nor SBS_SIZEBOXTOPLEFTALIGN style is specified, the size box has the height, width, and position given in the CreateWindow function. |
| SBS_SIZEBOXBOTTOMRIGHTALIGN |
Used with the SBS_SIZEBOX style. The lower-right corner of the size box is aligned with the lower-right corner of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The size box has the default size for system size boxes. |
| SBS_SIZEBOXTOPLEFTALIGN |
Used with the SBS_SIZEBOX style. The upper-left corner of the size box is aligned with the upper-left corner of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The size box has the default size for system size boxes. |
| SBS_TOPALIGN |
Used with the SBS_HORZ style. The top edge of the scroll bar is aligned with the top edge of the rectangle specified by the X, Y, nWidth, and nHeight parameters given in the CreateWindow function. The scroll bar has the default height for system scroll bars. |
| SBS_VERT |
Designates a vertical scroll bar. If neither the SBS_RIGHTALIGN nor SBS_LEFTALIGN style is specified, the scroll bar has the height, width, and position given in the CreateWindow function. |
| SS_BLACKFRAME |
Specifies a box with a frame drawn with the same color as window frames. This color is black in the default Windows color scheme. |
| SS_BLACKRECT |
Specifies a rectangle filled with the color used to draw window frames. This color is black in the default Windows color scheme. |
| SS_CENTER |
Designates a simple rectangle and displays the given text centered in the rectangle. 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 centered line. |
| SS_GRAYFRAME |
Specifies a 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_GRAYRECT |
Specifies a rectangle filled with the color used to fill the screen background. This color is gray in the default Windows color scheme. |
| SS_ICON |
Designates 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. The nWidth and nHeight parameters are ignored; the icon automatically sizes itself. |
| SS_LEFT |
Designates a simple rectangle and displays the given text flush-left in the rectangle. 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 flush-left line. |
| SS_LEFTNOWORDWRAP |
Designates a simple rectangle and displays the given text flush-left in the rectangle. Tabs are expanded, but words are not wrapped. Text that extends past the end of a line is clipped. |
| SS_NOPREFIX |
Unless this style is specified, windows will interpret any “&” characters in the control's text to be accelerator prefix characters. In this case, the “&” is removed and the next character in the string is underlined. 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_RIGHT |
Designates a simple rectangle and displays the given text flush-right in the rectangle. 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 flush-right line. |
| SS_SIMPLE |
Designates a simple rectangle and displays a single line of text flush-left in the rectangle. 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_USERITEM |
Specifies a user-defined item. |
| SS_WHITEFRAME |
Specifies a box with a frame drawn with the same color as window backgrounds. This color is white in the default Windows color scheme. |
| SS_WHITERECT |
Specifies a rectangle filled with the color used to fill window backgrounds. This color is white in the default Windows color scheme. |