WinCreateWindow
WinCreateWindow
- WinCreateWindow( hwndParent, pszClass, pszText, flStyle, x, y, cx, cy, hwndOwner, hwndBehind, id, pCtrlData, pPresParams );
- Creates a new window of class pszClass.
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.html WinRegisterClass], or be a pre-defined PM class. This could be one of the following: {| border="1"
! 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: {| border="1"
| 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: {| border="1"
| 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;
Gotchas
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
PMI:WinCreateStdWindow, PMI:WinDestroyWindow, PMI:WinEnableWindow, PMI:WinSetWindowPos, PMI:WinShowWindow