1.0 Introduction

Most graphical user interface toolkits provide a number of standard user interface controls (sometimes known as `widgets' or `gadgets'). Historically, Emacs didn't support anything like this, except for its incredible powerful text "widget". However, since XEmacs 21.4, XEmacs has supported "native" widgets (GUI controls implemented as Lisp APIs in C for the MS Windows, Motif, Athena, and GTK toolkits) and libglade (GUI controls with an XML API for the GTK toolkit). On the other hand, Emacs does provide the necessary primitives to implement many other widgets within a text buffer, and of course this is the only way to implement self-contained controls in a text terminal. The widget package simplifies this task.

Examples of some basic widgets include:

link

Areas of text with an associated action. Intended for hypertext links embedded in text.

push-button

Like link, but intended for stand-alone buttons.

editable-field

An editable text field. It can be either variable or fixed length.

menu-choice

Allows the user to choose one of multiple options from a menu, each option is itself a widget. Only the selected option will be visible in the buffer.

radio-button-choice

Allows the user to choose one of multiple options by activating radio buttons. The options are implemented as widgets. All options will be visible in the buffer.

item

A simple constant widget intended to be used in the menu-choice and radio-button-choice widgets.

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.

toggle

A simple `on'/`off' switch.

checkbox

A checkbox (`[ ]'/`[X]').

editable-list

Create an editable list. The user can insert or delete items in the list. Each list item is itself a widget.

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 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 `forms' package (of course), the customize buffers, the mail and news compose modes, and the HTML form support in the `w3' browser.

The advantages for a programmer of using the widget package to implement forms are:

1. More complex fields than just editable text are supported.
2. You can give the users immediate feedback if they enter invalid data in a text field, and sometimes prevent entering invalid data.
3. You can have fixed sized fields, thus allowing multiple fields to be lined up in columns.
4. It is simple to query or set the value of a field.
5. Editing happens in a normal buffer, not in the mini-buffer.
6. Packages using the library get a uniform look-and-feel, making them easier for the user to learn.
7. 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.
8. A widget specification is implemented as a class, and new subclasses can be derived from any class, by restricting or extending the behavior.

In order to minimize the code that is loaded by users who does not create any widgets, the code has been split in two files:

`widget.el'

This declares the user variables, defines the function define-widget, and autoloads the function widget-create.

`wid-edit.el'

Everything else is here. Do not load it explicitly, as it will be autoloaded when needed.

In order to minimize the code that is loaded by users who does not create any widgets, the code has been split in two files:

`widget.el'

This will declare the user variables, define the function widget-define, and autoload the function widget-create.

`wid-edit.el'

Everything else is here, there is no reason to load it explicitly, as it will be autoloaded when needed.