8.1.18 The toggle Widget

Syntax:

type ::= (toggle [keyword argument]...)

A widget that can toggle between two states. Its super is the item widget.

The widget has two possible states, ‘on’ and ‘off’, which correspond to a t or nil value, respectively.

Example:

(widget-insert "Press the button to activate/deactivate the field: ")
(widget-create 'toggle
               :notify (lambda (widget &rest _ignored)
                          (widget-apply widget-example-field
                                        (if (widget-value widget)
                                            :activate
                                          :deactivate))))
(widget-insert "\n")

(setq widget-example-field
      (widget-create 'editable-field
                     :deactivate (lambda (widget)
                                   (widget-specify-inactive
                                    widget
                                    (widget-field-start widget)
                                    (widget-get widget :to)))))
(widget-apply widget-example-field :deactivate)))

It either overrides or adds the following properties:

:format

By default, it buttonizes the value and adds a newline at the end of the widget.

:on

A string representing the ‘on’ state. By default the string ‘on’.

:off

A string representing the ‘off’ state. By default the string ‘off’.

:on-glyph

Name of a glyph to be used instead of the ‘:on’ text string, on emacsen that supports this.

:off-glyph

Name of a glyph to be used instead of the ‘:off’ text string, on emacsen that supports this.

:value-create

A function for creating the widget’s value, according to its ‘:on’ or ‘:off’ state.

:action

Function to toggle the state of the widget. After toggling, it notifies itself.

:match

This widget matches anything.