WinSetDesktopBkgnd
Syntax
WinSetDesktopBkgnd (hwndDeskTop, DeskTopState)
Parameters
- hwndDeskTop (HWND) - input
- Desktop-window handle.
- pDeskTopState (PDESKTOP) - input
- Desktop-state structure.
- If the flag is set, then the background is unaffected although the bit-map file may still be loaded and tiled, or scaled as requested.
Returns
- hbm (HBITMAP) - returns
- Desktop background bit-map handle loaded or set.
- NULLHANDLE
- Error occurred.
- Other
- Bit-map handle loaded, set, or both for desktop background. The bit-map handle returned may be different from that passed into call if any scaling or tiling is performed.
Remarks
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.
Errors
Possible returns from WinGetLastError
- PMERR_INVALID_HPTR (0x101B)
- An invalid pointer handle was specified.
- PMERR_INVALID_HWND (0x1001)
- An invalid window handle was specified.
Example Code
Declaration:
#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */ #include <os2.h> HWND hwndDeskTop; /* Desktop-window handle. */ PDESKTOP pDeskTopState; /* Desktop-state structure. */ HBITMAP hbm; /* Desktop background bit-map handle loaded or set. */ hbm = WinSetDesktopBkgnd(hwndDeskTop, pDeskTopState);
This example uses WinQueryDesktopBkgnd to query the current desktop background bit map before setting it to a new bit map with WinSetDesktopBkgnd.
#define INCL_WINDESKTOP
#define INCL_WINWINDOWMGR
#include <os2.h>
HAB hab;
HWND hwndDeskTop;
DESKTOP DeskTopState;
HBITMAP hbm;
HBITMAP hbm_user;
WinQueryDesktopBkgnd(HWND_DESKTOP,
&DeskTopState);
if (hbm_user != DeskTopState.hbm)
{
DeskTopState.fl = SDT_LOADFILE;
/* the szFile is used to load the bit map because */
/* the fl parameter is set to SDT_LOADFILE. */
strcpy(DeskTopState.szFile,"fruit.bmp");
DeskTopState.hbm = hbm_user;
WinSetDesktopBkgnd(hwndDeskTop,
&DeskTopState);
}