WinCreateWindow

Creates a new window of class pszClass.

Sytanx

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. In this case, WinGetLastError might return:

PMERR_INVALID_HWND	0x1001
PMERR_INVALID_FLAG	0x1019

Include Info

#define INCL_WINWINDOWMGR
#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

Relevant Structures

Control Data structures include the following:

typedef struct _BOOKPAGEINFO {
  ULONG       cb;                // length of control data in bytes
  ULONG       fl;                // page flags - BFA_
  BOOL        bLoadDlg;          // load dialog now?
  ULONG       ulPageData;        // data to associate with page
  HWND        hwndPage;          // hwnd to associate with page
  PFN         pfnPageDlgProc;    // auto load of dialogs for app
  ULONG       idPageDlg;         // id of page
  HMODULE     hmodPageDlg;       // resource info
  PVOID       pPageDlgParams;    // page creation presentation parameters
  PDLGTEMPLATE  pdlgtPage;
  ULONG       cbStatusLine;      // page flags - BFA_
  PSZ         pszStatusLine;     // status line text string
  HBITMAP     hbmMajorTab;       // major tab bitmap handle
  HBITMAP     hbmMinorTab;       // minor tab bitmap handle
  ULONG       cbMajorTab;        // page flags - BFA_
  PSZ         pszMajorTab;       // major tab text string
  ULONG       cbMinorTab;        // page flags - BFA_
  PSZ         pszMinorTab;       // minor tab text string
  PVOID       pBidiInfo;         // reserved
} BOOKPAGEINFO, *PBOOKPAGEINFO;

typedef structc _BTNCDATA {
  USHORT      cb;                // length of control data in bytes
  USHORT      fsCheckState;      // check state of button
  USHORT      fsHilightState;    // highlight state of button
  LHANDLE     hImage;            // resource handle for icon/bitmap
} BTNCDATA, *PBTNCDATA;

typedef struct _COMBOCDATA {
  ULONG       cb;                // length of control data in bytes
  ULONG       reserved;          // reserved
  PVOID       pHWXCtlData;       // reserved
} COMBOCDATA, *PCOMBOCDATA;

typedef struct _CNRINFO {
  ULONG       cb;                // length of control data in bytes
  PVOID       pSortRecord;       // pointer to sort function
  PFIELDINFO  pFieldInfoLast;    // pointer to last column
  PFIELDINFO  pFieldInfoObject;  // pointer to IN-USE column
  PSZ         pszCnrTitle;       // text for container title
  ULONG       flWindowAttr;      // container attributes: CV_* CA_*
  POINTL      ptlOrigin;         // lower-left origin (virtual)
  ULONG       cDelta;            // number of records from end
  ULONG       cRecords;          // number of records in container
  SIZEL       slBitmapOrIcon;    // size of bitmap in pixels
  SIZEL       slTreeBitmapOrIcon;// size of tree bitmaps in pixels
  HBITMAP     hbmExpanded;       // bitmap for tree node
  HBITMAP     hbmCollapsed;      // bitmap for tree node
  HPOINTER    hptrExpanded;      // icon for tree node
  HPOINTER    hptrCollapsed;     // icon for tree node
  LONG        cyLineSpacing;     // space between two rows
  LONG        cxTreeIndent;      // indent for children
  LONG        cxTreeLine;        // thickness of the Tree Line
  ULONG       cFields;           // number of fields in container
  LONG        xVertSplitbar;     // position relative to container
} CNRINFO, *PCNRINFO;

typedef struct _ENTRYFDATA {
  USHORT      cb;                // length of control data in bytes
  USHORT      cchEditLimit;      // edit limit
  USHORT      ichMinSel;         // minimum selection
  USHORT      ichMaxSel;         // maximum selection
} ENTRYFDATA, *PENTRYFDATA;

typedef struct _FRAMECDATA {
  USHORT      cb;                // length of control data in bytes
  ULONG       flCreateFlags;     // frame creation flags
  USHORT      hmodResource;      // id of required resource
  USHORT      idResource;        // resource identifier
} FRAMECDATA, *PFRAMECDATA;

typedef struct _LBOXINFO {
  LONG        lItemIndex;        // item index
  ULONG       ulItemCount;       // item count
  ULONG       reserved;          // reserved - must be zero
  ULONG       reserved2;         // reserved - must be zero
} LBOXINFO, *PLBOXINFO

typedef struct _MLECTLDATA {
  USHORT      cb;                // length of control data in bytes
  USHORT      afIEFormat;        // import/export format
  ULONG       cchText;           // text limit
  IPT         iptAnchor;         // selection anchor point (start)
  IPT         iptCursor;         // selection cursor point (end)
  LONG        cxFormat;          // formatting rectangle width (pixels)
  LONG        cyFormat;          // formatting rectangle height (pixels)
  ULONG       afFormatFlags;     // format flags
} MLECTLDATA, *PMLECTLDATA;

typedef struct _SBCDATA {
  USHORT      cb;                // length of control data in bytes
  USHORT      sHilight;          // highlight code
  SHORT       posFirst;          // first possible position of scroll bar
  SHORT       posLast;           // last possible position of scroll bar
  SHORT       posThumb;          // scroll thumb current position
  SHORT       cVisible;          // number of lines (items) visible
  SHORT       cTotal;            // total number of lines (items) in MLE
} SBCDATA, *PSBCDATA;

typedef struct _SLDCDATA {
  ULONG       cb;                // length of control data in bytes
  USHORT      usScale1Increments;// number of divisions on scale 1
  USHORT      usScale1Spacing;   // space in pixels between increments
  USHORT      usScale2Increments;// number of divisions on scale 2
  USHORT      usScale2Spacing;   // space in pixels between increments
} SLDCDATA, *PSLDCDATA;

typedef struct _SPBCDATA {
  ULONG       cb;                // length of control data in bytes
  ULONG       ulTextLimit;       // entryfield text limit
  LONG        lLowerLimit;       // spin lower limit (numeric only)
  LONG        lUpperLimit;       // spin upper limit (numeric only)
  ULONG       idMasterSpb;       // id of the servant's master spinbutton
  PVOID       pHWXCtlData;       // reserved
} SPBCDATA, *PSPBCDATA;

typedef struct _VSCDATA {
  ULONG       cbSize;            // length of control data in bytes
  USHORT      usRowCount;        // number of rows in value set
  USHORT      usColumnCount;     // number of columns in value set
} VSCDATA, *PVSCDATA;

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

Related Functions

• WinCreateStdWindow
• WinDestroyWindow
• WinEnableWindow
• WinSetWindowPos
• WinShowWindow