WinRegisterClass
Syntax
WinRegisterClass( hab, pszClassName, pfnWndProc, flStyle, cbWndData );
Usage Explanation
This API is normally used by the main window of all applications. Its main purpose is to register the address of the window procedure for this class. After this has been done, WinCreateWindow or WinCreateStdWindow can be used to create windows of this class, usually the main window of the app.
The private class name must not clash with the name of a public class in the same process. If this should happen, FALSE will be returned, and PMERR_PARAMETER_OUT_OF_RANGE will be returned from WinGetLastError. A private class can override an older private class, though, in which case the current parameters replace the old ones.
Private classes disappear when the owning process terminates, ie. when they are no longer needed.
Parameters
- hab (HAB) - input
- Anchor block handle.
- pszClassName (PSZ) - input
- The name of the class to register. This is usually specific to your application.
- pfnWndProc (PFNWP) - input
- The window procedure of the application.
- flStyle (ULONG) - input
- Default window style. This is the default style of any windows created of this class. This can be modified in the usual manner. If CS_PUBLIC is specified, any process can use this public class. Otherwise, a private class is created, available only to this process. You must only specify CS_PUBLIC for the shell process. This value is frequently 0L.
| CS_CLIPCHILDREN | Clip window drawing to children's boundaries |
| CS_CLIPSIBLINGS | Clip window drawing to siblings' boundaries |
| CS_FRAME | Frame window |
| CS_HITTEST | When pointer is in window, WM_HITTEST is sent |
| CS_MOVENOTIFY | WM_MOVE messages will be sent to window |
| CS_PARENTCLIP | Clip window drawing to parent's boundaries |
| CS_PUBLIC | Makes the new class public (see above) |
| CS_SAVEBITS | Save area covered by window for faster redraws |
| CS_SIZEREDRAW | Invalidates whole window when it is resized |
| CS_SYNCPAINT | Window is repainted synchronously (WM_PAINT is SENT) |
| ... | Other Control Styles |
- cbWindowData (ULONG) - input
- The number of bytes reserved for storage for each window of this class which is created. If none is needed, specify 0L.
Returns
- rc (BOOL) - returns
- TRUE means class was registered. FALSE means it was not. If FALSE is returned, you may use WinGetLastError() to find out what went wrong. Possible errors are:
| 0x1003 | PMERR_PARAMETER_OUT_OF_RANGE | A parameter was out of range (?). |
| 0x1013 | PMERR_INVALID_HATOMTBL | An invalid atom table handle was passed. |
| 0x1015 | PMERR_INVALID_ATOM_NAME | An invalid atom name string was given. |
| 0x1016 | PMERR_INVALID_INTEGER_ATOM | The atom specified is not a valid integer atom. |
| 0x1017 | PMERR_ATOM_NAME_NOT_FOUND | The atom name given was not in the atom table. |
| 0x1019 | PMERR_INVALID_FLAG | An invalid bit was set for a parameter. |
| 0x1208 | PMERR_INVALID_PARAMETERS | One or more parameters were invalid. |
Errors
Possible returns from WinGetLastError
- 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_INVALID_INTEGER_ATOM (0x1016)
- The specified atom is not a valid integer atom.
- PMERR_INVALID_HATOMTBL (0x1013)
- An invalid atom-table handle was specified.
- PMERR_INVALID_ATOM_NAME (0x1015)
- An invalid atom name string was passed.
- PMERR_ATOM_NAME_NOT_FOUND (0x1017)
- The specified atom name is not in the atom table.
Include Info
#define INCL_WINWINDOWMGR #include <os2.h>
Gotchas
Only DLLs run by the shell at startup can use the CS_PUBLIC style.
When an application registers a private class with the window procedure in a dynamic link library, it is the application's responsibility to resolve the window-procedure address before issuing this function.
A private class must not be registered with the same name as a public class in the same process.
However, if a private class is registered with the same name as one that already exists, the parameters replace the old class parameters, and the return value is TRUE. The window procedure of an existing window can be changed using WinSubclassWindow or WinSetWindowPtr. The style of an existing window can be changed with the WinSetWindowULong or WinSetWindowUShort functions. The number of bytes of storage allocated for application use cannot be changed once the window is created.
Private classes are deleted when the process that registers them terminates.
Sample Code
Definition:
#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, Also in COMMON section */
#include <os2.h>
HAB hab; /* Anchor-block handle. */
PSZ pszClassName; /* Window-class name. */
PFNWP pfnWndProc; /* Window-procedure identifier. */
ULONG flStyle; /* Default-window style. */
ULONG cbWindowData; /* Reserved storage. */
BOOL rc; /* Window-class-registration indicator. */
rc = WinRegisterClass(hab, pszClassName, pfnWndProc,
flStyle, cbWindowData);
Sample:
#define INCL_WINWINDOWMGR
#include <os2.h>
MRESULT EXPENTRY WndProc (HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2);
HAB hab;
HMQ hmq;
CHAR szClassName[] = "My_class";
hab=WinInitialize(0L);
hmq=WinCreateMsgQueue(hab, 0L);
if (hmq) {
retval = WinRegisterClass(hab,
szClassName,
(PFNWP) WndProc,
0L,
0L);
.
.
.
}
This example calls WinRegisterClass to register a class or returns FALSE if an error occurs.
#define INCL_WINWINDOWMGR
#include <OS2.H>
HAB hab;
CHAR szClassName[] = "Generic"; /* window class name */
PFNWP pGenericWndProc;
if (!WinRegisterClass(hab, /* anchor-block handle */
szClassName, /* class name */
pGenericWndProc, /* window procedure */
0L, /* window style */
0)) /* amount of reserved memory */
return (FALSE);