-This is ../info/widget.info, produced by makeinfo version 4.0 from
+This is ../info/widget.info, produced by makeinfo version 4.6 from
widget.texi.
INFO-DIR-SECTION XEmacs Editor
* Widget Minor Mode::
* Utilities::
* Widget Wishlist::
+* Widget Internals::
\1f
File: widget.info, Node: Introduction, Next: User Interface, Prev: Top, Up: Top
Introduction
============
- Most graphical user interface toolkits, such as Motif and XView,
-provide a number of standard user interface controls (sometimes known as
+Most graphical user interface toolkits, such as Motif and XView, 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 incredible powerful text "widget". On the other
hand, Emacs does provide the necessary primitives to implement many
and `radio-button-choice' widgets.
`choice-item'
- An button item only intended for use in choices. When invoked,
- the user will be asked to select another option from the choice
- widget.
+ 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.
`widget.el'
This will declare the user variables, define the function
- `widget-define', and autoload the function `widget-create'.
+ `define-widget', and autoload the function `widget-create'.
`wid-edit.el'
Everything else is here, there is no reason to load it explicitly,
User Interface
==============
- A form consist of read only text for documentation and some fields,
-where each the fields contain two parts, as tag and a value. The tags
-are used to identify the fields, so the documentation can refer to the
-foo field, meaning the field tagged with `Foo'. Here is an example form:
+A form consists of read only text for documentation and some fields,
+where each of the fields contains two parts, a tag and a value. The
+tags are used to identify the fields, so the documentation can refer to
+the foo field, meaning the field tagged with `Foo'. Here is an example
+form:
Here is some documentation.
Editable Text Fields
--------------------
- In the example, the value for the `Name' is most likely displayed in
-an editable text field, and so are values for each of the members of
-the `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
+In the example, the value for the `Name' is most likely displayed in an
+editable text field, and so are values for each of the members of the
+`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.
Editing text fields are created by the `editable-field' widget.
Buttons
-------
- Some portions of the buffer have an associated "action", which can
-be "invoked" by a standard key or mouse command. These portions are
+Some portions of the buffer have an associated "action", which can be
+"invoked" by a standard key or mouse command. These portions are
called "buttons". The default commands for activating a button are:
`<RET>'
widget. In the example, `Choose' is an option field tag.
_The `[INS]' and `[DEL]' buttons._
- Activating these will insert or delete elements from a editable
+ Activating these will insert or delete elements from an editable
list. The list is created by the `editable-list' widget.
_Embedded Buttons._
Navigation
----------
- You can use all the normal Emacs commands to move around in a form
+You can use all the normal Emacs commands to move around in a form
buffer, plus you will have these additional commands:
`<TAB>'
Programming Example
===================
- Here is the code to implement the user interface example (see *Note
+Here is the code to implement the user interface example (see *Note
User Interface::).
(require 'widget)
Setting Up the Buffer
=====================
- Widgets are created with `widget-create', which returns a "widget"
+Widgets are created with `widget-create', which returns a "widget"
object. This object can be queried and manipulated by other widget
functions, until it is deleted with `widget-delete'. After the widgets
have been created, `widget-setup' must be called to enable them.
Basic Types
===========
- The syntax of a type specification is given below:
+The syntax of a type specification is given below:
NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
| NAME
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.
+ leading to the change, if any. In editable fields, this includes
+ all insertions, deletions, _etc_. To watch only for "final"
+ actions, redefine the `:action' callback.
`:menu-tag'
Tag used in the menu when the widget is used as an option in a
`:parent'
The parent of a nested widget (e.g. a `menu-choice' item or an
- element of a `editable-list' widget).
+ element of an `editable-list' widget).
`:sibling-args'
This keyword is only used for members of a `radio-button-choice' or
arguments, which will be used when creating the `radio-button' or
`checkbox' associated with this item.
+
- User Option: widget-glyph-directory
Directory where glyphs are found. Widget will look here for a
file with the same name as specified for the image, with either a
The `link' Widget
-----------------
- Syntax:
+Syntax:
TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ])
The `url-link' Widget
---------------------
- Syntax:
+Syntax:
TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
The `info-link' Widget
----------------------
- Syntax:
+Syntax:
TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
The `push-button' Widget
------------------------
- Syntax:
+Syntax:
TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ])
The `editable-field' Widget
---------------------------
- Syntax:
+Syntax:
TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
The `text' Widget
-----------------
- This is just like `editable-field', but intended for multiline text
+This is just like `editable-field', but intended for multiline text
fields. The default `:keymap' is `widget-text-keymap', which does not
rebind the return key.
The `menu-choice' Widget
------------------------
- Syntax:
+Syntax:
TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
The `radio-button-choice' Widget
--------------------------------
- Syntax:
+Syntax:
TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
The `item' Widget
-----------------
- Syntax:
+Syntax:
ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
The `choice-item' Widget
------------------------
- Syntax:
+Syntax:
ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
The `toggle' Widget
-------------------
- Syntax:
+Syntax:
TYPE ::= (toggle [KEYWORD ARGUMENT]...)
The `checkbox' Widget
---------------------
- The widget has two possible states, `selected' and `unselected',
-which corresponds to a `t' or `nil' value.
+The widget has two possible states, `selected' and `unselected', which
+corresponds to a `t' or `nil' value.
Syntax:
The `checklist' Widget
----------------------
- Syntax:
+Syntax:
TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
The `editable-list' Widget
--------------------------
- Syntax:
+Syntax:
TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
`:args'
List whose car is the type of the list elements.
+
\1f
File: widget.info, Node: group, Prev: editable-list, Up: Basic Types
The `group' Widget
------------------
- This widget simply group other widget together.
+This widget simply groups other widgets together.
Syntax:
Sexp Types
==========
- A number of widgets for editing s-expressions (lisp types) are also
+A number of widgets for editing s-expressions (lisp types) are also
available. These basically fall in the following categories.
* Menu:
The Constant Widgets.
---------------------
- The `const' widget can contain any lisp expression, but the user is
-prohibited from editing edit it, which is mainly useful as a component
-of one of the composite widgets.
+The `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 `const' widget is
Generic Sexp Widget.
--------------------
- The `sexp' widget can contain any lisp expression, and allows the
-user to edit it inline in the buffer.
+The `sexp' widget can contain any lisp expression, and allows the user
+to edit it inline in the buffer.
The syntax for the `sexp' widget is
Atomic Sexp Widgets.
--------------------
- The atoms are s-expressions that does not consist of other
+The atoms are s-expressions that does not consist of other
s-expressions. A string is an atom, while a list is a composite type.
You can edit the value of an atom with the following widgets.
Composite Sexp Widgets.
-----------------------
- The syntax for the composite are
+The syntax for the composite are
TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
Properties
==========
- You can examine or set the value of a widget by using the widget
-object that was returned by `widget-create'.
+You can examine or set the value of a widget by using the widget object
+that was returned by `widget-create'.
- Function: widget-value widget
Return the current value contained in WIDGET. It is an error to
Defining New Widgets
====================
- You can define specialized widgets with `define-widget'. It allows
-you to create a shorthand for more complex widgets. This includes
+You can define specialized widgets with `define-widget'. It allows you
+to create a shorthand for more complex widgets. This includes
specifying component widgets and new default values for the keyword
arguments.
- - Function: widget-define name class doc &rest args
+ - Function: define-widget name class doc &rest args
Define a new widget type named NAME from `class'.
NAME and class should both be symbols, `class' should be one of
* (apply widget-create CLASS ARGS)
- Using `widget-define' just stores the definition of the widget type
+ Using `define-widget' just stores the definition of the widget type
in the `widget-type' property of NAME, which is what `widget-create'
uses.
If you just want to specify defaults for keywords with no complex
-conversions, you can use `identity' as your conversion function.
+conversions, you can use `identity' as your `:convert-widget' function.
The following additional keyword arguments are useful when defining
new widgets:
`: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.
+ Method to convert type-specific components of a widget type before
+ instantiating a widget of that type. Not normally called from user
+ code, it is invoked by `widget-convert'. Typical operations
+ include converting types of child widgets to widget instances and
+ converting values from external format (_i.e._, as expected by the
+ calling code) to internal format (which is often different for the
+ convenience of widget manipulation). It takes a widget type as an
+ argument, and returns the converted widget type. When a widget is
+ created, the value of this property is called for the widget type,
+ then for all the widget's parent types, most derived first. (The
+ property is reevaluated for each parent type.)
The following predefined functions can be used here:
- Function: widget-types-convert-widget widget
- Convert `:args' as widget types in WIDGET.
+ Convert each member of `:args' in WIDGET from a widget type
+ to a widget.
- Function: widget-value-convert-widget widget
- Initialize `:value' from `:args' in WIDGET.
+ Initialize `:value' from `(car :args)' in WIDGET, and reset
+ `:args'.
+
+`:copy'
+ A method to implement deep copying of the type. Any member of the
+ widget which might be changed in place (rather than replaced)
+ should be copied by this method. (`widget-copy' uses
+ `copy-sequence' to ensure that the top-level list is a copy.)
+ This particularly applies to child widgets.
`:value-to-internal'
Function to convert the value to the internal format. The function
`: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.
+ argument, a widget, and inserts it in the buffer. Not normally
+ called from user code. Instead, call `widget-create' or related
+ functions, which take a type argument, (usually) convert it to a
+ widget, call the `:create' function to insert it in the buffer,
+ and then return the (possibly converted) widget.
+
+ The default, `widget-default-create', is invariably appropriate.
+ (None of the standard widgets specify `:create'.)
`:delete'
Function to delete a widget. The function takes one argument, a
`:action'
Function to handle user initiated events. By default, `:notify'
- the parent.
+ the parent. Actions normally do not include mere edits, but refer
+ to things like invoking buttons or hitting enter in an editable
+ field. To watch for any change, redefine the `:notify' callback.
The following predefined function can be used here:
It provides most of the functionality that is referred to as "by
default" in this text.
+ In implementing complex hierarchical widgets (_e.g._, using the
+`group' widget), the following functions may be useful. The syntax for
+the TYPE arguments to these functions is described in *Note Basic
+Types::.
+
+ - Function: widget-create-child-and-convert parent type &rest args
+ As a child of PARENT, create a widget with type TYPE and value
+ VALUE. TYPE is copied, and the `:widget-contvert' method is
+ applied to the optional keyword arguments from ARGS.
+
+ - Function: widget-create-child parent type
+ As a child of PARENT, create a widget with type TYPE. TYPE is
+ copied, but no conversion method is applied.
+
+ - Function: widget-create-child-value parent type value
+ As a child of PARENT, create a widget with type TYPE and value
+ VALUE. TYPE is copied, but no conversion method is applied.
+
+ - Function: widget-convert type &rest args
+ Convert TYPE to a widget without inserting it in the buffer. The
+ optional ARGS are additional keyword arguments.
+
+ The widget's `:args' property is set from the longest tail of ARGS
+ whose `cdr' is not a keyword, or if that is null, from the longest
+ tail of TYPE's `:args' property whose cdr is not a keyword.
+ Keyword arguments from ARGS are set, and the `:value' property (if
+ any) is converted from external to internal format.
+
+ `widget-convert' is typically not called from user code; rather it
+is called implicitly through the `widget-create*' functions.
+
\1f
File: widget.info, Node: Widget Browser, Next: Widget Minor Mode, Prev: Defining New Widgets, Up: Top
Widget Browser
==============
- There is a separate package to browse widgets. 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 `:parent', which avoids printing cyclic structures.
+There is a separate package to browse widgets. 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 `:parent', which avoids printing cyclic structures.
- Command: widget-browse WIDGET
Create a widget browser for WIDGET. When called interactively,
Widget Minor Mode
=================
- There is a minor mode for manipulating widgets in major modes that
+There is a minor mode for manipulating widgets in major modes that
doesn't provide any support for widgets themselves. This is mostly
intended to be useful for programmers doing experiments.
This is only meaningful for radio buttons or checkboxes in a list.
\1f
-File: widget.info, Node: Widget Wishlist, Prev: Utilities, Up: Top
+File: widget.info, Node: Widget Wishlist, Next: Widget Internals, Prev: Utilities, Up: Top
Wishlist
========
* `C-e e' in a fixed size field should go to the end of the text in
the field, not the end of the field itself.
- * Use and overlay instead of markers to delimit the widget. Create
+ * Use an overlay instead of markers to delimit the widget. Create
accessors for the end points.
* Clicking on documentation links should call `describe-function' or
symbol, it should pop up a menu.
+\1f
+File: widget.info, Node: Widget Internals, Prev: Widget Wishlist, Up: Top
+
+Internals
+=========
+
+This (very brief!) section provides a few notes on the internal
+structure and implementation of Emacs widgets. Avoid relying on this
+information. (We intend to improve it, but this will take some time.)
+To the extent that it actually describes APIs, the information will be
+moved to appropriate sections of the manual in due course.
+
+The "Widget" and "Type" Structures
+----------------------------------
+
+Widgets and types are currently both implemented as lists.
+
+ A symbol may be defined as a "type name" using `define-widget'.
+*Note Defining New Widgets::. A "type" is a list whose car is a
+previously defined type name, nil, or (recursively) a type. The car is
+the "class" or parent type of the type, and properties which are not
+specified in the new type will be inherited from ancestors. Probably
+the only type without a class should be the `default' type. The cdr of
+a type is a plist whose keys are widget property keywords.
+
+ A type or type name may also be referred to as an "unconverted
+widget".
+
+ A "converted widget" or "widget instance" is a list whose car is a
+type name or a type, and whose cdr is a property list. Furthermore,
+all children of the converted widget must be converted. Finally, in the
+process of appropriate parts of the list structure are copied to ensure
+that changes in values of one instance do not affect another's.
+
\1f
Tag Table:
Node: Top\7f211
-Node: Introduction\7f591
-Node: User Interface\7f4075
-Node: Programming Example\7f8970
-Node: Setting Up the Buffer\7f13120
+Node: Introduction\7f612
+Node: User Interface\7f4087
+Node: Programming Example\7f8976
+Node: Setting Up the Buffer\7f13123
Node: Basic Types\7f14837
-Node: link\7f20895
-Node: url-link\7f21409
-Node: info-link\7f21721
-Node: push-button\7f22012
-Node: editable-field\7f22585
-Node: text\7f24068
-Node: menu-choice\7f24366
-Node: radio-button-choice\7f25219
-Node: item\7f26786
-Node: choice-item\7f27174
-Node: toggle\7f27672
-Node: checkbox\7f28409
-Node: checklist\7f28715
-Node: editable-list\7f30159
-Node: group\7f31341
-Node: Sexp Types\7f31628
-Node: constants\7f31941
-Node: generic\7f33020
-Node: atoms\7f33553
-Node: composite\7f35500
-Node: Widget Properties\7f37970
-Node: Defining New Widgets\7f41035
-Node: Widget Browser\7f46335
-Node: Widget Minor Mode\7f47193
-Node: Utilities\7f47750
-Node: Widget Wishlist\7f48231
+Node: link\7f21042
+Node: url-link\7f21553
+Node: info-link\7f21862
+Node: push-button\7f22150
+Node: editable-field\7f22720
+Node: text\7f24200
+Node: menu-choice\7f24495
+Node: radio-button-choice\7f25345
+Node: item\7f26909
+Node: choice-item\7f27294
+Node: toggle\7f27789
+Node: checkbox\7f28523
+Node: checklist\7f28826
+Node: editable-list\7f30267
+Node: group\7f31447
+Node: Sexp Types\7f31733
+Node: constants\7f32043
+Node: generic\7f33114
+Node: atoms\7f33644
+Node: composite\7f35588
+Node: Widget Properties\7f38055
+Node: Defining New Widgets\7f41117
+Node: Widget Browser\7f49281
+Node: Widget Minor Mode\7f50136
+Node: Utilities\7f50690
+Node: Widget Wishlist\7f51171
+Node: Widget Internals\7f52892
\1f
End Tag Table
projects / chise / xemacs-chise.git.1 / blobdiff