GetSysColorBrush function (winuser.h)

Article
02/22/2024

The GetSysColorBrush function retrieves a handle identifying a logical brush that corresponds to the specified color index.

Syntax

HBRUSH GetSysColorBrush(
  [in] int nIndex
);

Parameters

[in] nIndex

A color index. This value corresponds to the color used to paint one of the window elements. See GetSysColor for system color index values.

Return value

The return value identifies a logical brush if the nIndex parameter is supported by the current platform. Otherwise, it returns NULL.

Remarks

A brush is a bitmap that the system uses to paint the interiors of filled shapes. An application can retrieve the current system colors by calling the GetSysColor function. An application can set the current system colors by calling the SetSysColors function.

An application must not register a window class for a window using a system brush. To register a window class with a system color, see the documentation of the hbrBackground member of the WNDCLASS or WNDCLASSEX structures.

System color brushes track changes in system colors. In other words, when the user changes a system color, the associated system color brush automatically changes to the new color.

To paint with a system color brush, an application should use GetSysColorBrush (nIndex) instead of CreateSolidBrush ( GetSysColor (nIndex)), because GetSysColorBrush returns a cached brush instead of allocating a new one.

System color brushes are owned by the system so you don't need to destroy them. Although you don't need to delete the logical brush that GetSysColorBrush returns, no harm occurs by calling DeleteObject.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll
API set	ext-ms-win-ntuser-gui-l1-1-1 (introduced in Windows 8.1)