ID Number: Q34611
2.03 2.10 3.00 3.10
WINDOWS
Summary:
The WNDCLASS structure contains two fields, cbClsExtra and cbWndExtra,
which can be used to specify a number of additional bytes of memory to
be allocated to the class structure itself or to each window created
using that class.
Every application that uses class extra bytes and window extra bytes
must specify the appropriate number of bytes before the window class
is registered. If no bytes are specified, an attempt to store
information in extra bytes will cause the application to write into
some random portion of Windows memory, causing data corruption.
Windows version 3.1 will FatalExit if extra bytes are used improperly.
If an application does not use class extra bytes or window extra
bytes, it is important that the cbClsExtra and cbWndExtra fields be
set to zero.
Class and window extra bytes are a scarce resource. If more than 4
extra bytes are required, use the GlobalAlloc fucntion to allocate a
block of memory and store the handle in class or window extra bytes.
Class Extra Bytes
-----------------
For example, setting the value of the cbClsExtra field to 4 will cause
4 extra bytes to be added to the end of the class structure when the
class is registered. This memory is accessible by all windows of that
class. The number of additional bytes allocated to a window's class
can be retrieved through the following call to the GetClassWord
function:
nClassExtraBytes = GetClassWord(hWnd, GCW_CBCLSEXTRA);
The additional memory can be accessed one word at a time by specifying
an offset, in BYTES (starting at 0), as the nIndex parameter in calls
to the GetClassWord function. These values can be set using the
SetClassWord function.
The GetClassLong and SetClassLong functions perform in a similar
manner and get or set four bytes of memory respectively.
It is important to note that while the functions get or set a word of
information, the offset is a number of bytes.
Window Extra Bytes
------------------
Assigning a value to cbWndExtra will cause additional memory to be
allocated for each window of the class. If, for example, cbWndExtra is
set to 4, every window created using that class will have 4 extra
bytes allocated for it. This memory is accessible only by using the
GetWindowWord and GetWindowLong functions, and specifying a handle
to the window. These values can be set by calling the SetClassWord
or SetClassLong functions. As with the class structures, the offset
is always specified in bytes.
An example of using window extra bytes would be a text editor that has
a variable number of files open at once. The file handle and other
file-specific variables can be stored in the window extra bytes of the
corresponding text window. This eliminates the requirement to always
consume memory for the maximum number of handles or to search a data
structure each time a window is opened or closed.
Additional reference words: 2.10 3.00 3.10 3.x