Geoff Chappell - Software Analyst
This method of the IListView interface sets the background colour of a List-View control.
HRESULT SetBackgroundColor (COLORREF clrBk);
The clrBk argument provides either: the background colour; or the value CLR_NONE (0xFFFFFFFF) if there is no background colour.
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.
If the List-View control is presently enabled, the request is acted on immediately, so that the given background colour becomes the current background colour. The given colour is CLR_NONE (0xFFFFFFFF) to clear the background colour, and is anything else to set a background colour.
By current background colour it is here meant the colour that the control is configured to use for its background when the background is next redrawn, whenever that turns out to be. Until then, the background as shown to the user may have an entirely different colour. This method does nothing to arrange that the background be repainted.
Whenever a List-View control is disabled, its current background colour is forced to COLOR_BTNFACE. If this method is called while the control is disabled, the requested setting or clearing of the background colour is deferred until the control is ever re-enabled, and the method returns success.
Setting a background colour clears the LVS_EX_TRANSPARENTBKGND extended style. If the new background colour already is the background colour, then the method succeeds. Otherwise, a solid brush is to be created for the new colour. Any solid brush for the old background colour is destroyed. Failure to create the new solid brush is failure for the method. Unless the control has the LVS_SHAREIMAGELISTS style, the new background colour is also set for each of the image lists for normal icons, small icons and state images. Finally, the new background colour is also set for the column headers.
If the List-View already has no background colour, then the method succeeds. Otherwise, any solid brush for the old background colour is destroyed. Unless the control has the LVS_SHAREIMAGELISTS style, the background colour is also cleared from each of the image lists for normal icons, small icons and state images. Finally, the background colour is also cleared from the column headers.
These processes of setting and clearing the background colour can occur by implication. The following discussion simplifies very slightly by assuming that setting a background colour never fails.
The initial background colour for all List-View controls, as set when the control is created, is COLOR_WINDOW.
Whenever a List-View control is disabled, its background colour is set to COLOR_BTNFACE. When a List-View control is created with the WS_DISABLED style, its background colour gets set twice: first to COLOR_WINDOW as the default; then to COLOR_BTNFACE by disabling the control. Whenever a List-View control is re-enabled, its background colour gets set again, either to update it (acting on the deferral noted above) else to restore it to whatever it was when the control was disabled.
While a List-View control uses a system colour for its background, receipt of a message causes the background colour to be set to whatever the applicable system colour now resolves to. A List-View control never stops regarding COLOR_BTNFACE as the applicable colour while the control is disabled, but it stops tracking COLOR_WINDOW once this method is called or once the background colour is cleared through the implicit mechanism described next.
Setting the LVS_EX_TRANSPARENTBKGND extended style, e.g., through the SetExtendedStyle method or message, clears the background colour.
Microsoft perhaps thinks such interactions are all so obvious that they needn’t even be hinted at in the documentation. Yet there are practical consequences, both as warning and opportunity. If you set the transparent-background style and then allow the control to be disabled, you lose the style until you set it again, even if the control is eventually re-enabled. If you disable the control and then set the transparent-background style, you are able to give the disabled control an otherwise novel background (assuming that you manage the parent window), and when you re-enable the control, you get its background colour back.
The SetBackgroundColor method of the IListView interface is implemented by List-View controls in COMCTL32 versions 6.10 and higher.
In all versions from at least 3.50, the functionality of the SetBackgroundColor method is available through the windowing system, by sending the message.