GetBackgroundColor

This method of the IListView interface gets the background colour of a List-View control.

Declaration

HRESULT GetBackgroundColor (COLORREF *pclrBk);

Parameters

The pclrBk argument is the address of a variable that is to receive either: the background colour; or the value CLR_NONE (0xFFFFFFFF) if there is no background colour.

Return Value

The method returns zero for success, else an error code.

Behaviour

The method fails, returning E_UNEXPECTED, if the List-View control has not yet received its WM_CREATE message or has already received a WM_DESTROY message.

In the preceding case, the background colour returned at the address given by pclrBk is zero (black).

In all other cases, the method succeeds. The background colour that the method returns (indirectly, at the address given by pclrBk) is the current background colour, if the control is enabled.

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, it returns the colour that is waiting to become the current background colour should the control ever be re-enabled.

Availability

The GetBackgroundColor method of the IListView interface is implemented by List-View controls in COMCTL32 versions 6.10 and higher.

In all COMCTL32 versions from at least 3.50, the functionality of the GetBackgroundColor method is available through the windowing system, by sending the LVM_GETBKCOLOR message.