1 CAPI Reference Entries

button

Summary

Abutton is a pane that displays either a piece of text or a generic image, and that performs an action when pressed. Certain types of buttons can also be selected and deselected.

Superclasses

simple-pane
item

Subclasses

push-button
radio-button
check-button

Slots

interaction

The interaction style for the button.

selected

For radio button and check button styles, ifselected is set tot, the button is initially selected.

callback

Specifies the callback to use when the button is selected.

image

A generic image for the button (ornil).

disabled-image

The image for the button when disabled (ornil).

enabled

Ifnil the button cannot be selected.

Accessors

button-enabled
button-selected

Readers

button-image
button-disabled-image

Description

The abstract classbutton is the class thatpush-button,radio-button, andcheck-button are built on. It can be displayed either with text or a generic image, and a callback is called when the button is clicked. It inherits all of its textual behavior fromitem, including the slottext which is the text that appears in the button. For more details, see item.

The subclasses ofbutton are just buttons with different interaction styles. It can often be easier just to make an instance ofbutton with the correct interaction (for instance, when the interaction is only known at run-time). The interaction styles are as follows:

:no-selection

A push button.

:single-selection

A radio button.

:multiple-selection

A check button.

Both radio buttons and check buttons can have a selection which can be set using theinitarg interaction and the accessorbutton-selected.

The button's callback gets called when the user clicks on the button, and by default gets passed the data in the button and the interface. This can be changed by specifying a callback type as described in the description of callbacks. The following callbacks are accepted by buttons:

:callback

Called when the button is pressed.

:selection-callback

Called when the button is selected.

:retract-callback

Called when the button is deselected.

By default,image anddisabled-image arenil, meaning that the button is a text button, but ifimage is provided then the button displays an image instead of the text. The image can be the name of an image that can be found in the image search path, or an instance of a generic image. The disabled image is the image that is shown when the button is disabled (ornil, meaning that it is left for the window system to decide how to display the image as disabled). For more details about generic images, see the LispWorks User Guide.

The button's actions can be enabled and disabled with theenabled slot, and its associated accessorbutton-enabled. This means that when the button is disabled, pressing on it does not call any callbacks or change its selection.

Note that the class button-panel provides functionality to group buttons together, and should normally be used in preference to creating individual buttons yourself. For instance, aradio-button-panel makes a number of radio buttons and also controls them such that only one button is ever selected at a time.

Example

In the following example a button is created. Using thebutton-enabled accessor the button is then enabled and disabled.

(setq button
      (capi:contain (make-instance 
                     'capi:push-button
                     :text "Press Me")))

(setf (capi:button-enabled button) nil)

(setf (capi:button-enabled button) t)

In the next example a button with an image instead of text is created.

(setq button
      (capi:contain (make-instance
                     'capi:push-button
                     :image "new-lispworks-logo")))

Example File

capi/elements/buttons.lisp

See Also

button-panel
callbacks

Generated with Harlequin WebMaker