Once a data handle is in a window's property list, any application that can access the window can also access the handle. Using the property list is a convenient way to make data (for example, an alternate title or menu for a window) available when the application needs to modify a window.
Every window has its own property list. When a window is created, the list is empty. The SetProp function adds entries to the list. Each entry contains a unique
Windows character string and a data handle. The Windows character string identifies the handle; the handle identifies the data associated with the window, as shown in the following illustration.
The data handle can identify any object that the application needs 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 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 can use them. An application can use the Windows clipboard to share global memory handles with other applications. (For more information about the clipboard, see the Microsoft Windows Guide to Programming.) 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 then carry out the necessary 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 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 number of entries depends on how much space is available in the USER heap. The available space 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 closes, 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.
An application can use the RemoveProp function at any time to remove entries from the property list. 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 that Windows has added to the list.