Class

Summary

A button 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

Initargs

:interaction

The interaction style for the button.

:selected

For radio button and check button styles, if selected is set to t , the button is initially selected.

:callback

Specifies the callback to use when the button is selected.

:image

A generic image for the button (or nil ).

:selected-image

The image used when the button is selected.

:enabled

If nil the button cannot be selected.

:cancel-p

If true the button is the "Cancel" button, that is, the button selected by the Escape key.

:default-p

If true the button is the default button, that is, the button selected by the Return key.

The following initargs controlling alternate images do not apply on MS Windows:

:disabled-image

The image for the button when disabled (or nil ).

:selected-disabled-image

The image used when the button is selected and disabled.

:armed-image

The image used when the button is pressed and interaction is :no-selection .

The following initargs controlling mnemonics apply only on MS Windows:

:mnemonic

A character specifying a mnemonic for the button, or the symbol :none .

:mnemonic-text

A string specifying the text and a mnemonic.

:mnemonic-escape

A character specifying the mnemonic escape. The default value is #\& .

Accessors

button-selected
button-armed-image
button-selected-image
button-selected-disabled-image
button-enabled
button-cancel-p
button-default-p

Readers

button-image
button-disabled-image

Description

The abstract class button is the class that push-button, radio-button, and check-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 from item, including the slot text which is the text that appears in the button.

The subclasses of button are just buttons with different interaction styles. It can often be easier just to make an instance of button with the correct value of interaction (for instance, when the interaction style is only known at run-time). The values allowed for interaction 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 the initarg :selected and the accessor button-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 and disabled-image are nil , meaning that the button is a text button, but if image 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 (or nil , meaning that it is left for the window system to decide how to display the image as disabled). On MS Windows, thr system computes the disabled image and so disabled-image is ignored. For more details about generic images, see the LispWorks CAPI User Guide .

The button's actions can be enabled and disabled with the enabled slot, and its associated accessor button-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, a radio-button-panel makes a number of radio buttons and also controls them such that only one button is ever selected at a time.

A mnemonic is character which can be entered with the Alt key pressed to invoke a button. The mnemonic is underlined in the button text. To specify a mnemonic in the button, pass mnemonic which should be a character that appears in the button text or the printed representation of the button data . If mnemonic is :none , then there is no mnemonic.

An alternative way to specify a mnemonic is to pass mnemonic-text . This is a string which provides the text for the button and also specifies the mnemonic character. The mnemonic character is preceded in mnemonic-text by mnemonic-escape , and mnemonic-escape is removed from mnemonic-text before the text is displayed. At most one character can be specified as the mnemonic in mnemonic-text .

To make mnemonic-escape itself appear in the button, precede it in mnemonic-text with mnemonic-escape .

Example

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

(setq button

      (capi:contain (make-instance 

                     'capi:push-button

                     :text "Press Me")

                    :process nil))

(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 

        (merge-pathnames  

         "capi/applications/images/info.bmp"

         (sys:lispworks-dir "examples")))))

The following examples illustrate mnemonics:

(defun egg (&rest ignore) 

  (declare (ignore ignore))

  (capi:display-message "Egg"))

(capi:contain 

 (make-instance 'capi:push-button  

                :selection-callback 'egg

                :mnemonic-text "Chicken && Rice"))

(capi:contain 

 (make-instance 'capi:push-button  

                :data "Chicken"

                :selection-callback 'egg

                :mnemonic #\k))

Compare this with the previous example: the #\k does not appear and the #\e becomes the mnemonic:

(capi:contain 

 (make-instance 'capi:push-button  

                :selection-callback 'egg

                :mnemonic-escape  #\k      

                :mnemonic-text "Chicken"))

Also see the example in the directory examples/capi/buttons/ .

See also

button-panel
callbacks