Allocating and Using Class and Window Extra Bytes

Last reviewed: November 2, 1995
Article ID: Q34611
The information in this article applies to:
  • Microsoft Windows Software Development Kit (SDK) versions 3.0 and 3.1
  • Microsoft Win32 Application Programming Interface (API) included with:

        - Microsoft Windows NT versions 3.5 and 3.51
        - Microsoft Windows 95 version 4.0
    

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.

MORE INFORMATION

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:

   nClassExtraBytes = GetClassLong(hWnd, GCL_CBCLSEXTRA);

NOTE: A Win32-based application should use GetClassLong and SetClassLong, because the GCW_ indices are obsolete under Win32.

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: 3.00 3.10 3.50 4.00 95
KBCategory: kbui
KBSubcategory: UsrWndw


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: November 2, 1995
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.