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.
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 default
widget. In this manual, when we talk about a default behavior, we
usually mean the behavior as defined by this default widget.
See 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.
One important property of a widget is its value. All widgets may have a value, which is stored in a so-called internal format. For the rest of Emacs, the widget presents its value in a so-called external format. Both formats can be equal or different, and each widget is responsible for defining how the conversion between each format should happen.
The value property is an important property for almost all widgets,
and perhaps more important for 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.
Important: You must call widget-setup after
modifying the value of a widget before the user is allowed to edit the
widget again. It is enough to call 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.
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 widget-put and widget-get functions. The
property names, as shown, are keywords, so they must begin with a
‘:’.