8.1.21 The checklist Widget

Syntax:

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

A widget to represent a multiplice choice. Its super is the default widget.

The type arguments represent each checklist item. The widget’s value will be a list containing the values of all checked type arguments.

Example:

(widget-create 'checklist
               :notify (lambda (widget child &optional _event)
                         (funcall
                           (widget-value (widget-get-sibling child))
                           'toggle))
               :value (list 'tool-bar-mode 'menu-bar-mode)
               '(item :tag "Tool-bar" tool-bar-mode)
               '(item :tag "Menu-bar" menu-bar-mode))))

It either overrides or adds the following properties:

:convert-widget

As other composite widgets, a function that takes care of converting each checklist item.

:copy

A function to copy each checklist item.

:format

By default, it inserts its value.

:entry-format

This string will be inserted for each entry in the list. The following ‘%’ escapes are available:

‘%v’

Replaced with the buffer representation of the type widget.

‘%b’

Replace with the checkbox.

‘%%’

Insert a literal ‘%’.

:button-args

A list of keywords to pass to the checkboxes. Useful for setting, e.g., the ‘:help-echo’ for each checkbox.

:buttons

The widgets representing the checkboxes.

:children

The widgets representing each type.

:args

The list of types.

:value-create

The function that takes care of inserting all values.

:value-get

A function that returns all values of selected items.

:validate

A function that ensures all selected children are valid.

:match

The checklist widget will match a list whose elements all match at least one of the specified type arguments.

:match-inline

Like the :match function, but taking into account the :inline property.

:greedy

Usually a checklist will only match if the items are in the exact sequence given in the specification. By setting :greedy to non-nil, it will allow the items to come in any sequence. However, if you extract the value they will be in the sequence given in the checklist, i.e., the original sequence is forgotten.