This function allows an application to present an image in the background of the desktop window. This application must be acting as the OS/2 PM shell in place of the IBM supplied shell. If the IBM supplied shell is executing it maintains control of the background of the desktop window, and WinSetDesktopBkgnd will have no effect on the desktop window background, but will indicate a successful return code. The background of the desktop window is that portion of the desktop on which no other windows have been painted.

The system assumes ownership of the bit map which forms the desktop background. This implies that once the bit map is set to form the desktop background, it is no longer available to an application and therefore must not be associated with any application presentation space or any symbol set LCID. The system repaints the desktop background automatically to show any changes.

The most recent invocation of this function sets the state of the desktop background. Consequently, any application which sets the desktop background must be aware that changing the desktop background every time the application is activated, which implies the repainting of the whole desktop, could be distracting, if not disorienting, to the user. Therefore, such an application should determine if the correct desktop background is already showing by processing the WM_ACTIVATE message and if its determining the desktop background state by using the WinQueryDesktopBkgnd function and checking the bit-map handle of the current desktop background with the desired bit-map handle.

When setting a new desktop background, it is important to ensure that any previous desktop background bit map is destroyed, in order to prevent the system becoming cluttered with unused bit maps.