WinCreateWindow

Creates a new window of class pszClass.

Syntax

WinCreateWindow ( hwndParent, pszClass, pszText, flStyle,
                  x, y, cx, cy, hwndOwner, hwndBehind, id,
                  pCtrlData, pPresParams )

Usage Explanation

This API creates most of the windows in you see in OS/2, including main windows, entry fields, scroll bars and so on. Many of these windows can be created by use of a dialog template, but many others can not. This is probably one of the most used APIs during the startup phase of any application. It takes some practice to get used to the way it works, as it has way too many options.

This API sends WM_CREATE and WM_ADJUSTWINDOWPOS messages during window creation. The size can be set during the WM_CREATE message. It is also common to follow the WinCreateWindow call (with the window not set to visible) with a WinSetWindowPos call, during which size and position are set.

If this API is used to create a menu (WC_MENU), then pCtrlData should point to the menu template.

WM_CREATE is the first message a newly created window will receive, but the window is not yet visible when this message is received, and may have no size yet.

Parameters

HWND hwndParent (input)

Handle to parent window. If HWND_DESKTOP is specified, a main window is created.

PSZ pszClass (input)

Class name. Must already either be registered via WinRegisterClass, or be a pre-defined PM class. This could be one of the following:

Class	Control Data	Explanation
WC_BUTTON	BTNCDATA	There are many different types of buttons, including some which have their own class name.
WC_CIRCULARSLIDER	N/A	This was adopted from MMOS2, and looks like a volume control.
WC_COMBOBOX	COMBOCDATA	Entryfield/list box combination.
WC_CONTAINER	CNRINFO	Container control, ie. folder-like control.
WC_ENTRYFIELD	ENTRYFDATA	Entryfield. This needs subclassing if you need to have a numerical control only.
WC_FRAME	FRAMECDATA	Window frame control.
WC_LISTBOX	LBOXINFO	List box control. This needs filling at some point.
WC_MENU	N/A	Menu control. Can be either an action bar, or a pop-up menu.
WC_MLE	MLECTLDATA	Multi-Line Edit control. Can be used for simple editors.
WC_NOTEBOOK	BOOKPAGEINFO	Notebook control. This is the control in which the pages are created, not the frame.
WC_SCROLLBAR	SBCDATA	Horizontal or vertical scroll bar. This needs sizing, and should not be used where a slider is more appropriate.
WC_SLIDER	SLDCDATA	Horizontal or vertical slider.
WC_SPINBUTTON	SPBCDATA	Spin button control. You will need to fill it.
WC_STATIC	N/A	A static display of either text or bitmap.
WC_TITLEBAR	N/A	Title bar.
WC_VALUESET	VSCDATA	Value set control. You will need to supply some bitmap for this.

PSZ pszText (input)

Window text. What happens with this text is specific to the class.

ULONG flStyle (input)

Window style. Usually chosen from pre-defined PM constants, but you can also create your own styles for your own classes. Here are the pre-defined PM styles:

WS_ANIMATE	Enables WPS animation, unless user has disabled this feature.
WS_CLIPCHILDREN	Window cannot draw on children.
WS_CLIPSIBLINGS	Window cannot draw on siblings.
WS_DISABLED	Creates window disabled. This might be desirable for filling list boxes, and so on. WinEnableWindow must be used later.
WS_GROUP	Start a new group for dialog box purposes. This should not be used on every window in the group, only the first one.
WS_MAXIMIZED	Create this window maximized. Used only with frame windows.
WS_MINIMIZED	Create this window minimized. Used only with frame windows.
WS_PARENTCLIP	Window created with this style cannot draw outside their parents, but they CAN draw on their parent, so care sould be used.
WS_SAVEBITS	PM will save the pixels underneath this window for when this window closes and moves away. This is faster, but uses more memory. With todays fast systems, if you are not concerned about higher RAM usage, this should be on.
WS_SYNCPAINTS	WM_PAINT messages will be sent, rather than posted.
WS_TABSTOP	Specifies that pressing tab in a dialog box will move the focus to this window. Otherwise it will be skipped.
WS_VISIBLE	Without this style, the window will be created invisible, and will have to be displayed later with WinSetWindowPos or WinShowWindow. The window also has to have size to be displayed, but may come up underneath other windows.

LONG x (input)

X position of lower left corner. Measured from left edge of screen, if HWND_DESKTOP is specified for parent. Otherwise measured from left edge of parent.

LONG y (input)

Y position of lower left corner. Measured from lower edge of screen, if HWND_DESKTOP is specified for parent. Otherwise measured from lower edge of parent.

LONG cx (input)

Width of window in pixels.

LONG cy (input)

Height of window in pixels.

HWND hwndOwner (input)

Owner of window. The owner will receive all notification messages regarding this window. This is usually HWND_DESKTOP for main windows, and hwndParent for other windows.

HWND hwndBehind (input)

The handle of the sibling window behind which this window will appear in the z-order. Usually HWND_TOP or HWND_BOTTOM for main windows.

ULONG id (input)

A value given by programmer for identification of the window by owner. between 0x0000 and 0xFFFF.

PVOID pCtrlData (input)

You can pass the class-specific data in the WM_CREATE message through this parameter. This is a pointer to a Control Data structure (see below). Frequently NULL.

PVOID pPresParams (input)

Pointer to class-specific presentation data passed to the window procedure in WM_CREATE.

Returns

HWND hwnd

Handle to the newly created window. NULLHANDLE is returned if there was an error.

NULLHANDLE : Error occurred

Other : Window handle.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

PMERR_INVALID_FLAG (0x1019)

An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.

PMERR_NO_MSG_QUEUE (0x1036)

PMERR_INVALID_PARM (0x1303)

A parameter to the function contained invalid data.

PMERR_INVALID_PARAMETERS (0x1208)

An application parameter value is invalid for its converted PM type. For example: a 4-byte value outside the range -32 768 to +32 767 cannot be converted to a SHORT, and a negative number cannot be converted to a ULONG or USHORT.

Include Info

#define INCL_WINWINDOWMGR
#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

Relevant Structures

Control Data structures include the following:

• BOOKPAGEINFO
• BTNCDATA
• COMBOCDATA
• CNRINFO
• ENTRYFDATA
• FRAMECDATA
• LBOXINFO
• MLECTLDATA
• SBCDATA
• SLDCDATA
• SPBCDATA
• VSCDATA

Remarks

The appearance and behavior of a window are determined by its style, which is the combination of the style established by pszClass and flStyle ORed together. Any of the standard styles WS_* can be used in addition to any class-specific styles that may be defined.

A window is usually created enabled and invisible. For more information on the initial state of a created window, see the list of the standard window styles.

Messages may be received from other processes or threads when this function is called.

This function sends the WM_CREATE message to the window procedure of the window being created.

This function sends the WM_ADJUSTWINDOWPOS message after the WM_CREATE message, and before the window is displayed (if applicable). The values passed are those given to the WinCreateWindow function. If the window has style WS_VISIBLE, the window is created visible.

The WM_SIZE message is not sent by the WinCreateWindow function while the window is being created. Any required size processing can be performed during the processing of the WM_CREATE message.

Because windows are often created with zero height or width and sized later, it is good practice not to perform any size-related processing if the size of the window is zero.

If the WinCreateWindow function is called for a window of class WC_FRAME, the controls specified by are created but not formatted. The frame is formatted when a WM_FORMATFRAME message is received but this is not sent during window creation. To cause the frame to format, either a WM_FORMATFRAME message must be sent, or the window position adjusted using the WinSetWindowPos function call which sends a WM_SIZE message if the position or size is changed.

The only limitation to the size and position specified for a window is the number range allowed for the size and position parameters; that is, an application can create windows that are larger than the screen or that are positioned partially or totally off the screen. However, the user interface for manipulation of window sizes and positions is affected if part or all of the window is off the screen.

It is recommended that part of the title bar be left on the screen, if the window has one, to enable the user to move the window around.

When a WC_MENU window is created with this call, pCtlData is assumed to be a menu template, which is used to create the menu. If pCtlData is NULL, an empty menu is created.

Sample Code

#define INCL_WINMESSAGEMGR
#include <os2.h>

ULONG flStyle = WS_VISIBLE;

WinCreateWindow (hwndFrame,            // Parent Window Handle
                 "CLIENT",             // Class Name
                 NULL,                 // Window Text
                 flStyle,              // Window Styles
                 0, 0, 50, 50,         // Position and size
                 hwndFrame,            // Owner Window Handle
                 HWND_BOTTOM,          // Z-order position
                 ID_CLIENT,            // Resource Identifier
                 NULL,                 // Control Data
                 NULL);                // Presentation Parameters

This example creates a list box window named "List Box" as a child of the desktop located at (0,0), of size 200x100.

 
#define INCL_WINWINDOWMGR             /* Window Manager Functions  */
#define INCL_WINLISTBOXES             /* List Box definitions      */
#include <os2.h>

HWND  hwnd;                           /* Cursor display window     */
ULONG ListBoxId;                      /* Window id                 */
                                      /* (supplied by application) */
ULONG flStyle;                        /* Window style              */

flStyle = WS_VISIBLE;                 /* Create window visible     */

/* Create button window */
hwnd = WinCreateWindow(HWND_DESKTOP,  /* Parent window             */
                       WC_LISTBOX,    /* Class name                */
                       "List Box",    /* Window text               */
                       flStyle,       /* Window style              */
                       0, 0,          /* Position (x,y)            */
                       200, 100,      /* Size (width,height)       */
                       NULLHANDLE,    /* Owner window              */
                       HWND_TOP,      /* Sibling window            */
                       ListBoxId,     /* Window id                 */
                       NULL,          /* Control data              */
                       NULL);         /* Pres parameters           */

Related Functions

• WinCreateStdWindow
• WinDestroyWindow
• WinEnableWindow
• WinSetWindowPos
• WinShowWindow

Related Messages

• WM_ADJUSTWINDOWPOS
• WM_CREATE
• WM_FORMATFRAME
• WM_SIZE