HWND CreateWindowEx(
DWORD dwExStyle, // extended window style
LPCTSTR lpClassName, // registered class name
LPCTSTR lpWindowName, // window name
DWORD dwStyle, // window style
int x, // horizontal position of window
int y, // vertical position of window
int nWidth, // window width
int nHeight, // window height
HWND hWndParent, // handle to parent or owner window
HMENU hMenu, // menu handle or child identifier
HINSTANCE hInstance, // handle to application instance
LPVOID lpParam // window-creation data
);
Parameters
- dwExStyle Specifies the extended window style of the window being created. See Windows Styles.
- lpClassName Pointer to a null-terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-order word of lpClassName; the high-order word must be zero.
If lpClassName is a string, it specifies the window class name. The class name can be any name registered with RegisterClass or RegisterClassEx, provided that the module that registers the class is also the module that creates the window. The class name can also be any of the predefined system class names.
- lpWindowName Pointer to a null-terminated string that specifies the window name.
If the window style specifies a title bar, the window title pointed to by lpWindowName is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use lpWindowName to specify the text of the control. When creating a static control with the SS_ICON style, use lpWindowName to specify the icon name or identifier. To specify an identifier, use the syntax "#num".
- dwStyle Specifies the style of the window being created. This parameter can be a combination of window styles, plus the control styles indicated in the Remarks section.
- x Specifies the initial horizontal 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. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window's client area.
If x is set to CW_USEDEFAULT, the system selects the default position for the window's upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.
- y Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box's client area relative to the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, the system ignores the y parameter.
- nWidth Specifies the width, in device units, of the window. For overlapped windows, nWidth is the window's width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, the system selects a default width and height for the window; the default width extends from the initial x-coordinates to the right edge of the screen; the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and nHeight parameter are set to zero.
- nHeight Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen coordinates. If the nWidth parameter is set to CW_USEDEFAULT, the system ignores nHeight.
- hWndParent Handle to the parent or owner window of the window being created. To create a child window or an owned window, supply a valid window handle. This parameter is optional for pop-up windows.
Windows 2000 or later: To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.
- hMenu Handle to a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.
- hInstance Windows 95/98/Me: Handle to the instance of the module to be associated with the window.
Windows NT/2000 or later: This value is ignored.
- lpParam Pointer to a value to be passed to the window through the programming:windows:CREATESTRUCT structure passed in the lParam parameter the WM_CREATE message. If an application calls CreateWindow to create a multiple document interface (MDI) client window, lpParam must point to a CLIENTCREATESTRUCT structure.
Return Values
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
This function typically fails for one of the following reasons:
- an invalid parameter value
- the system class was registered by a different module
- the WH_CBT hook is installed and returns a failure code
- the window procedure fails for WM_CREATE or WM_NCCREATE
Remarks
The CreateWindowEx function sends the following messages to the window being created:
For information on controlling whether the Taskbar displays a button for the created window, see Visibility of Taskbar Buttons.
Windows 95: The system can support a maximum of 16,364 window handles.
Windows 2000 or later: The WS_EX_NOACTIVATE value for dwExStyle prevents foreground activation by the system. To prevent queue activation when the user clicks on the window, you must process the WM_MOUSEACTIVATE message appropriately. To bring the window to the foreground or to activate it programmatically, use SetForegroundWindow or SetActiveWindow. Returning FALSE to WM_NCACTIVATE prevents the window from losing queue activation. However, the return value is ignored at activation time.
Whistler: With WS_EX_COMPOSITED set, all descendants of a window get bottom-to-top painting order using double-buffering. Bottom-to-top painting order allows a descendent window to have translucency (alpha) and transparency (color-key) effects, but only if the descendent window also has the WS_EX_TRANSPARENT bit set. Double-buffering allows the window and its descendents to be painted without flicker.
For an example, see Creating a Main Window.
Requirements
- Windows NT/2000 or later: Requires Windows NT 3.1 or later.
- Windows 95/98/Me: Requires Windows 95 or later.
- Header: Declared in Winuser.h; include Windows.h.
- Library: Use User32.lib.
- Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.