Property functions create and access a window's property list. A property list is a storage area that contains handles for data that the application wishes to associate with a window. The following list briefly describes each property function:
| Function | Description | |
| EnumProps | Passes the properties of a window to an enumeration function. | |
| GetProp | Retrieves a handle associated with a string from the window property list. | |
| RemoveProp | Removes a string from the property list. | |
| SetProp | Copies a string and a data handle to a window's property list. |
Using Property Lists
Once a data handle is in a window's property list, any application can access the handle if it can also access the window. This makes the property list a convenient way to make data (for example, alternate captions or menus for the window) available to the application when it wishes to modify the window.
Every window has its own property list. When the window is created, the list is empty. The SetProp function adds entries to the list. Each entry contains a unique ANSI string and a data handle. The ANSI string identifies the handle; the handle identifies the data associated with the window, as illustrated in Figure 1.2:
The data handle can identify any object or memory block that the application wishes to associate with the window. The GetProp function retrieves the data handle of an entry from the list without removing the entry. The handle can then be used to retrieve or use the data. The RemoveProp function removes an entry from the list when it is no longer needed.
Although the purpose of the property list is to associate data with a window for use by the application that owns the window, the handles in a property list are actually accessible to any application that has access to the window. This means an application can retrieve and use a data handle from the property list of a window created by another application. But using another application's data handles must be done with care. Only shared, global memory objects, such as GDI drawing objects, can be used by other applications. If a property list contains local or global memory handles or resource handles, only the application that has created the window may use them. Global memory handles can be shared with other applications by using the Windows clipboard. (For more information, see Section 1.12, “Clipboard Functions.”) Local memory handles cannot be shared.
The contents of a property list can be enumerated by using the EnumProps function. The function passes the string and data handle of each entry in the list to an application-supplied function. The application-supplied function can carry out any task.
The data handles in a property list always belong to the application that created them. The property list itself, like other window-related data, belongs to Windows. A window's property list is actually allocated in the USER heap, the local heap of the USER library. Although there is no defined limit to the number of entries in a property list, the actual number of entries depends on how much room is available in the USER heap. This depends on how many windows, window classes, and other window-related objects have been created.
The application creates the entries in a property list. Before a window is destroyed or the application that owns the window terminates, all entries in the property list must be removed by using the RemoveProp function. Failure to remove the entries leaves the property list in the USER heap and makes the space it occupies unusable for subsequent applications. This can ultimately cause an overflow of the USER heap. Entries in the property list can be removed at any time by using the RemoveProp function. If there are entries in the property list when the WM_DESTROY message is received for the window, the entries must be removed at that time. To ensure that all entries are removed, use the EnumProps function to enumerate all entries in the property list. An application should remove only those properties that it added to the property list. Windows adds properties for its own use and disposes of them automatically. An application must not remove properties which Windows has added to the list.