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);

Related Functions

• WinInitialize
• WinCreateMsgQueue
• WinCreateStdWindow
• WinCreateWindow