background-color

Arguments: standard-object &optional result-rgb

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. Inthat 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.

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.

The optional result-rgb argument is no longer used, and is retained only for compatibility with older Common Graphics application code. This argument was used through version 6.1 to avoid consing the returned RGB instance; now the RGB instance that was specified for the object is instead retained and returned without ever consing a copy.

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

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had significant revisions compared to the 6.1 page.
Created 2002.2.26.