Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function SetSysColors Lib "user32.dll" (ByVal cElements As Long, lpaElements As Long, lpaRgbValues As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

SetSysColors changes the system colors used by Windows. Windows uses these colors when displaying the typical widgets such as title bars, scroll bars, the desktop, menus, etc. This function can set multiple different system colors simultaneously, by passing all the new RGB color values in an array. SetSysColors also notifies all windows of the change, so the color change takes effect immediately. However, the new colors are not saved after Windows shuts down.

Return Value

If successful, the function returns a nonzero value. If an error occured, the function returns zero (use GetLastError to get the error code).

Visual Basic-Specific Issues

None.

Parameters

cElements

The number of elements in the arrays passed as lpaElements and lpaRgbValues.

lpaElements

An array holding the identifiers of all the system colors to change. Each element can be one of the following flags, specifying a system color:

COLOR_3DDKSHADOW: The dark shadow color for 3D objects.
COLOR_3DFACE, COLOR_BTNFACE: The face color for 3D objects.
COLOR_3DHILIGHT, COLOR_3DHIGHLIGHT, COLOR_BTNHILIGHT, COLOR_BTNHIGHLIGHT: The highlight (opposite of shadow) color for 3D objects.
COLOR_3DLIGHT: The light (opposite of shadow) color for 3D objects.
COLOR_3DSHADOW, COLOR_BTNSHADOW: The shadow color for 3D objects.
COLOR_ACTIVEBORDER: The active window border color.
COLOR_ACTIVECAPTION: The active window title bar color. Windows 98, 2000: The color of the left side of the active window title bar gradient, if the gradient effect is used.
COLOR_APPWORKSPACE: The background color of multiple document interface (MDI) windows.
COLOR_BACKGROUND, COLOR_DESKTOP: The desktop color.
COLOR_BTNTEXT: The text color for pushbuttons.
COLOR_CAPTIONTEXT: The color of window caption text, size boxes, and scroll bar arrow boxes.
COLOR_GRADIENTACTIVECAPTION: Windows 98, 2000: The color of the right side of the active window title bar gradient, if the gradient effect is used.
COLOR_GRADIENTINACTIVECAPTION: Windows 98, 2000: The color of the right side of an inactive window's title bar gradient, if the gradient effect is used.
COLOR_GRAYTEXT: The color for disabled (grayed-out) text.
COLOR_HIGHLIGHT: The color used to highlight selected items.
COLOR_HIGHLIGHTTEXT: The color used for the text of highlighted items.
COLOR_HOTLIGHT: Windows 98, 2000: The color of a hot-tracked item, which is executed with a single click.
COLOR_INACTIVEBORDER: The color of an inactive window's border.
COLOR_INACTIVECAPTION: The color of an inactive window's caption. Windows 98, 2000: The color of the right side of an inactive window's title bar gradient, if the gradient effect is used.
COLOR_INACTIVECAPTIONTEXT: The color of an inactive window's caption text.
COLOR_INFOBK: The background color for tooltop controls.
COLOR_INFOTEXT: The text color for tooltip controls.
COLOR_MENU: The background color of menus.
COLOR_MENUTEXT: The color of menu text.
COLOR_SCROLLBAR: The color of a scroll bar's gray area.
COLOR_WINDOW: The background color of a window.
COLOR_WINDOWFRAME: The color of a window frame.
COLOR_WINDOWTEXT: The color of text in a window.

lpaRgbValues

An array of the RGB values of the new system colors to assign. These elements correspond directly to the elements in lpaElements. For example, the first element of this array is the color to use for the system color identified by the first element of lpaElements, etc.

Constant Definitions

Const COLOR_3DDKSHADOW = 21 Const COLOR_3DFACE = COLOR_BTNFACE Const COLOR_3DHIGHLIGHT = COLOR_BTNHIGHLIGHT Const COLOR_3DHILIGHT = COLOR_BTNHIGHLIGHT Const COLOR_3DLIGHT = 22 Const COLOR_3DSHADOW = COLOR_BTNSHADOW Const COLOR_ACTIVEBORDER = 10 Const COLOR_ACTIVECAPTION = 2 Const COLOR_APPWORKSPACE = 12 Const COLOR_BACKGROUND = 1 Const COLOR_BTNFACE = 15 Const COLOR_BTNHIGHLIGHT = 20 Const COLOR_BTNHILIGHT = COLOR_BTNHIGHLIGHT Const COLOR_BTNSHADOW = 16 Const COLOR_BTNTEXT = 18 Const COLOR_CAPTIONTEXT = 9 Const COLOR_DESKTOP = COLOR_BACKGROUND Const COLOR_GRADIENTACTIVECAPTION = 27 Const COLOR_GRADIENTINACTIVECAPTION = 28 Const COLOR_GRAYTEXT = 17 Const COLOR_HIGHLIGHT = 13 Const COLOR_HIGHLIGHTTEXT = 14 Const COLOR_HOTLIGHT = 26 Const COLOR_INACTIVEBORDER = 11 Const COLOR_INACTIVECAPTION = 3 Const COLOR_INACTIVECAPTIONTEXT = 19 Const COLOR_INFOBK = 24 Const COLOR_INFOTEXT = 23 Const COLOR_MENU = 4 Const COLOR_MENUTEXT = 7 Const COLOR_SCROLLBAR = 0 Const COLOR_WINDOW = 5 Const COLOR_WINDOWFRAME = 6 Const COLOR_WINDOWTEXT = 8

Example

Reverse the gradient colors in windows' title bars. In other words, the left-side gradient color is swapped with the right-side gradient color, for both active and inactive windows. After making the change, a notification is sent to all windows, to insure that the change takes effect immediately. Of course, this example won't work properly on Windows 95 or Windows NT 3.1 through 4.0, but you can still see how these two functions are used by looking at the source code.

This example runs when the user clicks command button Command1. So, to use this example, you must first place a command button named Command1 on a form window.

' This code is licensed according to the terms and conditions listed here. ' Declarations and such needed for the example: ' (Copy them to the (declarations) section of a module.) Public Declare Function GetSysColor Lib "user32.dll" (ByVal nIndex As Long) As Long Public Declare Function SetSysColors Lib "user32.dll" (ByVal cElements As Long, lpaElements As Long, _ lpaRgbValues As Long) As Long Public Const COLOR_ACTIVECAPTION = 2 Public Const COLOR_GRADIENTACTIVECAPTION = 27 Public Const COLOR_GRADIENTINACTIVECAPTION = 28 Public Const COLOR_INACTIVECAPTION = 3 ' *** Place the following code inside a form window. *** Private Sub Command1_Click() Dim activeLeftColor As Long ' color of left-side gradient of active window title bar Dim activeRightColor As Long ' color of right-side gradient of active window title bar Dim inactiveLeftColor As Long ' color of the left-side gradient of inactive window title bar Dim inactiveRightColor As Long ' color of the right-side gradient of inactive window title bar Dim colorNames(0 To 3) As Long ' identifiers of the system colors to change Dim colorRGBs(0 To 3) As Long ' RGB values of the system colors to change Dim retval As Long ' generic return value ' Get the RGB values of the colors used in title bars. activeLeftColor = GetSysColor(COLOR_ACTIVECAPTION) activeRightColor = GetSysColor(COLOR_GRADIENTACTIVECAPTION) inactiveLeftColor = GetSysColor(COLOR_INACTIVECAPTION) inactiveRightColor = GetSysColor(COLOR_GRADIENTINACTIVECAPTION) ' Load the arrays with the new values to assign. Note how we're switching ' the values used on the left and right sides of the two gradients. colorNames(0) = COLOR_ACTIVECAPTION colorRGBs(0) = activeRightColor colorNames(1) = COLOR_GRADIENTACTIVECAPTION colorRGBs(1) = activeLeftColor colorNames(2) = COLOR_INACTIVECAPTION colorRGBs(2) = inactiveRightColor colorNames(3) = COLOR_GRADIENTINACTIVECAPTION colorRGBs(3) = inactiveLeftColor ' Change the system color settings as specified above. retval = SetSysColors(4, colorNames(0), colorRGBs(0)) End Sub