background-color

Arguments: standard-object

Returns the background color for standard-object if one has been specified for it, and otherwise returns nil. (By contrast, effective-background-color will always return a color, by calling default-background-color when background-color returns nil.)

The background-color is the color that is used to erase the object's drawing area (such as by clear-page) before its graphical content is drawn in the object's foreground-color. It is also used for drawing by functions such as erase-line and erase-contents-box. foreground-color and background-color apply to windows, dialog-items, button-infos (of a multi-picture-button), and outline-items (of an outline).

A background color may be specified either by calling (setf background-color) or by passing the background-color initarg to make-instance or make-window when creating the object. The value may be either an RGB instance (see make-rgb), nil, or t. nil means to use the default-background-color for the object. t means to use the background color of the parent of the object, if there is a parent, and otherwise use the default-background-color of the object.

The value cannot be an HLS color, as returned by make-hls. If you use HLS colors, apply hls-to-rgb to them before setting this property, and call rgb-to-hls to get the HLS equivalent of an RGB value.

It is typical to leave the background-color of an object nil. In that case, the color returned by default-background-color will be used. If the default methods for that generic function have not been overridden, default-background-color will return a system color such as the one returned by system-background-color or system-dialog-background-color (depending on whether the object is or is not an instance of dialog-mixin). This causes your application to use the end user's preferred colors that they have selected in the Windows Control Panel.

Some widgets that are supplied by the underlying window system will not allow you to change their background color. This is usually true when there is normally no need to use a non-default color. An exception, however, is that on GTK you cannot change the background color of a text-editing widget, such as to make a "scrolling static-text" widget by setting the border property to :none and making the background-color match the parent window.

The actual RGB instance that is passed to (setf background-color) is retained to be returned later by background-color, so an application should not modify an RGB instance while it is assigned to an object. A single RGB instance may be assigned to any number of objects, however.

In earlier releases, this generic function had an optional argument, result-rgb, which was already deprecated and unused. Starting in release 7.0, that argument is no longer supported. Code which includes that argument will signal an error. The error can be fixed by removing any reference to a second, optional argument.

See also with-background-color, a convenient macro that temporarily changes the background color while a body of code is executed.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.