lamp

Class

Package: cg

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 8.0
This page is new in 8.0.

lamp

The class of the lamp control. The widget-window of the control is a member of the lamp-pane class.

The lamp control is a colored shape (a circle, rectangle, triangle, or diamond) which can be on or off, or can blink between on and off. The on and off colors may be any colors, and may be changed at any time. A single lamp widget can optionally display an entire rectangular array of lamp images, which may individually be on or off or blinking.

The value property of the widget may be t (meaning the lamp is on), nil (meaning it is off), or :blinking (meaning it switches between on and off, with the interval determined by blink-off-milliseconds and blink-on-milliseconds). The lamp displays its on-color when it is on, and its off-color when it is off.

The off-color property value is nil by default, in which case the effective off-color is derived automatically from the on-color and the off-color-factor. The off-color-factor is a number between zero and one by which to multiply the on-color RGB values to produce a dimmer version of the same hue for the off state.

The lamp-shape property may be either :circle, :triangle, :rectangle, or :diamond to draw the lamp in a particular shape. The border around the lamp is controlled with the border-color and border-width properties (where a border-width of zero would draw no border).

The title property may be either a string to display on one side of the lamp, or else nil to display no string. The title-side property may be :left, :top, :right, or :bottom to position the title on a particular side of the lamp image, or :center to position the title within the (typically rectangular) lamp image. As with other widgets, the font property determines the font with which to draw the title string.

The size of the lamp image within the widget may be specified explicitly by setting the lamp-width and lamp-height properties to the desired pixel size. By default these properties are nil instead, which means to fit the lamp image to the current size of the widget. When fitting to the widget, the size of the lamp image is affected by the outer-horizontal-margin, inner-horizontal-margin, outer-vertical-margin, and inner-vertical-margin properties. The "outer" margins are between the image and the edge of the widget, while the "inner" margins are between the lamp image and the title, or between the multiple lamp images when the value property is an array (see below). The outer margins are particularly useful when laying out lamps on a form, allowing you to snap the widgets up against each other without the lamp images or title strings running into each other.

Making an array of lamps

To make a lamp widget display a rectangular grid of lamp images, set the value property to be a two-dimensional array, where the major dimension of the array indicates the row, and the minor dimension the column. Each value in the array should be either nil, t, or :blinking to specify the state of each lamp in the grid. The title of the widget is never displayed when the value is an array. The colors and lamp shape will be the same for all lamps in the grid, and any blinking lamps will blink in unison.

Replacing any lamp property will automatically update the appearance of the widget, as usual, either on a form or at runtime. But when the value is an array, it is simpler and more efficient to modify the existing array object, rather than consing up a new array for each change. Since the value property remains the same object in this case, the widget will not update itself automatically. To cause the widget to update its appearance after modifying the array object, you can setf the value of the widget to be the same array object that is already the value of the widget. (This works because the on-change-test property of a lamp is nil by default.)