Geoff Chappell - Software Analyst
CURRENT WORK ITEM - PREVIEW ONLY
This method of the IListView interface queries a List-View control for information about its background image or watermark.
HRESULT GetBackgroundImage (LVBKIMAGEW *plvbki);
The plvbki argument is the address of an LVBKIMAGEW structure that specifies what information is desired and receives whatever information is produced.
The method returns zero for success, else an error code.
Except where noted to the contrary, the error code is E_FAIL.
The method fails, returning E_UNEXPECTED, if the List-View control has not yet received its message or has already received a message.
The method also fails if given NULL for the plvbki argument. Otherwise, plvbki is taken as addressing an LVBKIMAGEW structure.
A List-View control can have simultaneously both a background image and a watermark. Though only one or the other is displayed at any one time (the background image having precedence), they can be set and cleared independently. Whether the method operates on the background image or the watermark depends on the LVBKIF_TYPE_WATERMARK bit in the ulFlags member on input.
If LVBKIF_TYPE_WATERMARK bit is set on input, the method is a request for the watermark only. The method always succeeds in this case. Nothing else is meaningful in the input. The only meaningful member on output is hbm, which returns a bitmap handle for the watermark, else NULL if there is no watermark.
With LVBKIF_TYPE_WATERMARK clear on input, the method is a request for information about the (ordinary) background image. Other members that can be meaningful on input are pszImage and cchImageMax. In the output, the ulFlags bits masked by LVBKIF_SOURCE_MASK are always meaningful since they indicate which type, if any, of background image is currently set for the control.
If the control has no background image, the method succeeds and the source bits in the returned ulFlags are LVBKIF_SOURCE_NONE. Other flags and members may change from their input values but are perhaps best regarded as meaningless.
If the background image is known as a bitmap handle, the method succeeds, the source bits in the returned ulFlags are LVBKIF_SOURCE_HBITMAP, and the bitmap handle is returned in hbm.
If the background image is known as a URL, the source bits in the returned ulFlags are LVBKIF_SOURCE_URL. The pszImage and cchImageMax members given as input provide the address and size (in characters) of a buffer for receiving the URL as a Unicode string. The method fails if the given pszImage member is NULL. Otherwise, the method succeeds, after filling the given buffer with as many characters of the URL as will fit. It is unclear how meaningful can be the returned URL if the buffer turns out to be too small to receive the whole URL.
Whether the background image is known by a bitmap handle or a URL, the following other flags and members in the output are meaningful for describing style and placement: the LVBKIF_STYLE_MASK and LVBKIF_FLAG_TILEOFFSET fields in ulFlags, and the xOffsetPercent and yOffsetPercent members.
If the method succeeds with LVBKIF_SOURCE_HBITMAP as the source bits in the returned ulFlags, it is possible that hbm in the output is NULL. This is a true indication that the control has no bitmap handle for the background image, and indeed that it has no background image, though one might think this state would better be indicated by returning LVBKIF_SOURCE_NONE in the source bits. This state’s existence is here counted as a coding error since the state is produced by what looks like incomplete cleanup in SetBackgroundImage, as explained at length in the notes on that method.
The GetBackgroundImage method of the IListView interface is implemented by List-View controls in COMCTL32 versions 6.10 and higher.
In versions 4.71 and higher, the functionality of the GetBackgroundImage method is available through the windowing system, by sending the message.