mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-01 08:17:38 +00:00
Code Issues Releases Activity
e53e8b4cf4
emacs/doc/misc/widget.texi
Eli Zaretskii 687c4137fa Merge from origin/emacs-29 
f37f01b504 Fix a typo in Introduction to Emacs Lisp (bug#70571).
d8687fd6cd Fix last change
494dfd9cf2 Fix indentation of if/else in 'csharp-ts-mode' (bug#70345)
1cc6322e61 ; * etc/PROBLEMS: Document crashes due to tree-sitter ABI...
42766f95e5 * build-aux/make-info-dir: Avoid bashism (bug#70484).
81476fa19e Improve documentation of selection and navigation in *xre...
2a53351492 Fix Widget manual typos, markup and omissions (bug#70502)
90be3015b4 ; Document bookmark fringe mark in the user manual
afd0b548fc Fix python-ts-mode built-in functions and attributes (bug...
dc720decc3 Fix markup and indexing in the Calendar chapter of user m...
f593bf79a9 Fix the user manual for `calendar-time-zone-style'
aed2b7a3d8 Avoid assertion violations in 'push_prefix_prop'
c929532b46 Remove ert-equal-including-properties from manual
e3aae5fd38 ; Document 'filtered-frame-list'
2024-04-27 06:23:46 -04:00

3460 lines
102 KiB
Plaintext
Raw Blame History

\input texinfo.tex
@c %**start of header
@setfilename ../../info/widget.info
@settitle The Emacs Widget Library
@include docstyle.texi
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@c %**end of header
@copying
Copyright @copyright{} 2000--2024 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying
@dircategory Emacs lisp libraries
@direntry
* Widget: (widget). The "widget" package used by the Emacs
Customization facility.
@end direntry
@titlepage
@title The Emacs Widget Library
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@node Top
@top The Emacs Widget Library
@insertcopying
@menu
* Introduction::
* User Interface::
* Programming Example::
* Widgets Basics::
* Setting Up the Buffer::
* Working with Widgets::
* Widgets and the Buffer::
* Widget Gallery::
* Defining New Widgets::
* Inspecting Widgets::
* Widget Minor Mode::
* Utilities::
* Customization::
* Widget Wishlist::
* GNU Free Documentation License::
* Index::
@end menu
@node Introduction
@chapter Introduction
Most graphical user interface toolkits provide a number of standard
user interface controls (sometimes known as ``widgets'' or ``gadgets'').
Emacs doesn't really support anything like this, except for an
incredibly powerful text ``widget''. On the other hand, Emacs does
provide the necessary primitives to implement many other widgets
within a text buffer. The @code{widget} package simplifies this task.
@cindex basic widgets
@cindex widgets, basic types
The basic widgets are:
@table @code
@item link
Areas of text with an associated action. Intended for hypertext links
embedded in text.
@item push-button
Like link, but intended for stand-alone buttons.
@item editable-field
An editable text field. It can be either variable or fixed length.
@item menu-choice
Allows the user to choose one of multiple options from a menu, where
each option is itself a widget. Only the selected option is visible
in the buffer.
@item radio-button-choice
Allows the user to choose one of multiple options by activating radio
buttons. The options are implemented as widgets. All options are
visible in the buffer, with the selected one marked as chosen.
@item item
A simple constant widget intended to be used in the @code{menu-choice} and
@code{radio-button-choice} widgets.
@item choice-item
A button item only intended for use in choices. When invoked, the user
will be asked to select another option from the choice widget.
@item toggle
A simple @samp{on}/@samp{off} switch.
@item checkbox
A checkbox (@samp{[ ]}/@samp{[X]}).
@item editable-list
Create an editable list. The user can insert or delete items in the
list. Each list item is itself a widget.
@end table
Now, of what possible use can support for widgets be in a text editor?
I'm glad you asked. The answer is that widgets are useful for
implementing forms. A @dfn{form} in Emacs is a buffer where the user is
supposed to fill out a number of fields, each of which has a specific
meaning. The user is not supposed to change or delete any of the text
between the fields. Examples of forms in Emacs are the @file{forms}
package (of course), the customize buffers, the mail and news compose
modes, and the @acronym{HTML} form support in the @file{w3} browser.
@cindex widget library, why use it
The advantages for a programmer of using the @code{widget} package to
implement forms are:
@enumerate
@item
More complex fields than just editable text are supported.
@item
You can give the users immediate feedback if they enter invalid data in a
text field, and sometimes prevent entering invalid data.
@item
You can have fixed sized fields, thus allowing multiple fields to be
lined up in columns.
@item
It is simple to query or set the value of a field.
@item
Editing happens in the buffer, not in the mini-buffer.
@item
Packages using the library get a uniform look, making them easier for
the user to learn.
@item
As support for embedded graphics improve, the Widget library will be
extended to use the GUI features. This means that your code using the
Widget library will also use the new graphic features automatically.
@end enumerate
@node User Interface
@chapter User Interface
A form consists of read only text for documentation and some fields,
where each field contains two parts, a tag and a value. The tags are
used to identify the fields, so the documentation can refer to the
@samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
example form:
@example
Here is some documentation.
Name: @i{My Name} @strong{Choose}: This option
Address: @i{Some Place
In some City
Some country.}
See also @b{_other work_} for more information.
Numbers: count to three below
@b{[INS]} @b{[DEL]} @i{One}
@b{[INS]} @b{[DEL]} @i{Eh, two?}
@b{[INS]} @b{[DEL]} @i{Five!}
@b{[INS]}
Select multiple:
@b{[X]} This
@b{[ ]} That
@b{[X]} Thus
Select one:
@b{(*)} One
@b{( )} Another One.
@b{( )} A Final One.
@b{[Apply Form]} @b{[Reset Form]}
@end example
The top level widgets in this example are tagged @samp{Name},
@samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
@samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
@samp{[Reset Form]}. There are basically two things the user can do
within a form, namely editing the editable text fields and activating
the buttons.
@section Editable Text Fields
In the example, the value for the @samp{Name} is most likely displayed
in an editable text field, and so are values for each of the members of
the @samp{Numbers} list. All the normal Emacs editing operations are
available for editing these fields. The only restriction is that each
change you make must be contained within a single editable text field.
For example, capitalizing all text from the middle of one field to the
middle of another field is prohibited.
Editable text fields are created by the @code{editable-field} widget.
The @code{:format} keyword is useful for generating the necessary
text; for instance, if you give it a value of @code{"Name: %v "},
the @samp{Name: } part will provide the necessary separating text
before the field and the trailing space will provide the
separating text after the field. If you don't include the
@code{:size} keyword, the field will extend to the end of the
line, and the terminating newline will provide separation after.
The editing text fields are highlighted with the
@code{widget-field-face} face, making them easy to find.
@section Buttons
@cindex widget buttons
@cindex button widgets
Some portions of the buffer have an associated @dfn{action}, which can
be @dfn{invoked} by a standard key or mouse command. These portions
are called @dfn{buttons}. The default commands for activating a button
are @code{widget-button-press} and @code{widget-button-click}. The
user typically interacts with the buttons with a key, like @key{RET},
or with the mouse buttons.
There are several different kind of buttons, all of which are present in
the example:
@table @emph
@cindex option field tag
@item The Option Field Tags
When you invoke one of these buttons, you will be asked to choose
between a number of different options. This is how you edit an option
field. Option fields are created by the @code{menu-choice} widget. In
the example, @samp{@b{Choose}} is an option field tag.
@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
Activating these will insert or delete elements from an editable list.
The list is created by the @code{editable-list} widget.
@cindex embedded buttons
@item Embedded Buttons
The @samp{@b{_other work_}} is an example of an embedded
button. Embedded buttons are not associated with any fields, but can serve
any purpose, such as implementing hypertext references. They are
usually created by the @code{link} widget.
@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
Activating one of these will convert it to the other. This is useful
for implementing multiple-choice fields. You can create them with the
@code{checkbox} widget.
@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
Only one radio button in a @code{radio-button-choice} widget can be
selected at any time. When you invoke one of the unselected radio
buttons, it will be selected and the previous selected radio button will
become unselected.
@item The @samp{@b{[Apply Form]}} and @samp{@b{[Reset Form]}} buttons
These are explicit buttons made with the @code{push-button} widget. The
main difference from the @code{link} widget is that the buttons will be
displayed as GUI buttons when possible.
@end table
To make them easier to locate, buttons are emphasized in the buffer
with a distinctive face, like @code{widget-button-face} or
@code{widget-mouse-face}.
@section Navigation
You can use all the normal Emacs commands to move around in a form
buffer, plus you will have these additional commands to navigate from
widget to widget: @code{widget-forward} and @code{widget-backward}.
@node Programming Example
@chapter Programming Example
@cindex widgets, programming example
@cindex example of using widgets
Here is the code to implement the user interface example (@pxref{User
Interface}).
@lisp
(require 'widget)
(eval-when-compile
(require 'wid-edit))
(defvar widget-example-repeat)
(defun widget-example ()
"Create the widgets from the Widget manual."
(interactive)
(switch-to-buffer "*Widget Example*")
(kill-all-local-variables)
(make-local-variable 'widget-example-repeat)
(let ((inhibit-read-only t))
(erase-buffer))
(remove-overlays)
(widget-insert "Here is some documentation.\n\n")
(widget-create 'editable-field
:size 13
:format "Name: %v " ; Text after the field!
"My Name")
(widget-create 'menu-choice
:tag "Choose"
:value "This"
:help-echo "Choose me, please!"
:notify (lambda (widget &rest ignore)
(message "%s is a good choice!"
(widget-value widget)))
'(item :tag "This option" :value "This")
'(choice-item "That option")
'(editable-field :menu-tag "No option" "Thus option"))
(widget-create 'editable-field
:format "Address: %v"
"Some Place\nIn some City\nSome country.")
(widget-insert "\nSee also ")
(widget-create 'link
:notify (lambda (&rest ignore)
(widget-value-set widget-example-repeat
'("En" "To" "Tre"))
(widget-setup))
"other work")
(widget-insert
" for more information.\n\nNumbers: count to three below\n")
(setq widget-example-repeat
(widget-create 'editable-list
:entry-format "%i %d %v"
:notify
(lambda (widget &rest ignore)
(let ((old (widget-get widget
':example-length))
(new (length (widget-value widget))))
(unless (eq old new)
(widget-put widget ':example-length new)
(message "You can count to %d." new))))
:value '("One" "Eh, two?" "Five!")
'(editable-field :value "three")))
(widget-insert "\n\nSelect multiple:\n\n")
(widget-create 'checkbox t)
(widget-insert " This\n")
(widget-create 'checkbox nil)
(widget-insert " That\n")
(widget-create 'checkbox
:notify (lambda (&rest ignore) (message "Tickle"))
t)
(widget-insert " Thus\n\nSelect one:\n\n")
(widget-create 'radio-button-choice
:value "One"
:notify (lambda (widget &rest ignore)
(message "You selected %s"
(widget-value widget)))
'(item "One") '(item "Another One.")
'(item "A Final One."))
(widget-insert "\n")
(widget-create 'push-button
:notify (lambda (&rest ignore)
(if (= (length
(widget-value widget-example-repeat))
3)
(message "Congratulation!")
(error "Three was the count!")))
"Apply Form")
(widget-insert " ")
(widget-create 'push-button
:notify (lambda (&rest ignore)
(widget-example))
"Reset Form")
(widget-insert "\n")
(use-local-map widget-keymap)
(widget-setup))
@end lisp
@node Widgets Basics
@chapter Widgets Basics
@cindex widget object
The Widget Library deals with widgets objects. A widget object has
properties whose value may be anything, be it numbers, strings,
symbols, functions, etc. Those properties are referred to as keywords
and are responsible for the way a widget is represented in a buffer,
and control the way a user or a program can interact with it.
@cindex widget inheritance
The library defines several widget types, and gives you a way to
define new types as well. In addition, widgets can derive from other
types, creating a sort of widget inheritance. In fact, all widgets
defined in the Widget Library share a common parent, the @dfn{default}
widget. In this manual, when we talk about a default behavior, we
usually mean the behavior as defined by this @code{default} widget.
@xref{Widget Gallery}, for a description of each defined widget.
Defining a new type that derives from a previous one is not mandatory
to create widgets that work very different from a specified type.
When creating a widget, you can override any default property,
including functions, that control the widget. That is, you can
specialize a widget on creation, without having to define it as a new
type of widget.
In addition to the function for defining a widget, this library
provides functions to create widgets, query and change its properties,
respond to user events and destroy them. The following sections
describe them.
@cindex widget value
One important property of a widget is its @dfn{value}. All widgets
may have a value, which is stored in a so-called @dfn{internal format}.
For the rest of Emacs, the widget presents its value in a so-called
@dfn{external format}. Both formats can be equal or different, and
each widget is responsible for defining how the conversion between
each format should happen.
@c FIXME: Briefly describe inline widgets?
@c The inline concept is described elsewhere, and it's difficult to
@c describe.
The value property is an important property for almost all widgets,
and perhaps more important for @code{editable-field} widgets. This
type of widgets allow the user to edit them via the usual editing
commands in Emacs. They can also be edited programmatically.
@strong{Important:} You @emph{must} call @code{widget-setup} after
modifying the value of a widget before the user is allowed to edit the
widget again. It is enough to call @code{widget-setup} once if you
modify multiple widgets. This is currently only necessary if the widget
contains an editing field, but may be necessary for other widgets in the
future.
@cindex widget properties
If your application needs to associate some information with the widget
objects, for example a reference to the item being edited, it can be
done with the @code{widget-put} and @code{widget-get} functions. The
property names, as shown, are keywords, so they must begin with a
@samp{:}.
@node Setting Up the Buffer
@chapter Setting Up the Buffer
@cindex widget creation, widget conversion
To show the widgets in a buffer, you have to create them. Widget
creation is actually a two-step process: conversion and creation per
se. With simple projects, usually the conversion step isn't really
important, and you only care about widget creation, so feel free to
skip the conversion description until you really need to know it.
Widget conversion is the process that involves taking a widget
specification and transforming it into a @dfn{widget} object, suitable
to be created, queried and manipulated with other widget functions.
Widget creation is the process that takes a widget object and actually
inserts it in the buffer.
The simplest function to create a widget is @code{widget-create}, which
gets a widget specification and returns a widget object.
@defun widget-create type [ keyword argument ]@dots{} args
Create and return a widget of type @var{type}, converting it.
@var{type} is a symbol that specifies a widget type. @var{keyword}
may be one of the properties supported by the widget type, and
@var{argument} specify the value for that property. These keyword
arguments can be used to overwrite the keyword arguments that are part
of @var{type} by default, as well as to provide other properties not
present in @var{type} by default. @var{args} holds additional
information for the creation of @var{type} and each widget type is
responsible for handling that information in a specific way.
The syntax for the @var{type} argument is described in @ref{Widget
Gallery}, and in more detail in every widget where it's relevant.
@end defun
There are other functions for creating widgets, useful when you work
with composite widgets. That is, widgets that are part of other
widgets.
@defun widget-create-child-and-convert parent type &rest args
Create a widget of type @var{type} as a child of @var{parent}.
Before creating it, converts @var{type} using the keyword arguments
provided in @var{args}.
@c FIXME: Is this description useful?
Adds the @code{:indent} property, unless it is already present, and
sets it to the sum of the values of: @code{:indent} and @code{:offset}
from @var{parent} and @code{:extra-offset} from @var{type}.
Returns a widget object, with the property @code{:parent} set to
@var{PARENT}.
@end defun
@defun widget-create-child parent type
Create a widget of type @var{type} as a child of @var{parent}.
This function is like @code{widget-create-child-and-convert} but it
doesn't convert @var{type}, so it expects an already converted widget.
@end defun
@defun widget-create-child-value parent type value
Create a widget of type @var{type} as a child of @var{parent} with
value @var{value}.
This function is like @code{widget-create-child}, but it lets you
specify a value for the widget.
Converts @var{value} to the internal format, as specified by
@var{type}, and stores it into the @code{:value} property of @var{type}.
That means, @var{value} should be in the external format, as
specified by @var{type}.
@end defun
All these creating functions described here use the function stored in
the @code{:create} property. So, to modify the creation logic for a
widget, you can provide a different @code{:create} function.
When you're done creating widgets and you're ready for the user to
interact with the buffer, use the function @code{widget-setup}.
@defun widget-setup
Setup the current buffer, so that editable widgets can be edited.
This should be called after creating all the widgets and before allowing
the user to edit them.
@end defun
As mentioned, all these functions return a widget object. That widget
object can be queried and manipulated with widget functions that
take widgets as arguments, until deleting it with the widgets
functions available to delete widgets. Even if you don't save the
returned widget object, you still can interact programmatically with
the widget. @xref{Working with Widgets}.
@defun widget-delete widget
Delete the widget @var{widget} and remove it from the buffer.
@end defun
@defun widget-children-value-delete widget
Delete all children and buttons in widget @var{widget}.
This function does not delete @var{widget} itself, only the widgets
stored in the @code{:children} and @code{:buttons} properties. It
also sets those properties to @code{nil}.
@end defun
As with the creation mechanism, the function stored in @code{:delete}
controls the deletion mechanism for a widget.
Additionally, the library provides a way to make a copy of a widget.
@defun widget-copy widget
Makes a copy of widget @var{widget} and returns it.
It uses the function stored in the @code{:copy} property of @var{widget}
and returns the widget that that function returns.
@end defun
As discussed, there is a conversion step when creating a widget. To
do the conversion without actually creating the widget, you can use
the @code{widget-convert} function.
@defun widget-convert type &rest args
Convert @var{type} to a widget object, using keyword arguments @var{args}.
Returns a widget object, suitable for creation. It calls the function
stored in the @code{:convert-widget} property, after putting into the
@code{:args} property the arguments that the widget in question needs.
If @var{type} has a @code{:value} property, either originally or after
doing the conversion, this function converts the value stored in
@code{:value} to the internal format, and stores it into @code{:value}.
@end defun
Apart from only creating widgets in the buffer, It's useful to have
plain text. For inserting text, the recommended way is with the
@code{widget-insert} function.
@defun widget-insert &rest args
Insert @var{args}, either strings or characters, at point.
Uses @code{insert} to perform the insertion, passing @var{args} as
argument. @xref{Insertion,,,elisp, the Emacs Lisp Reference Manual},
for more information about @var{args}.
The resulting text will be read-only.
@end defun
@node Working with Widgets
@chapter Working with Widgets
This section covers the more important functions needed to query and
manipulate widgets in a generic way. Widgets may have additional
functions for interacting with them, those are described in the
description for each widget. @xref{Widget Gallery}.
@defun widgetp widget
Non-@code{nil} if @var{widget} is a widget.
@end defun
@defun widget-type widget
Return the type of widget @var{widget}, a symbol.
This function is useful to find out which kind of widget @var{widget}
represents, i.e., the name of the widget type when the widget
was created.
@end defun
@defun widget-member widget property
Non-@code{nil} if widget @var{widget} has a value (even @code{nil}) for
property @var{property}.
@end defun
@defun widget-get widget property
For widget @var{widget}, return the value of the property @var{property}.
@var{property} should be a keyword, and the value is what was last set by
@code{widget-put} for @var{property}.
@end defun
@defun widget-put widget property value
For widget @var{widget}, set the property @var{property} to @var{value}.
@var{property} should be a keyword, while @var{value} can be anything.
@end defun
@defun widget-at &optional pos
Return the widget at position @var{pos}, or at point if @var{pos} is @code{nil}.
@end defun
@defun widget-field-at pos
Return the widget field at position POS, or @code{nil} if there is none.
@end defun
@defun widget-apply widget property &rest args
Apply the function stored in @var{property} to @var{widget}, passing @var{args}
as additional arguments to the function.
Returns the result of that function call.
@end defun
@defun widget-value widget
Return the current value contained in @var{widget}.
Note that the value returned by this function might differ from what's
stored in the @code{:value} property of @var{widget}. This is because
this function extracts the current value of @var{widget} from the
buffer, taking editions into account.
The value returned is in the external format, after getting it with
the @code{:value-get} function.
It is an error to call this function on an uninitialized widget.
@end defun
@defun widget-value-set widget value
Set the value contained in @var{widget} to @var{value}.
Converts @var{value} to the internal format, and then sets it by
applying the @code{:value-set} function.
It is an error to call this function with an invalid @var{value}, that
is, a value that @var{widget} cannot represent.
@end defun
@defun widget-default-get widget
Return the default external value of widget @var{widget}.
The default value is the one stored in @code{:value} or the result of
applying the @code{:default-get} function to the arguments of
@var{widget}, as stored in @code{:args}. A value of @code{nil} is
ignored by default, so in order for a widget to respect @code{nil} as
a value, it has to override the @code{:default-get} function.
@end defun
@defun widget-type-default-get widget
Convert the @code{:type} attribute in @var{widget} and return its
default value.
@end defun
@defun widget-child-value-get widget
Return the value of the first member of @code{:children} in
@var{widget}.
@end defun
@defun widget-child-value-inline widget
Return the inline value of the first member of @code{:children} in
@var{widget}.
The inline value is whatever the function stored in
@code{:value-inline} returns.
@end defun
@defun widget-type-value-create widget
Create a child widget for @var{widget}, of type stored in
@code{:type}.
Creates the child widget taking the value from the @code{:value}
property and stores the newly created widget in the @code{:children}
property of @var{widget}.
The value stored in @code{:type} should be an unconverted widget
type.
@end defun
@defun widget-value-convert-widget widget
Initializes the @code{:value} property of @var{widget} from
@code{:args}.
Sets @code{:args} to @code{nil} and returns the modified widget
@var{widget}.
@end defun
@defun widget-value-value-get widget
Return the value stored in @code{:value} for widget @var{widget}.
This is different to getting the current value for @var{widget} with
@code{widget-value}, since that function extracts the value from the
buffer.
@end defun
@defun widget-apply-action widget &optional event
Apply the function stored in @code{:action} to @var{widget}, in
response to @var{event}.
It is an error to call this function with an inactive widget.
@end defun
@defun widget-parent-action widget &optional event
Tell @code{:parent} of @var{widget} to handle @var{event}.
Optional @var{event} is the event that triggered the action.
@end defun
@defun widget-child-validate widget
Check that the first member of @code{:children} in @var{widget} is valid.
To be valid means that the widget value passes the checks that the
function stored in @code{:validate} makes.
@end defun
@defun widget-children-validate widget
Check that all @code{:children} in @var{widget} are valid.
Returns @code{nil} on success, or the first child that isn't valid.
@end defun
@defun widget-type-match widget value
Return non-@code{nil} if @var{VALUE} matches the value for the
@code{:type} widget.
As with the other type functions, the widget stored in @code{:type}
should be an unconverted widget.
@end defun
@defun widget-types-copy widget
Copy the @code{:args} value in @var{widget} and store them in @code{:args}.
Makes the copies by calling @code{widget-copy} on each element present
in @code{:args}. Returns the modified widget @var{widget}.
@end defun
@defun widget-types-convert-widget widget
Convert the @code{:args} value in @var{widget} and store them in
@code{args}.
Returns the modified widget @var{widget}.
@end defun
@node Widgets and the Buffer
@chapter Widgets and the Buffer
This chapter describes commands that are specific to buffers that
contain widgets.
@cindex widget keybindings
@defvar widget-keymap
Keymap containing useful bindings for buffers containing widgets.
Binds @key{TAB} to @code{widget-forward} and both @kbd{S-@key{TAB}} and
@kbd{M-@key{TAB}} to @code{widget-backward}. It also binds @key{RET} to
@code{widget-button-press} and both @kbd{down-mouse-1} and
@kbd{down-mouse-2} to @code{widget-button-click}.
@end defvar
There's also a keymap for events that the Widget library doesn't need
to handle.
@defvar widget-global-map
Keymap used by @code{widget-button-press} and @code{widget-button-click}
when not on a button. By default this is @code{global-map}.
@end defvar
In addition to these two keymaps, each widget might define a keymap of
its own, active when events happen at that widget.
@cindex widget navigation
The following navigation commands are available:
@table @kbd
@item @key{TAB}
@deffn Command widget-forward &optional count
Move point @var{count} buttons or editing fields forward.
@end deffn
@item M-@key{TAB}
@itemx S-@key{TAB}
@deffn Command widget-backward &optional count
Move point @var{count} buttons or editing fields backward.
@end deffn
@end table
@noindent
By default, tabbing can put point on an inactive widget. To skip over
inactive widgets when tabbing, set the user option
@code{widget-skip-inactive} to a non-@code{nil} value.
@xref{Customization}.
When editing an @code{editable-field} widget, the following commands
are available:
@table @kbd
@item C-e
@deffn Command widget-end-of-line
Move point to the end of field or end of line, whichever is first.
@end deffn
@item C-k
@deffn Command widget-kill-line
Kill to end of field or end of line, whichever is first.
@end deffn
@item M-@key{TAB}
@itemx C-M-i
@deffn Command widget-complete
Complete the content of the editable field at point.
@end deffn
@item C-m
@itemx @key{RET}
@deffn Command widget-field-activate
Invoke the editable field at point.
@end deffn
@end table
The following two commands can execute the action associated with a
button widget (e.g., a radio button or checkbox):
@table @kbd
@item @key{RET}
@itemx C-m
@findex widget-button-press
@deffn Command widget-button-press @var{pos} &optional @var{event}
Invoke the button at @var{pos}, defaulting to point.
Invocation means to run the function stored in the @code{:action}
property.
If point is not located on a button, invoke the binding in
@code{widget-global-map} (by default the global map).
@end deffn
@kindex mouse-2 @r{(on button widgets})
@item mouse-2
@findex widget-button-click
@deffn Command widget-button-click @var{event}
Invoke the button at the location of the mouse pointer.
If the mouse pointer is located in an editable text field, invoke the
binding in @code{widget-global-map} (by default the global map).
In case the mouse-click is on a widget, calls the function stored in
the @code{:mouse-down-action} property.
@end deffn
@end table
@node Widget Gallery
@chapter Widget Gallery
@cindex widget syntax
All widgets can be created from a type specification. The general
syntax of a type specification is:
@c FIXME: Add BNF reference here? If yes, what reference?
@example
@var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
| @var{name}
@end example
Where @var{name} is a widget name, as defined with
@code{define-widget}, @var{keyword} is the name of a property and
@var{argument} is the value for that property, and @var{args} are
interpreted in a widget specific way. @xref{Defining New Widgets}.
@menu
* Basic Types::
* Sexp Types::
@end menu
@node Basic Types
@section Basic Types
@menu
* default::
* item::
* link::
* url-link::
* info-link::
* function-link::
* variable-link::
* face-link::
* file-link::
* emacs-library-link::
* emacs-commentary-link::
* push-button::
* editable-field::
* text::
* menu-choice::
* radio-button-choice::
* choice-item::
* toggle::
* radio-button-toggle::
* checkbox::
* checklist::
* editable-list::
* group::
* documentation-string::
@end menu
@node default
@subsection The @code{default} Widget
@findex default@r{ widget}
The most basic widget in the Widget Library is the @dfn{default}
widget. It provides the basic behavior for all other widgets, and all
its properties are present by default in derived widgets. You're
seldom (if ever) going to effectively create a default widget, but
here we describe its properties and behavior, so that we can describe
other widgets only by mentioning the properties and behavior those
other widgets specialize.
@deffn Widget default
Widget used as a base for other widgets.
It provides most of the functionality that is referred to as ``by
default'' in this text. If you want to define a new widget from
scratch, use the @code{default} widget as its base.
@end deffn
@cindex keyword arguments
The following keyword arguments apply to all widgets:
@table @code
@vindex create@r{ keyword}
@item :create
Function to create a widget from scratch.
The function takes one argument, a widget type, and creates a widget
of that type, inserts it in the buffer, and returns a widget object.
By default, it inserts the widget at point, using the format provided
in the @code{:format} property.
@vindex delete@r{ keyword}
@item :delete
Function to delete a widget.
The function should take one argument, a widget, and should remove all
traces of the widget from the buffer.
The default value is:
@defun widget-default-delete widget
Remove @var{widget} from the buffer.
Delete all @code{:children} and @code{:buttons} in @var{widget}.
@end defun
In most cases you should not change this value, but instead use
@code{:value-delete} to make any additional cleanup.
@cindex internal format
@cindex external format
@vindex value@r{ keyword}
@item :value
The initial value for widgets of this type.
Typically, a widget represents its value in two formats: external and
internal. The external format is the value as the rest of Emacs sees
it, and the internal format is a representation that the widget
defines and uses in a widget specific way.
Both formats might be the same for certain widgets and might differ
for others, and there is no guarantee about which format the value
stored in the @code{:value} property has. However, when creating a
widget or defining a new one (@pxref{Defining New Widgets}), the
@code{:value} should be in the external format.
@vindex value-to-internal@r{ keyword}
@item :value-to-internal
Function to convert the value to the internal format.
The function takes two arguments, a widget and an external value, and
returns the internal value. The function is called on the present
@code{:value} when the widget is created, and on any value set later
with @code{widget-value-set}.
@vindex value-to-external@r{ keyword}
@item :value-to-external
Function to convert the value to the external format.
The function takes two arguments, a widget and an internal value, and
returns the value in the external format.
@vindex value-create@r{ keyword}
@item :value-create
Function to expand the @samp{%v} escape in the format string.
It will be called with the widget as its argument and should insert a
representation of the widget's value in the buffer.
@vindex value-delete@r{ keyword}
@item :value-delete
A function that should remove the representation of the widget's value
from the buffer.
It will be called with the widget as its argument. It doesn't have to
remove the text, but it should release markers and delete nested widgets
if these are not listed in @code{:children} or @code{:buttons}.
By default, it's a no-op.
@vindex value-get@r{ keyword}
@item :value-get
Function to extract the value of a widget, as it is displayed in the
buffer.
@vindex value-set@r{ keyword}
@item :value-set
Function that takes a widget and a value as arguments, and recreates
it.
The value must already be in the internal format for widget. By
default, it deletes the widget with the @code{:delete} function and
creates it again with the @code{:create} function.
@vindex value-inline@r{ keyword}
@item :value-inline
Function that takes a widget and returns its value, inlined.
Inlined means that if the widget is not inline (i.e., its
@code{:inline} property is @code{nil}), the return value is wrapped in
a list.
@vindex default-get@r{ keyword}
@item :default-get
Function that takes a widget and returns its default value.
By default, it just returns the value stored in @code{:value}.
@vindex format@r{ keyword}
@item :format
This string will be inserted in the buffer when you create a widget.
The following @samp{%} escapes are available:
@table @samp
@item %[
@itemx %]
The text inside will be marked as a button.
By default, the text will be shown in @code{widget-button-face}, and
surrounded by brackets.
@item %@{
@itemx %@}
The text inside will be displayed with the face specified by
@code{:sample-face}.
@item %v
This will be replaced with the buffer representation of the widget's
value. What this is depends on the widget type.
@item %d
Insert the string specified by @code{:doc} here.
@item %h
Like @samp{%d}, with the following modifications: If the documentation
string is more than one line, it will add a button which will toggle
between showing only the first line, and showing the full text.
Furthermore, if there is no @code{:doc} property in the widget, it will
instead examine the @code{:documentation-property} property. If it is a
lambda expression, it will be called with the widget's value as an
argument, and the result will be used as the documentation text.
@item %t
Insert the string specified by @code{:tag} here, or the @code{princ}
representation of the value if there is no tag.
@item %%
Insert a literal @samp{%}.
@end table
@vindex button-face@r{ keyword}
@item :button-face
Face used to highlight text inside %[ %] in the format.
@vindex button-prefix@r{ keyword}
@vindex button-suffix@r{ keyword}
@item :button-prefix
@itemx :button-suffix
Strings used as prefix and suffix for widgets that are buttons.
By default, the values are @code{widget-button-prefix} and
@code{widget-button-suffix}.
Text around %[ %] in the format.
These can be
@table @emph
@item nil
No text is inserted.
@item a string
The string is inserted literally.
@item a symbol
The value of the symbol is expanded according to this table.
@end table
@vindex doc@r{ keyword}
@item :doc
The string inserted by the @samp{%d} escape in the format
string.
@vindex tag@r{ keyword}
@item :tag
The string inserted by the @samp{%t} escape in the format
string.
@vindex tag-glyph@r{ keyword}
@item :tag-glyph
Name of image to use instead of the string specified by @code{:tag} on
Emacsen that supports it.
@vindex help-echo@r{ keyword}
@item :help-echo
Specifies how to display a message whenever you move to the widget with
either @code{widget-forward} or @code{widget-backward} or move the mouse
over it (using the standard @code{help-echo} mechanism).
The value is either a string to display, or a function of one
argument, the widget. If a function, it should return a string to
display, or a form that evaluates to such a string.
@vindex follow-link@r{ keyword}
@item :follow-link
Specifies how to interpret a @key{mouse-1} click on the widget.
@xref{Clickable Text,, Defining Clickable Text, elisp, the Emacs Lisp Reference Manual}.
@vindex indent@r{ keyword}
@item :indent
An integer indicating the absolute number of spaces to indent children
of this widget. Its value might be @code{nil} too, which corresponds
to a value of 0.
The default @code{:create} functions and the functions that create the
value per se use this property as a rudimentary layout mechanism for
the widgets.
@vindex offset@r{ keyword}
@item :offset
An integer indicating how many extra spaces to add to the widget's
grandchildren compared to this widget.
@vindex extra-offset@r{ keyword}
@item :extra-offset
An integer indicating how many extra spaces to add to the widget's
children compared to this widget.
@vindex menu-tag@r{ keyword}
@item :menu-tag
Tag used in the menu when the widget is used as an option in a
@code{menu-choice} widget.
@vindex menu-tag-get@r{ keyword}
@item :menu-tag-get
Function that takes a widget and returns the tag when the widget is
used as an option in a @code{menu-choice} widget.
By default, the tag used will be either the @code{:menu-tag} or
@code{:tag} property if present, or the @code{princ} representation of
the @code{:value} property if not.
@vindex match@r{ keyword}
@item :match
Should be a function called with two arguments, the widget and an
external value, and should return non-@code{nil} if the widget can
represent the specified value.
@vindex validate@r{ keyword}
@item :validate
A function which takes a widget as an argument, and returns @code{nil}
if the widget's current value is valid for the widget.
Otherwise, it should return the widget containing the invalid data,
and set that widget's @code{:error} property to a string explaining
the error.
By default, it always returns @code{nil}.
@vindex tab-order@r{ keyword}
@item :tab-order
Specify the order in which widgets are traversed with
@code{widget-forward} or @code{widget-backward}. This is only partially
implemented.
@enumerate a
@item
Widgets with tabbing order @code{-1} are ignored.
@item
(Unimplemented) When on a widget with tabbing order @var{n}, go to the
next widget in the buffer with tabbing order @var{n+1} or @code{nil},
whichever comes first.
@item
When on a widget with no tabbing order specified, go to the next widget
in the buffer with a positive tabbing order, or @code{nil}
@end enumerate
@vindex parent@r{ keyword}
@item :parent
The parent of a nested widget (e.g., a @code{menu-choice} item or an
element of a @code{editable-list} widget).
@vindex sibling-args@r{ keyword}
@item :sibling-args
This keyword is only used for members of a @code{radio-button-choice} or
@code{checklist}. The value should be a list of extra keyword
arguments, which will be used when creating the @code{radio-button} or
@code{checkbox} associated with this item.
@vindex completions-function@r{ keyword}
@item :completions-function
Function that takes a widget and returns completion data for that
widget, like @code{completion-at-point-functions} would.
@xref{Completion,,,elisp, the Emacs Lisp Reference Manual}. It's
used by @code{editable-field} widgets to provide completions.
By default, it looks into the property @code{:completions}, which
should be a completion table. If @code{:completions} is @code{nil},
then it calls the function stored either in the @code{:complete} or
@code{:complete-function} property.
@vindex format-handler@r{ keyword}
@item :format-handler
Function to handle unknown @samp{%} escapes in the format string.
It takes a widget and the character that follows the @samp{%} as
arguments. You can set this to allow your widget to handle
non-standard escapes in your own specialized widgets.
@findex widget-default-format-handler
You should end up calling @code{widget-default-format-handler} to handle
unknown escape sequences, which will handle the @samp{%h} and any future
escape sequences, as well as give an error for unknown escapes.
@vindex button-face-get@r{ keyword}
@item :button-face-get
Function to return the face used to fontify a widget button.
Takes a widget and returns an appropriate face for the widget. By
default, it either returns the face stored in the @code{:button-face}
property, or calls the @code{:button-face-get} function from the
parent of the widget, if it has one.
@vindex mouse-face-get@r{ keyword}
@item :mouse-face-get
Function to return the face used to fontify a widget when the mouse
pointer hovers over it.
Takes a widget and returns an appropriate face. By default, it either
returns the face stored in the @code{:mouse-face} property, or calls
the @code{:button-face-get} function from the parent of the widget, if
it has one.
@vindex copy@r{ keyword}
@item :copy
Function to deep copy a widget type.
It takes a shallow copy of the widget type as an argument (made by
@code{copy-sequence}), and returns a deep copy. The purpose of this
is to avoid having different instances of combined widgets share
nested attributes.
Its value by default is @code{identity}.
@vindex active@r{ keyword}
@item :active
Function that takes a widget and returns @code{t} if it is active.
A widget might be effectively always active, if its
@code{:always-active} property is @code{t}.
@cindex active widget
@cindex inactive widget
@cindex activate a widget
@cindex deactivate a widget
Widgets can be in two states: active, which means they are modifiable by
the user, or inactive, which means they cannot be modified by the user.
You can query or set the state with the following code:
@lisp
;; Examine if @var{widget} is active or not.
(if (widget-apply @var{widget} :active)
(message "Widget is active.")
(message "Widget is inactive.")
;; Make @var{widget} inactive.
(widget-apply @var{widget} :deactivate)
;; Make @var{widget} active.
(widget-apply @var{widget} :activate)
@end lisp
A widget is inactive if it, or any of its ancestors (found by
following the @code{:parent} link), have been deactivated. To make sure
a widget is really active, you must therefore activate both it and
all its ancestors.
@lisp
(while widget
(widget-apply widget :activate)
(setq widget (widget-get widget :parent)))
@end lisp
You can check if a widget has been made inactive by examining the value
of the @code{:inactive} keyword. If this is non-@code{nil}, the widget itself
has been deactivated. This is different from using the @code{:active}
keyword, in that the latter tells you if the widget @strong{or} any of
its ancestors have been deactivated. Do not attempt to set the
@code{:inactive} keyword directly. Use the @code{:activate}
@code{:deactivate} functions instead.
@vindex activate@r{ keyword}
@item :activate
Function that takes a widget and makes it active for user
modifications.
@vindex deactivate@r{ keyword}
@item :deactivate
Function that takes a widget and makes it inactive for user
modifications.
@vindex action@r{ keyword}
@item :action
Function that takes a widget and optionally an event, and handles a
user initiated event.
By default, uses the @code{:notify} function to notify the widget's
parent about the event.
@vindex mouse-down-action@r{ keyword}
@item :mouse-down-action
Function that takes a widget and optionally an event, and handles a
mouse click on the widget.
By default, it does nothing.
@vindex notify@r{ keyword}
@item :notify
A function called each time the widget or a nested widget is changed.
The function is called with two or three arguments. The first argument
is the widget itself, the second argument is the widget that was
changed, and the third argument is the event leading to the change, if
any.
By default, it passes the notification to the widget's parent.
@vindex prompt-value@r{ keyword}
@item :prompt-value
Function to prompt for a value in the minibuffer.
The function should take four arguments, a widget, a prompt (a
string), a value and a boolean, and should return a value for the
widget, entered by the user.
The prompt is the prompt to use. The value is the default value to
use, unless the fourtha argument is non-@code{nil}, in which case
there is no default value.
The function should read the value using the method most natural for
this widget, and does not have to check that it matches.
@end table
@node item
@subsection The @code{item} Widget
@findex item@r{ widget}
Syntax:
@example
@var{type} ::= (item [@var{keyword} @var{argument}]... @var{value})
@end example
A useful widget that holds a constant value, and can be included in
other widgets. Its super is the @code{default} widget.
As can be seen in the syntax, the @code{item} widget is one of the
widget that handles the @var{args} argument to @code{widget-create} in
a specific way. If present, @var{value} is used to initialize the
@code{:value} property. When created, it inserts the value as a
string in the buffer.
@noindent
Example:
@lisp
(widget-create 'item :tag "Today is" :format "%t: %v\n"
(format-time-string "%d-%m-%Y"))
@end lisp
By default, it has the following properties:
@table @code
@item :convert-widget
The function that allows it to handle @var{value}.
@item :value-create
Prints the representation of @code{:value} in the buffer.
@item :value-get
Returns the value stored in @code{:value}.
@item :match
A value matches the @code{item} widget if it's @code{equal} to its
@code{:value}.
@item :match-inline
Inline values match the @code{item} widget if @code{:value} is a
sublist of values.
@item :action
The @code{item} widget notifies itself of an event.
@item :format
By default, the @code{item} widget inserts its tag in the buffer.
@end table
@node link
@subsection The @code{link} Widget
@findex link@r{ widget}
Syntax:
@example
@var{type} ::= (link [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
A widget to represent an embedded link. Its super is the @code{item}
widget.
The @var{value}, if present, is used to initialize the @code{:value}
property. The value should be a string, which will be inserted in the
buffer.
@noindent
Example:
@lisp
(widget-create 'link
:button-prefix ""
:button-suffix ""
:tag "Mail yourself"
:action #'(lambda (widget &optional _event)
(compose-mail-other-window (widget-value widget)))
user-mail-address)
@end lisp
By default, it has the following properties:
@table @code
@item :button-prefix
The value of @code{widget-link-prefix}.
@item :button-suffix
The value of @code{widget-link-suffix}.
@item :keymap
A custom keymap for the link widget, so that it can respond to mouse clicks.
@item :follow-link
This property allows the link to respect the value of
@code{mouse-1-click-follows-link}. @xref{Clickable Text,,,elisp, the Emacs Lisp Reference Manual}.
@item :format
Buttonizes the link, to make it clickable.
If you override this property, you should make sure to provide the
@samp{%[} and @samp{%]} escape sequences, so that the link is
clickable.
@end table
By default the link will be shown in brackets.
@node url-link
@subsection The @code{url-link} Widget
@findex url-link@r{ widget}
Syntax:
@example
@var{type} ::= (url-link [@var{keyword} @var{argument}]... @var{url})
@end example
A widget to represent a link to a web page. Its super is the
@code{link} widget.
It overrides the @code{:action} property to open up the @var{url}
specified.
@noindent
Example:
@lisp
@group
(widget-create 'url-link
:button-prefix ""
:button-suffix ""
;; Return appropriate face.
:button-face-get (lambda (widget)
(if (widget-get widget :visited)
'link-visited
'link))
:format "%[%t%]"
:tag "Browse this manual"
:action (lambda (widget &optional _event)
(widget-put widget :visited t)
;; Takes care of redrawing the widget.
(widget-value-set widget (widget-value widget))
;; And then call the original function.
(widget-url-link-action widget))
"https://www.gnu.org/software/emacs/manual/html_mono/widget.html")
@end group
@end lisp
@node info-link
@subsection The @code{info-link} Widget
@findex info-link@r{ widget}
Syntax:
@example
@var{type} ::= (info-link [@var{keyword} @var{argument}]... @var{address})
@end example
A widget to represent a link to an info file. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to start the
built-in Info reader on @var{address}, when invoked.
@noindent
Example:
@lisp
(widget-create 'info-link
:button-prefix ""
:button-suffix ""
:tag "Browse this manual"
"(widget) info-link")))
@end lisp
@node function-link
@subsection The @code{function-link} Widget
@findex function-link@r{ widget}
Syntax:
@example
@var{type} ::= (function-link [@var{keyword} @var{argument}]... @var{function})
@end example
A widget to represent a link to an Emacs function. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to describe
@var{function}.
@noindent
Example:
@lisp
(widget-create 'function-link
:button-prefix ""
:button-suffix ""
:tag "Describe the function that gets called"
#'widget-function-link-action)
@end lisp
@node variable-link
@subsection The @code{variable-link} Widget
@findex variable-link@r{ widget}
Syntax:
@example
@var{type} ::= (variable-link [@var{keyword} @var{argument}]... @var{var})
@end example
A widget to represent a link to an Emacs variable. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to describe
@var{var}.
@noindent
Example:
@lisp
(widget-create 'variable-link
:button-prefix ""
:button-suffix ""
:tag "What setting controls button-prefix?"
'widget-button-prefix)
@end lisp
@node face-link
@subsection The @code{face-link} Widget
@findex face-link@r{ widget}
Syntax:
@example
@var{type} ::= (face-link [@var{keyword} @var{argument}]... @var{face})
@end example
A widget to represent a link to an Emacs face. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to describe
@var{face}.
@noindent
Example:
@lisp
(widget-create 'face-link
:button-prefix ""
:button-suffix ""
:tag "Which face is this one?"
'widget-button)
@end lisp
@node file-link
@subsection The @code{file-link} Widget
@findex file-link@r{ widget}
Syntax:
@example
@var{type} ::= (file-link [@var{keyword} @var{argument}]... @var{file})
@end example
A widget to represent a link to a file. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to find the file
@var{file}.
@noindent
Example:
@lisp
(let ((elisp-files (directory-files user-emacs-directory t ".el$")))
(dolist (file elisp-files)
(widget-create 'file-link
:button-prefix ""
:button-suffix ""
file)
(widget-insert "\n")))
@end lisp
@node emacs-library-link
@subsection The @code{emacs-library-link} Widget
@findex emacs-library-link@r{ widget}
Syntax:
@example
@var{type} ::= (emacs-library-link [@var{keyword} @var{argument}]... @var{file})
@end example
A widget to represent a link to an Emacs Lisp file. Its super is the
@code{link} widget.
It overrides the @code{:action} property, to a function to find the file
@var{file}.
@noindent
Example:
@lisp
(widget-create 'emacs-library-link
:button-prefix ""
:button-suffix ""
:tag "Show yourself, Widget Library!"
"wid-edit.el")
@end lisp
@node emacs-commentary-link
@subsection The @code{emacs-commentary-link} Widget
@findex emacs-commentary-link@r{ widget}
Syntax:
@example
@var{type} ::= (emacs-commentary-link [@var{keyword} @var{argument}]... @var{file})
@end example
A widget to represent a link to the Comment section of an Emacs Lisp
file. Its super is the @code{link} widget.
It overrides the @code{:action} property, to a function to find the file
@var{file} and put point in the Comment section.
@noindent
Example:
@lisp
(widget-create 'emacs-commentary-link
:button-prefix ""
:button-suffix ""
:tag "Check our good friend Customize"
"cus-edit.el")
@end lisp
@node push-button
@subsection The @code{push-button} Widget
@findex push-button@r{ widget}
Syntax:
@example
@var{type} ::= (push-button [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
A widget that acts as a pushable button. Its super is the @code{item}
widget.
The @var{value}, if present, is used to initialize the @code{:value}
property. The value should be a string, which will be inserted in the
buffer.
By default, it has the following properties:
@table @code
@item :button-prefix
The empty string.
@item :button-suffix
The empty string.
@item :value-create
Inserts a representation of the ``on'' and ``off'' states for the push
button.
The representation might be an image, stored in the @code{:tag-glyph}
property, or text. If it is text, it might be the value of the
@code{:tag} property, or the @code{:value} of the widget, surrounded
with @code{widget-push-button-prefix} and
@code{widget-push-button-suffix}. @xref{Customization}.
@item :format
Buttonizes the widget, to make it clickable.
@end table
@node editable-field
@subsection The @code{editable-field} Widget
@findex editable-field@r{ widget}
Syntax:
@example
@var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
A widget that can be edited by the user. Its super is the
@code{default} widget.
The @var{value}, if present, is used to initialize the @code{:value}
property. The value should be a string, which will be inserted in the
field. If not present, @code{:value} is the empty string.
@strong{Warning:} In an @code{editable-field} widget, the editable
field must not be adjacent to another widget---that won't work.
You must put some text in between. Either make this text part of
the @code{editable-field} widget itself, or insert it with
@code{widget-insert}.
This widget either overrides or adds the following properties:
@table @code
@item :convert-widget
Just like the @code{item} widget, this function allows it to
initialize @code{:value} from @var{value}.
@vindex keymap@r{ keyword}
@vindex widget-field-keymap
@item :keymap
Keymap used in the editable field.
The default value is @code{widget-field-keymap}, which allows the user
to use all the normal editing commands, even if the buffer's major
mode suppresses some of them. Pressing @key{RET} invokes the function
specified by @code{:action}.
@item :format
By default, it specifies to insert only the widget's value.
@strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
must be preceded by some other text in the @code{:format} string (if
specified).
@vindex size@r{ keyword}
@item :size
The width of the editable field.
By default the field will reach to the end of the line.
@vindex value-face@r{ keyword}
@item :value-face
Face used for highlighting the editable field.
Default is @code{widget-field-face}, @pxref{User Interface}.
@vindex secret@r{ keyword}
@item :secret
Character used to display the value.
You can set this to, e.g., @code{?*} if the field contains a password
or other secret information. By default, this is @code{nil}, and the
value is not secret.
@vindex valid-regexp@r{ keyword}
@item :valid-regexp
By default the @code{:validate} function will match the content of the
field with the value of this attribute.
The default value is @code{""} which matches everything.
@item :validate
Returns @code{nil} if the current value of the widget matches the
@code{:valid-regexp} value.
@item :prompt-internal
A function to read a value for widget, used by the
@code{:prompt-value} function.
@item :prompt-history
A variable that holds the history of field minibuffer edits.
@item :prompt-value
A function that uses the @code{:prompt-internal} function and the
@code{:prompt-history} value to prompt for a string, and return the
user response in the external format.
@item :action
When invoked, moves point to the next field.
@item :value-create
Function that takes care of creating the widget, respecting its
@code{:size} and @code{:value}.
@item :value-set
Function to use to modify programmatically the current value of the
widget.
@item :value-delete
Function that removes the widget so it cannot be edited anymore.
@item :value-get
Function to return the current text in the widget.
It takes an optional argument, @var{no-truncate}. If
@var{no-truncate} is nil, truncates trailing spaces.
@item :match
Function that makes the widget match any string value.
@end table
@node text
@subsection The @code{text} Widget
@findex text@r{ widget}
Syntax:
@example
@var{type} ::= (text [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
A widget just like the @code{editable-field} widget, but intended for
multiline text fields. Its super is the @code{editable-field} widget.
It overrides the following properties:
@table @code
@item :format
By default, prints a tag and the value.
@vindex widget-text-keymap
@item :keymap
The default is @code{widget-text-keymap}, which does not rebind the
@key{RET} key.
@end table
@node menu-choice
@subsection The @code{menu-choice} Widget
@findex menu-choice@r{ widget}
Syntax:
@example
@var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
@end example
A widget to represent a menu of options. Its super is the
@code{default} widget.
The @var{type} argument represents each possible choice. The widget's
value will be that of the chosen @var{type} argument.
It either overrides or adds the following properties:
@table @code
@item :convert-widget
A function that takes care of converting each possible choice.
@item :copy
A function to copy each possible choice.
@item :format
By default, buttonize the tag and show the value.
@vindex void@r{ keyword}
@item :void
Widget type used as a fallback when the value does not match any of the
specified @var{type} arguments.
By default this is an @code{item} widget.
@vindex case-fold@r{ keyword}
@item :case-fold
If @code{nil} don't ignore case when prompting for a choice through
the minibuffer.
By default, its value is @code{t}.
@vindex children@r{ keyword}
@item :children
A list whose @sc{car} is the widget representing the currently chosen
type in the buffer.
@vindex choice@r{ keyword}
@item :choice
The current chosen type.
@vindex args@r{ keyword}
@item :args
The list of types.
@item :value-create
The function that inserts the current value for the widget.
It inserts the first choice that matches, as with the @code{:match}
function, the value of the widget.
@item :value-get
Returns the value of the first child for the widget (see the
description for @code{:children} above).
@item :value-inline
Returns the inline value of the first child for the widget.
@item :default-get
The default value for this widget is the default value for the first
choice, in case @code{:value} is missing.
This means that if you want a specific default value for the
@code{menu-choice} widget, you should either pass a @code{:value}
property when creating it, or arrange the choices so that the first
one can hold your desired default value.
@item :mouse-down-action
A function that takes care of showing a menu, if possible and desired.
@item :action
A function that takes care of getting a new choice for the widget.
Depending on the number of choices available, it may show a menu or
just toggle the choices, or even do nothing at all.
After getting the choice, it recreates the widget and notifies it.
@item :validate
Returns @code{nil} if the widget's value is a valid choice.
@item :match
This widget will match any value matching at least one of the
specified @var{type} arguments.
@item :match-inline
A function that returns non-@code{nil} if the values match the widget,
taking into account the @code{:inline} property.
@end table
@node radio-button-choice
@subsection The @code{radio-button-choice} Widget
@findex radio-button-choice@r{ widget}
Syntax:
@example
@var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]... @var{type} ... )
@end example
A widget to represent a choice from multiple options. Its super is
the @code{default} widget.
The component @var{types} specify the choices, with one radio button for
each. The widget's value will be that of the chosen @var{type}
argument.
It overrides the following properties:
@table @code
@item :convert-widget
As other composite widgets, a function that takes care of converting
each available choice.
@item :copy
A function to copy each available choice.
@item :action
A function that checks if any radio button was pressed and activates
the pressed one, possibly deactivating an old one. Then, it notifies
itself.
@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
@table @samp
@item %v
Replace with the buffer representation of the @var{type} widget.
@item %b
Replace with the radio button.
@item %%
Insert a literal @samp{%}.
@end table
@item :format
By default, it inserts its value.
@vindex button-args@r{ keyword}
@item :button-args
A list of keywords to pass to the radio buttons. Useful for setting,
e.g., the @samp{:help-echo} for each button.
@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the radio buttons.
@vindex children@r{ keyword}
@item :children
The widgets representing each type.
@vindex choice@r{ keyword}
@item :choice
The current chosen type.
@vindex args@r{ keyword}
@item :args
The list of types.
@item :value-create
A function to insert all available choices.
@item :value-get
Returns the value for the chosen widget.
@item :value-set
A function to set the value to one of its available options.
@item :value-inline
A function that returns the inline value of the child widget.
@item :offset
By default, this widget has an offset of 4.
@item :validate
The widget validates if the current value is valid for one of its
children.
@item :match
This widget matches any value that matches at least one of
the specified @var{type} arguments.
@item :match-inline
Like the @code{:match} function, but taking into account inline
values.
@end table
You can add extra radio button items to a @code{radio-button-choice}
widget after it has been created with the function
@code{widget-radio-add-item}.
@defun widget-radio-add-item widget type
Add to @code{radio-button-choice} widget @var{widget} a new radio button
item of type @var{type}.
@end defun
Please note that such items added after the @code{radio-button-choice}
widget has been created will @strong{not} be properly destructed when
you call @code{widget-delete}.
@node choice-item
@subsection The @code{choice-item} Widget
@findex choice-item@r{ widget}
Syntax:
@example
@var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{value})
@end example
A widget to represent a choice in a @code{menu-choice} widget. Its
super is the @code{item} widget.
The @var{value}, if present, is used to initialize the @code{:value}
property.
It overrides the following properties:
@table @code
@item :action
Activating the button of a @code{choice-item} is equivalent to
activating the parent widget.
@item :format
By default, it buttonizes the tag (i.e., its value) and adds a newline
character at the end of the widget.
@end table
@node toggle
@subsection The @code{toggle} Widget
@findex toggle@r{ widget}
Syntax:
@example
@var{type} ::= (toggle [@var{keyword} @var{argument}]...)
@end example
A widget that can toggle between two states. Its super is the
@code{item} widget.
The widget has two possible states, @samp{on} and @samp{off}, which
correspond to a @code{t} or @code{nil} value, respectively.
@noindent
Example:
@lisp
@group
(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")
@end group
@group
(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)))
@end group
@end lisp
It either overrides or adds the following properties:
@table @code
@item :format
By default, it buttonizes the value and adds a newline at the end of
the widget.
@item :on
A string representing the @samp{on} state. By default the string
@samp{on}.
@item :off
A string representing the @samp{off} state. By default the string
@samp{off}.
@vindex on-glyph@r{ keyword}
@item :on-glyph
Name of a glyph to be used instead of the @samp{:on} text string, on
emacsen that supports this.
@vindex off-glyph@r{ keyword}
@item :off-glyph
Name of a glyph to be used instead of the @samp{:off} text string, on
emacsen that supports this.
@item :value-create
A function for creating the widget's value, according to its
@samp{:on} or @samp{:off} state.
@item :action
Function to toggle the state of the widget. After toggling, it
notifies itself.
@item :match
This widget matches anything.
@end table
@node radio-button-toggle
@subsection The @code{radio-button-toggle} Widget
@findex radio-button-toggle@r{ widget}
Syntax:
@example
@var{type} ::= (radio-button-toggle [@var{keyword} @var{argument}]...)
@end example
A toggle to use in the @code{radio} widget.
It overrides the following properties:
@table @code
@item :button-prefix
The empty string.
@item :button-suffix
The empty string.
@item :on
The string ``(*)'', to represent the @samp{on} state.
@item :off
The string ``( )'', to represent the @samp{off} state.
@item :on-glyph
The name of an image to represent the @samp{on} state.
@item :off-glpyh
The name of an image to represent the @samp{off} state.
@item :format
By default, it buttonizes its value.
@item :notify
A function to notify its parent.
@end table
@node checkbox
@subsection The @code{checkbox} Widget
@findex checkbox@r{ widget}
Syntax:
@example
@var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
@end example
A widget to represent a toggle widget, with a checkbox. Its super is
the @code{toggle} widget.
This widget has two possible states, @samp{selected} and
@samp{unselected}, which corresponds to a @code{t} or @code{nil}
value, respectively.
It either overrides or adds the following properties:
@table @code
@item :button-prefix
The empty string.
@item :button-suffix
The empty string.
@item :format
By default, buttonizes the value.
@item :on
By default, the string ``[X]''.
@item :off
By default, the string ``[ ]''.
@item :on-glyph
The name of the image to use when the state is @samp{on}.
@item :off-glyph
The name of the image to use when the state is @samp{off}.
@item :action
A function that toggles the checkbox, notifies the parents and in the
@samp{on} state, activates its siblings.
@end table
@node checklist
@subsection The @code{checklist} Widget
@findex checklist@r{ widget}
Syntax:
@example
@var{type} ::= (checklist [@var{keyword} @var{argument}]... @var{type} ... )
@end example
A widget to represent a multiplice choice. Its super is the
@code{default} widget.
The @var{type} arguments represent each checklist item. The widget's
value will be a list containing the values of all checked @var{type}
arguments.
@noindent
Example:
@lisp
(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))))
@end lisp
It either overrides or adds the following properties:
@table @code
@item :convert-widget
As other composite widgets, a function that takes care of converting
each checklist item.
@item :copy
A function to copy each checklist item.
@item :format
By default, it inserts its value.
@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
@table @samp
@item %v
Replaced with the buffer representation of the @var{type} widget.
@item %b
Replace with the checkbox.
@item %%
Insert a literal @samp{%}.
@end table
@vindex button-args@r{ keyword}
@item :button-args
A list of keywords to pass to the checkboxes. Useful for setting,
e.g., the @samp{:help-echo} for each checkbox.
@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the checkboxes.
@vindex children@r{ keyword}
@item :children
The widgets representing each type.
@vindex args@r{ keyword}
@item :args
The list of types.
@item :value-create
The function that takes care of inserting all values.
@item :value-get
A function that returns all values of selected items.
@item :validate
A function that ensures all selected children are valid.
@item :match
The checklist widget will match a list whose elements all
match at least one of the specified @var{type} arguments.
@item :match-inline
Like the @code{:match} function, but taking into account the
@code{:inline} property.
@vindex greedy@r{ keyword}
@item :greedy
Usually a checklist will only match if the items are in the exact
sequence given in the specification. By setting @code{:greedy} to
non-@code{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.
@end table
@node editable-list
@subsection The @code{editable-list} Widget
@findex editable-list@r{ widget}
Syntax:
@example
@var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{type})
@end example
A widget that can hold a variable list of widgets of the same type,
represented by @var{type}. Its super is the @code{default} widget.
It either overrides or adds the following properties:
@table @code
@item :convert-widget
As other composite widgets, a function that takes care of converting
each type in @var{type}.
@item :copy
A function to copy the types given in @var{type}.
@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
@table @samp
@item %v
This will be replaced with the buffer representation of the @var{type}
widget.
@item %i
Insert the @b{[INS]} button, a widget of type @code{insert-button}.
@item %d
Insert the @b{[DEL]} button, a widget of type @code{delete-button}.
@item %%
Insert a literal @samp{%}.
@end table
@vindex insert-button-args@r{ keyword}
@item :insert-button-args
A list of keyword arguments to pass to the insert buttons.
@vindex delete-button-args@r{ keyword}
@item :delete-button-args
A list of keyword arguments to pass to the delete buttons.
@vindex append-button-args@r{ keyword}
@item :append-button-args
A list of keyword arguments to pass to the trailing insert button.
@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the insert and delete buttons.
@item :format
By default, insert its value and at the and adds an insert button.
This is useful so that new elements can be added to the list upon user
request.
@item :format-handler
A function that recognize the escape for inserting an insert button.
@item :offset
By default, this widget has an offset of 12.
@vindex children@r{ keyword}
@item :children
The widgets representing the elements of the list.
@vindex args@r{ keyword}
@item :args
List whose @sc{car} is the type of the list elements.
@item :insert-before
Function to insert a new widget as a child of the @code{editable-list}
widget.
This function inserts a recently deleted child, if there is one. That
is useful, so that the user can move elements in a list easily. If
there is not a recently deleted child, it inserts a child with its
default value.
@item :delete-at
Function to delete a child from the widget, and store it into the
@code{:last-deleted} list, so that it can be reinserted when the
@code{:insert-before} function executes.
@item :value-create
The function that takes care of inserting all values.
@item :value-get
Function that returns a list with the value of the child widgets.
@item :validate
This widget validates if all children validate.
@item :match
To match, the value must be a list and all the list members must match
the specified @var{type}.
@item :match-inline
Like the @code{:match} function, but taking into account inline
values and widgets.
@end table
@node group
@subsection The @code{group} Widget
@findex group@r{ widget}
Syntax:
@example
@var{type} ::= (group [@var{keyword} @var{argument}]... @var{type}...)
@end example
A widget to group other widgets. Its super is the @code{default}
widget.
Its value is a list, with one member for each @var{type}.
It overrides the following properties:
@table @code
@item :convert-widget
As other composite widgets, a function that takes care of converting
each widget in @var{type}.
@item :copy
A function to copy the types given in @var{type}.
@item :format
By default, displays a newline character and its value.
@item :value-create
A function to create each of its components.
@item :value-get
The same function used by the @code{editable-list} widget.
@item :default-get
A function that returns a list whose members are the default values of
each widget it groups.
@item :validate
This widget validates if all of its children validate.
@item :match
This widget matches a value that matches each of its components.
@item :match-inline
As @code{:match}, but taking into account widgets and values that are
inline.
@end table
@node documentation-string
@subsection The @code{documentation-string} Widget
@findex documentation-string@r{ widget}
Syntax:
@example
@var{type} ::= (documentation-string [@var{keyword} @var{argument}]... @var{value})
@end example
A widget to represent a documentation string. Its super is the
@code{item} widget.
It either overrides or adds the following properties:
@table @code
@item :format
By default, insert its value.
@item :value-create
Function to insert a documentation string, possibly hiding part of the
documentation if its large.
To show or hide the rest of the documentation, uses a
@code{visibility} widget.
@item :action
Function to toggle showing the documentation upon an event.
@item :visibility-widget
A symbol, the type of the widget to use for the visibility widget.
This is, by default, the symbol @code{visibility}.
@end table
@node Sexp Types
@section Sexp Types
@cindex sexp types
A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp
for short, are also available. These basically fall in several
categories described in this section.
@menu
* constants::
* generic::
* atoms::
* composite::
@end menu
@node constants
@subsection The Constant Widgets
@cindex constant widgets
The @code{const} widget can contain any Lisp expression, but the user is
prohibited from editing it, which is mainly useful as a component of one
of the composite widgets.
The syntax for the @code{const} widget is:
@example
@var{type} ::= (const [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
Its super is the @code{item} widget. The @var{value}, if present, is
used to initialize the @code{:value} property and can be any
s-expression.
@deffn Widget const
This will display any valid s-expression in an immutable part of the
buffer.
It overrides the @code{:prompt-value} function, to avoid prompting and
just return the widget's value.
@end deffn
There are two variations of the @code{const} widget, namely
@code{variable-item} and @code{function-item}. These should contain a
symbol with a variable or function binding, respectively. The major
difference from the @code{const} widget is that they will allow the
user to see the variable or function documentation for the symbol.
This is accomplished via using the @samp{%h} format escape, and adding
an appropriate @code{:documentation-property} function for each widget.
@deffn Widget variable-item
An immutable symbol that is bound as a variable.
@end deffn
@deffn Widget function-item
An immutable symbol that is bound as a function.
@end deffn
@node generic
@subsection Generic Sexp Widget
@cindex generic sexp widget
The @code{sexp} widget can contain any Lisp expression, and allows the
user to edit it inline in the buffer.
The syntax for the @code{sexp} widget is:
@example
@var{type} ::= (sexp [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
@deffn Widget sexp
This widget represents an editable field that's useful to edit any
valid s-expression.
The @code{sexp} widget takes the same keyword arguments as the
@code{editable-field} widget. @xref{editable-field}.
Its default value is @code{nil}.
@end deffn
@deffn Widget restricted-sexp
A widget to edit Lisp expressions restricted to certain values or
types. Its super is the @code{sexp} widget.
It works just like the sexp widget, but it overrides the @code{:match}
function to match for certain values. To use this widget, either you
must define a @code{:match} function or give a
@code{:match-alternatives} property. The @code{:match-alternatives}
property holds a list of predicate functions to call when checking if
a given value matches the widget. Each predicate function will be
called with one argument, the value to be matched, and should return
non-@code{nil} on success.
As an example, the @code{integer} widget overrides
@code{:match-alternatives} to @code{(integerp)}.
@end deffn
@node atoms
@subsection Atomic Sexp Widgets
@cindex atomic sexp widget
The atoms are s-expressions that do not consist of other s-expressions.
For example, a string, a file name, or a symbol are atoms, while a list
is a composite type. You can edit the value of an atom with the
widgets described in this section.
The syntax for all the atoms is:
@example
@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
The @var{value}, if present, is used to initialize the @code{:value}
property and must be an expression of the same type as the widget.
That is, for example, the string widget can only be initialized with a
string.
All the atom widgets take the same keyword arguments as the
@code{editable-field} widget. @xref{editable-field}.
@deffn Widget string
An editable field widget that can represent any Lisp string.
It offers completion via the ispell library and the @code{:complete}
property.
@end deffn
@deffn Widget regexp
An editable field widget that can represent a regular expression.
Overrides the @code{:match} and the @code{:validate} properties to
check that the value is a valid regexp.
@end deffn
@deffn Widget character
An editable field widget that can represent a character.
The character widget represents some characters (like the newline
character) in a special manner, to make it easier for the user to see
what's the content of the character field.
@end deffn
@deffn Widget file
A widget for editing file names.
Keywords:
@table @code
@item :completions
Offers file name completion to the user.
@item :prompt-value
A function to read a file name from the minibuffer.
@vindex must-match@r{ keyword}
@item :must-match
If this is set to non-@code{nil}, only existing file names are allowed
when prompting for a value in the minibuffer.
@item :match
The widget matches if the value is a string, and the file whose name
is that string is an existing file, or if @code{:must-match} is
@code{nil}.
@item :validate
The widget is valid if its value matches.
@end table
@end deffn
@deffn Widget directory
A widget for editing directory names.
Its super is the @code{file} widget, and it overrides the
@code{:completions} property, to offer completions only for
directories.
@end deffn
@deffn Widget symbol
A widget for editing a Lisp symbol.
Its value by default is @code{nil}.
@end deffn
@deffn Widget function
A widget for editing a lambda expression, or a function name, offering
completion. Its super is the @code{restricted-sexp} widget.
@end deffn
@deffn Widget variable
A widget for editing variable names, offering completion. Its super
is the @code{symbol} widget.
@end deffn
@deffn Widget integer
A widget for editing integers in an editable field. Its super is the
@code{restricted-sexp} widget.
It has a default @code{:value} of 0.
@end deffn
@deffn Widget natnum
A widget for editing non-negative integers. Its super is the
@code{restricted-sexp} widget.
It has a default @code{:value} of 0.
@end deffn
@deffn Widget float
A widget for editing a floating point number. Its super is the
@code{restricted-sexp} widget.
It has a default @code{:value} of 0.0.
@end deffn
@deffn Widget number
A widget for editing a number, either floating point or integer. Its
super is the @code{restricted-sexp} widget.
It has a default @code{:value} of 0.0.
@end deffn
@deffn Widget boolean
A widget for editing a boolean value. Its super is the @code{toggle}
widget.
Its value may be @code{nil}, meaning false, or non-@code{nil}, meaning
true.
@end deffn
@deffn Widget color
A widget to edit a color name.
In addition, shows a sample that shows the selected color, if any.
@end deffn
@deffn Widget other
A widget useful as the last item in a @code{choice} widget, since it
matches any value.
Its super is the @code{sexp} widget, and its @code{:value} is
@code{other}, by default.
@end deffn
@deffn Widget coding-system
A widget that can represent a coding system name, offering
completions. @xref{Coding Systems,,,elisp, the Emacs Lisp Reference
Manual}. Its super is the @code{symbol} widget.
It has a default value of @code{undecided}.
@end deffn
@deffn Widget key
A widget to represent a key sequence.
It uses a special keymap as the @code{:keymap}.
@end deffn
@node composite
@subsection Composite Sexp Widgets
@cindex composite sexp widgets
The syntax for the composite widget construct is:
@example
@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... @var{component}...)
@end example
@noindent
where each @var{component} must be a widget type. Each component widget
will be displayed in the buffer, and will be editable by the user.
@deffn Widget cons
A widget to edit cons-cell values. Its super is the @code{group}
widget.
The value of a @code{cons} widget must be a cons-cell whose @sc{car}
and @sc{cdr} have two specified types. It uses this syntax:
@example
@var{type} ::= (cons [@var{keyword} @var{argument}]... @var{car-type} @var{cdr-type})
@end example
@end deffn
@deffn Widget choice
A widget to hold a value of one of a fixed set of types. Its super is
the @code{menu-choice} widget.
The widget's syntax is as follows:
@example
@var{type} ::= (choice [@var{keyword} @var{argument}]... @var{type} ... )
@end example
The value of a @code{choice} widget can be anything that matches any of the
@var{types}.
This widget only displays the widget that corresponds to the current
choice.
@end deffn
@deffn Widget radio
A widget to hold a value of one of a fixed set of options. Its super is
the @code{radio-button-choice} widget.
@end deffn
@deffn Widget list
A widget to edit a list value. Its super is the @code{group} widget.
The value of a @code{list} widget must be a list whose element types
match the specified component types:
@example
@var{type} ::= (list [@var{keyword} @var{argument}]... @var{component-type}...)
@end example
Thus, for example, @code{(list string number)} matches lists of two
elements, the first being a string and the second being a number.
@end deffn
@deffn Widget vector
A widget to edit a vector value. Its super is the @code{group}
widget.
The @code{vector} widget is like the @code{list} widget but matches
vectors instead of lists. Thus, for example, @code{(vector string
number)} matches vectors of two elements, the first being a string and
the second being a number.
@end deffn
The above suffice for specifying fixed size lists and vectors. To get
variable length lists and vectors, you can use a @code{choice},
@code{set}, or @code{repeat} widget together with the @code{:inline}
keyword. If any component of a composite widget has the
@code{:inline} keyword set, its value must be a list which will then
be spliced into the composite. For example, to specify a list whose
first element must be a file name, and whose remaining elements should
either be the symbol @code{t} or two strings (file names), you can use
the following widget specification:
@example
(list file
(choice (const t)
(list :inline t
:value ("foo" "bar")
string string)))
@end example
The value of a widget of this type will either have the form
@code{(file t)} or @code{(file @var{string} @var{string})}.
This concept of @code{:inline} may be hard to understand. It was
certainly hard to implement, so instead of confusing you more by
trying to explain it here, I'll just suggest you meditate over it for
a while.
@deffn Widget set
A widget to hold a list of members from a fixed set. Its super is the
@code{checklist} widget.
Its value is a list where the elements all belong to a given set. The
order of elements of the list is not significant.
Here's the syntax:
@example
@var{type} ::= (set [@var{keyword} @var{argument}]... @var{permitted-element} ... )
@end example
Use @code{const} to specify each permitted element, like this:
@code{(set (const a) (const b))}.
@end deffn
@deffn Widget repeat
Specifies a list of any number of elements that fit a certain type.
Its super is the @code{editable-list} widget.
@example
@var{type} ::= (repeat [@var{keyword} @var{argument}]... @var{type})
@end example
@end deffn
@deffn Widget plist
A widget to edit property lists. Its super is the @code{list} widget.
It recognizes the following properties:
@table @code
@item :options
A given set of recommended key-value values for the @code{plist}
widget. Each option shows up as a checklist item.
@item :key-type
The widget type to use for the plist keys. By default, it uses the
@code{symbol} widget.
@item :value-type
The widget type to use for the plist values. By default, it uses the
@code{sexp} widget.
@end table
@end deffn
@deffn Widget alist
A widget to edit association lists. Its super is the @code{list}
widget.
It recognizes the same properties that the @code{plist} widget, with
the difference that the @code{:key-type} uses by default a @code{sexp}
widget.
@end deffn
Most composite widgets do not allow for recursion. That is, none of
the contained widgets may be of the same type that is currently being
defined. To allow for this kind of widgets, there's the @code{lazy}
widget.
@deffn Widget lazy
A base widget for recursive data structures. Its super is the
@code{default} widget.
When instantiated, it contains a single inferior widget of the widget
type specified in the @code{:type} property. Its value is the same as
the value of this inferior widget.
@end deffn
@node Defining New Widgets
@chapter Defining New Widgets
@cindex new widgets
@cindex defining new widgets
You can define specialized widgets with @code{define-widget}. It allows
you to create a shorthand for more complex widgets, including specifying
component widgets and new default values for the keyword arguments.
@defun define-widget name class doc &rest args
Define a new widget type named @var{name} that derives from @var{class}.
@var{name} and @var{class} should both be symbols, and @var{class}
should be one of the existing widget types.
The third argument @var{doc} is a documentation string for the widget.
@var{args} should be key-value pairs, overriding keyword values of
@var{class}, or adding new recognized keywords for @var{name}.
Usually, you'll want to derive from an existing widget type, like the
@code{editable-field} widget, or the @code{default} widget, but it's
also possible to derive from nothing, by passing a value of @code{nil}
as @var{class}. Note that if you do this, you're entirely responsible
for defining a whole new default behavior for your widgets.
After using this function, the following two calls will create
identical widgets:
@itemize @bullet
@item
@lisp
(widget-create @var{name})
@end lisp
@item
@lisp
(apply widget-create @var{class} @var{args})
@end lisp
@end itemize
@end defun
Using @code{define-widget} just stores the definition of the widget type
in the @code{widget-type} property of @var{name}, which is what
@code{widget-create} uses.
If you only want to specify defaults for keywords with no complex
conversions, you can use @code{identity} as your conversion function.
When defining new widgets, the @code{:convert-widget} property might
be useful:
@table @code
@vindex convert-widget@r{ keyword}
@item :convert-widget
Function to convert a widget type before creating a widget of that
type.
It takes a widget type as an argument, and returns the converted
widget type. When a widget is created, this function is called for
the widget type and all the widget's parent types, most derived first.
The predefined functions @code{widget-types-convert-widget} and
@code{widget-value-convert-widget} can be used here.
@end table
@noindent
Example:
@lisp
@group
(defvar widget-ranged-integer-map
(let ((map (copy-keymap widget-keymap)))
(define-key map [up] #'widget-ranged-integer-increase)
(define-key map [down] #'widget-ranged-integer-decrease)
map))
@end group
@group
(define-widget 'ranged-integer 'integer
"A ranged integer widget."
:min-value most-negative-fixnum
:max-value most-positive-fixnum
:keymap widget-ranged-integer-map)
@end group
@group
(defun widget-ranged-integer-change (widget how)
"Change the value of the ranged-integer WIDGET, according to HOW."
(let* ((value (widget-value widget))
(newval (cond
((eq how 'up)
(if (< (1+ value) (widget-get widget :max-value))
(1+ value)
(widget-get widget :max-value)))
((eq how 'down)
(if (> (1- value) (widget-get widget :min-value))
(1- value)
(widget-get widget :min-value)))
(t (error "HOW has a bad value"))))
(inhibit-read-only t))
(widget-value-set widget newval)))
@end group
@group
(defun widget-ranged-integer-increase (widget)
"Increase the value of the ranged-integer WIDGET."
(interactive (list (widget-at)))
(widget-ranged-integer-change widget 'up))
@end group
@group
(defun widget-ranged-integer-decrease (widget)
"Decrease the value of the ranged-integer WIDGET."
(interactive (list (widget-at)))
(widget-ranged-integer-change widget 'down))
@end group
@end lisp
@node Inspecting Widgets
@chapter Inspecting Widgets
@cindex widget browser
There is a separate package to browse widgets, in
@samp{wid-browse.el}. This is intended to help programmers who want
to examine the content of a widget. The browser shows the value of
each keyword, but uses links for certain keywords such as
@samp{:parent}, which avoids printing cyclic structures.
@deffn Command widget-browse @var{widget}
Create a widget browser for @var{widget}.
When called interactively, prompt for @var{widget}.
@end deffn
@deffn Command widget-browse-other-window @var{widget}
Create a widget browser for @var{widget} and show it in another window.
When called interactively, prompt for @var{widget}.
@end deffn
@deffn Command widget-browse-at @var{pos}
Create a widget browser for the widget at @var{pos}.
When called interactively, use the position of point.
@end deffn
In addition, there's a function to describe the widget at point.
@deffn Command widget-describe &optional widget-or-pos
Describe the widget at point.
When called from Lisp, @var{widget-or-pos} might be the widget to
describe or a buffer position where a widget is present. If
@var{widget-or-pos} is @code{nil}, the widget to describe is the
widget at point.
This command sets up a help buffer for providing information about the
widget, mainly its @code{:action} and @code{:mouse-down-action}
functions, and provides links to describe it in more detail using the
@code{widget-browse} commands described above.
@end deffn
@node Widget Minor Mode
@chapter Widget Minor Mode
@cindex widget minor mode
There is a minor mode for manipulating widgets in major modes that
don't provide any support for widgets themselves. This is mostly
intended to be useful for programmers doing experiments.
@deffn Command widget-minor-mode
Toggle minor mode for traversing widgets.
With arg, turn widget mode on if and only if arg is positive.
@end deffn
@defvar widget-minor-mode-keymap
Keymap used in @code{widget-minor-mode}.
@end defvar
@node Utilities
@chapter Utilities
@cindex utility functions for widgets
Here we describe some utility functions that don't really have a place
earlier in this manual.
@defun widget-prompt-value widget prompt [ value unbound ]
Prompt for a value matching @var{widget}, using @var{prompt}.
The current value is assumed to be @var{value}, unless @var{unbound} is
non-@code{nil}.
Converts @var{widget} before prompting, and for prompting it uses the
@code{:prompt-value} function. This function returns the user
``answer'', and it's an error if that answer doesn't match the widget,
as with the @code{:match} function.
If the answer matches the widget, returns the answer.
@end defun
@defun widget-get-sibling widget
Get the item which @var{widget} should toggle.
This is only meaningful for radio buttons or checkboxes in a list.
@end defun
@defun widget-choose title items &optional event
Prompt the user to choose an item from a list of options.
@var{title} is the name of the list of options. @var{items} should be
a menu, with its items in the simple format or in the extended format.
@xref{Defining Menus,, Defining Menus, elisp, the Emacs Lisp Reference
Manual}. Independently of the format, you don't have to provide a
title for the menu, just pass the desired title in @var{title}. The
optional @var{event} is an input event. If @var{event} is a mouse
event and the number of elements in @var{items} is less than the user
option @code{widget-menu-max-size}, then @code{widget-choose} uses a
popup menu to prompt the user. Otherwise, @code{widget-choose} uses
the minibuffer.
When @var{items} is a keymap menu, the returned value is the symbol in
the key vector, as in the argument of @code{define-key}
(@pxref{Changing Key Bindings,,,elisp, the Emacs Lisp Reference
Manual}). When @var{items} is a list whose selectable items are of
the form (@var{name} . @var{value}) (i.e., the simplified format),
then the return value is the @var{value} of the chosen element.
@end defun
@defun widget-image-find image
Create a graphical button from @var{image}, an image or a file name
sans extension.
If @var{image} is a file name, the file should be in
@code{widget-image-directory}, or in a place where @code{find-image}
will find it.
@end defun
@defun widget-image-insert widget tag image
As part of @var{widget}, insert the text @var{tag} or, if supported,
the image @var{image}.
@var{image} should be as described in @code{widget-image-find}.
@end defun
@defun widget-echo-help pos
Display help-echo text for the widget at @var{pos}.
Uses the value of @code{:help-echo}. If it is a function, it calls it
to get a string. Otherwise, it @code{eval}s it.
@end defun
@node Customization
@chapter Customization
This chapter is about the customization options for the Widget
library, for the end user.
@deffn Face widget-documentation
Face used for documentation text.
@end deffn
@deffn Face widget-field
Face used for editable fields.
@end deffn
@deffn Face widget-button
Face used for buttons.
@end deffn
@deffn Face widget-button-pressed
Face used for pressed buttons.
@end deffn
@deffn Face widget-inactive
Face used for inactive widgets.
@end deffn
@defopt widget-mouse-face
Face used for highlighting a button when the mouse pointer moves
across it.
The default value is @code{highlight}.
@end defopt
@defopt widget-image-directory
Directory where Widget should look for images.
Widget will look here for a file with the same name as specified for the
image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
@end defopt
@defopt widget-image-enable
If non-@code{nil}, allow images to appear on displays where they are supported.
@end defopt
@defopt widget-image-conversion
An alist to convert symbols from image formats to file name suffixes.
Each element is a cons cell (@var{format} . @var{suffix}), where
@var{format} is a symbol that represents an image format and
@var{suffix} is its correspondent suffix.
@end defopt
@defopt widget-button-prefix
String to prefix buttons.
@end defopt
@defopt widget-button-suffix
String to suffix buttons.
@end defopt
@defopt widget-push-button-prefix
String to prefix push buttons.
@end defopt
@defopt widget-push-button-suffix
String to suffix push buttons.
@end defopt
@defopt widget-link-prefix
String to prefix links.
@end defopt
@defopt widget-link-suffix
String to suffix links.
@end defopt
@defopt widget-choice-toggle
If non-@code{nil}, toggle when there are just two options.
By default, its value is @code{nil}.
@end defopt
@defopt widget-skip-inactive
If non-@code{nil}, skip over inactive widgets when using @kbd{@key{TAB}}
(@code{widget-forward}) or @kbd{S-@key{TAB}} (@code{widget-backward},
also bound to @kbd{M-@key{TAB}}) to navigate between widgets.
By default, its value is @code{nil} and tabbing does not skip over
inactive widgets.
@end defopt
@defopt widget-documentation-links
If non-@code{nil}, add hyperlinks to documentation strings.
@end defopt
@defopt widget-documentation-link-regexp
A regexp that matches potential links in documentation strings. The
link itself should match to the first group.
@end defopt
@defopt widget-documentation-link-p
A predicate function to test if a string is useful as a link. The
function is called with one argument, a string, and should return
non-@code{nil} if there should be a link for that string.
By default, the value is @code{intern-soft}.
@end defopt
@defopt widget-documentation-link-type
A symbol that represents a widget type to use for links in
documentation strings.
By default, the value is @code{documentation-link}.
@end defopt
@defopt widget-menu-max-size
Maximum size for a popup menu. By default, its value is 40.
If a function ask you to choose from a menu that is larger than this
value, it will use the minibuffer.
@end defopt
@defopt widget-menu-max-shortcuts
Largest number of items for which it works to choose one with a
character.
For a larger number, use the minibuffer.
@end defopt
@defopt widget-menu-minibuffer-flag
Whether to use the minibuffer to ask for a choice.
If @code{nil}, the default, read a single character.
@end defopt
@node Widget Wishlist
@chapter Wishlist
@cindex todo
@itemize @bullet
@item
It should be possible to add or remove items from a list with @kbd{C-k}
and @kbd{C-o} (suggested by @sc{rms}).
@item
The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
dash (@samp{-}). The dash should be a button that, when invoked, asks
whether you want to add or delete an item (@sc{rms} wanted to git rid of
the ugly buttons, the dash is my idea).
@item
The @code{menu-choice} tag should be prettier, something like the abbreviated
menus in Open Look.
@item
Finish @code{:tab-order}.
@item
Make indentation work with glyphs and proportional fonts.
@item
Add commands to show overview of object and class hierarchies to the
browser.
@item
Find a way to disable mouse highlight for inactive widgets.
@item
Find a way to make glyphs look inactive.
@item
Add @code{widget} widget for editing widget specifications.
@item
Find clean way to implement variable length list.
See @code{TeX-printer-list} for an explanation.
@item
@kbd{C-h} in @code{widget-prompt-value} should give type specific help.
@item
Add a @code{mailto} widget.
@end itemize
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Index
@unnumbered Index
This is an alphabetical listing of all concepts, functions, commands,
variables, and widgets described in this manual.
@printindex cp
@bye
Reference in New Issue View Git Blame Copy Permalink