+++ /dev/null
-This is Info file ../info/widget.info, produced by Makeinfo version
-1.68 from the input file widget.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Widgets: (widget). The Emacs Widget Library.
-END-INFO-DIR-ENTRY
-
-\1f
-File: widget.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
-
-The Emacs Widget Library
-************************
-
-* Menu:
-
-* Introduction::
-* User Interface::
-* Programming Example::
-* Setting Up the Buffer::
-* Basic Types::
-* Sexp Types::
-* Widget Properties::
-* Defining New Widgets::
-* Widget Browser::
-* Widget Minor Mode::
-* Utilities::
-* Widget Wishlist::
-
-\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
-`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
-other widgets within a text buffer. The `widget' package simplifies
-this task.
-
- The basic widgets are:
-
-`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'
- An 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 field than just editable text are supported.
-
- 2. You can give the user immediate feedback if he enters invalid data
- in a text field, and sometimes prevent entering invalid data.
-
- 3. You can have fixed sized fields, thus allowing multiple field to be
- lined up in columns.
-
- 4. It is simple to query or set the value of a field.
-
- 5. Editing happens in buffer, not in the mini-buffer.
-
- 6. Packages using the library get a uniform look, making them easier
- for the user to learn.
-
- 7. As support for embedded graphics improve, the widget library will
- extended to support it. This means that your code using the widget
- library will also use the new graphic features by automatic.
-
- 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.
-
-\1f
-File: widget.info, Node: User Interface, Next: Programming Example, Prev: Introduction, Up: Top
-
-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:
-
- Here is some documentation.
-
- Name: My Name *Choose*: This option
- Address: Some Place
- In some City
- Some country.
-
- See also _other work_ for more information.
-
- Numbers: count to three below
- [INS] [DEL] One
- [INS] [DEL] Eh, two?
- [INS] [DEL] Five!
- [INS]
-
- Select multiple:
-
- [X] This
- [ ] That
- [X] Thus
-
- Select one:
-
- (*) One
- ( ) Another One.
- ( ) A Final One.
-
- [Apply Form] [Reset Form]
-
- The top level widgets in is example are tagged `Name', `Choose',
-`Address', `_other work_', `Numbers', `Select multiple', `Select one',
-`[Apply Form]', and `[Reset Form]'. There are basically two thing the
-user can do within a form, namely editing the editable text fields and
-activating the buttons.
-
-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
-middle of another field is prohibited.
-
- Editing text fields are created by the `editable-field' widget.
-
- The editing text fields are highlighted with the `widget-field-face'
-face, making them easy to find.
-
- - Face: widget-field-face
- Face used for other editing fields.
-
-Buttons
--------
-
- 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>'
- - Command: widget-button-press POS &optional EVENT
- Invoke the button at POS, defaulting to point. If point is
- not located on a button, invoke the binding in
- `widget-global-map' (by default the global map).
-
-`mouse-2'
- - Command: widget-button-click 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 `widget-global-map' (by default the
- global map).
-
- There are several different kind of buttons, all of which are
-present in the example:
-
-*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 `menu-choice'
- 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
- list. The list is created by the `editable-list' widget.
-
-*Embedded Buttons.*
- The `_other work_' is an example of an embedded button. Embedded
- buttons are not associated with a fields, but can serve any
- purpose, such as implementing hypertext references. They are
- usually created by the `link' widget.
-
-*The `[ ]' and `[X]' buttons.*
- Activating one of these will convert it to the other. This is
- useful for implementing multiple-choice fields. You can create it
- wit
-
-*The `( )' and `(*)' buttons.*
- Only one radio button in a `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.
-
-*The `[Apply Form]' `[Reset Form]' buttons.*
- These are explicit buttons made with the `push-button' widget.
- The main difference from the `link' widget is that the buttons are
- will be displayed as GUI buttons when possible. enough.
-
- To make them easier to locate, buttons are emphasized in the buffer.
-
- - Face: widget-button-face
- Face used for buttons.
-
- - User Option: widget-mouse-face
- Face used for buttons when the mouse pointer is above it.
-
-Navigation
-----------
-
- You can use all the normal Emacs commands to move around in a form
-buffer, plus you will have these additional commands:
-
-`<TAB>'
- - Command: widget-forward &optional COUNT
- Move point COUNT buttons or editing fields forward.
-
-`<M-TAB>'
- - Command: widget-backward &optional COUNT
- Move point COUNT buttons or editing fields backward.
-
-\1f
-File: widget.info, Node: Programming Example, Next: Setting Up the Buffer, Prev: User Interface, Up: Top
-
-Programming Example
-===================
-
- Here is the code to implement the user interface example (see *Note
-User Interface::).
-
- (require 'widget)
-
- (eval-when-compile
- (require 'wid-edit))
-
- (defvar widget-example-repeat)
-
- (defun widget-example ()
- "Create the widgets from the Widget manual."
- (interactive)
- (kill-buffer (get-buffer-create "*Widget Example*"))
- (switch-to-buffer (get-buffer-create "*Widget Example*"))
- (kill-all-local-variables)
- (make-local-variable 'widget-example-repeat)
- (widget-insert "Here is some documentation.\n\nName: ")
- (widget-create 'editable-field
- :size 13
- "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-insert "Address: ")
- (widget-create 'editable-field
- "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))
-
-\1f
-File: widget.info, Node: Setting Up the Buffer, Next: Basic Types, Prev: Programming Example, Up: Top
-
-Setting Up the Buffer
-=====================
-
- 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.
-
- - Function: widget-create TYPE [ KEYWORD ARGUMENT ]...
- Create and return a widget of type TYPE. The syntax for the TYPE
- argument is described in *Note Basic Types::.
-
- The keyword arguments can be used to overwrite the keyword
- arguments that are part of TYPE.
-
- - Function: widget-delete WIDGET
- Delete WIDGET and remove it from the buffer.
-
- - Function: widget-setup
- Setup a buffer to support widgets.
-
- This should be called after creating all the widgets and before
- allowing the user to edit them.
-
-
- If you want to insert text outside the widgets in the form, the
-recommended way to do that is with `widget-insert'.
-
- - Function: widget-insert
- Insert the arguments, either strings or characters, at point. The
- inserted text will be read only.
-
- There is a standard widget keymap which you might find useful.
-
- - Const: widget-keymap
- A keymap with the global keymap as its parent.
- <TAB> and `C-<TAB>' are bound to `widget-forward' and
- `widget-backward', respectively. `<RET>' and `mouse-2' are bound
- to `widget-button-press' and `widget-button-'.
-
- - Variable: widget-global-map
- Keymap used by `widget-button-press' and `widget-button-click'
- when not on a button. By default this is `global-map'.
-
-\1f
-File: widget.info, Node: Basic Types, Next: Sexp Types, Prev: Setting Up the Buffer, Up: Top
-
-Basic Types
-===========
-
- The syntax of a type specification is given below:
-
- NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
- | NAME
-
- Where, NAME is a widget name, KEYWORD is the name of a property,
-ARGUMENT is the value of the property, and ARGS are interpreted in a
-widget specific way.
-
- There following keyword arguments that apply to all widgets:
-
-`:value'
- The initial value for widgets of this type.
-
-`:format'
- This string will be inserted in the buffer when you create a
- widget. The following `%' escapes are available:
-
- `%['
- `%]'
- The text inside will be marked as a button.
-
- By default, the text will be shown in `widget-button-face',
- and surrounded by brackets.
-
- - User Option: widget-button-prefix
- String to prefix buttons.
-
- - User Option: widget-button-suffix
- String to suffix buttons.
-
- `%{'
- `%}'
- The text inside will be displayed with the face specified by
- `:sample-face'.
-
- `%v'
- This will be replaces with the buffer representation of the
- widgets value. What this is depends on the widget type.
-
- `%d'
- Insert the string specified by `:doc' here.
-
- `%h'
- Like `%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
- `:doc' property in the widget, it will instead examine the
- `: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.
-
- `%t'
- Insert the string specified by `:tag' here, or the `princ'
- representation of the value if there is no tag.
-
- `%%'
- Insert a literal `%'.
-
-`:button-face'
- Face used to highlight text inside %[ %] in the format.
-
-`:button-prefix'
-`:button-suffix'
- Text around %[ %] in the format.
-
- These can be
- *nil*
- No text is inserted.
-
- *a string*
- The string is inserted literally.
-
- *a symbol*
- The value of the symbol is expanded according to this table.
-
-`:doc'
- The string inserted by the `%d' escape in the format string.
-
-`:tag'
- The string inserted by the `%t' escape in the format string.
-
-`:tag-glyph'
- Name of image to use instead of the string specified by `:tag' on
- Emacsen that supports it.
-
-`:help-echo'
- Message displayed whenever you move to the widget with either
- `widget-forward' or `widget-backward'.
-
-`:indent'
- An integer indicating the absolute number of spaces to indent
- children of this widget.
-
-`:offset'
- An integer indicating how many extra spaces to add to the widget's
- grandchildren compared to this widget.
-
-`:extra-offset'
- An integer indicating how many extra spaces to add to the widget's
- children compared to this widget.
-
-`: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.
-
-`:menu-tag'
- Tag used in the menu when the widget is used as an option in a
- `menu-choice' widget.
-
-`:menu-tag-get'
- Function used for finding the tag when the widget is used as an
- option in a `menu-choice' widget. By default, the tag used will
- be either the `:menu-tag' or `:tag' property if present, or the
- `princ' representation of the `:value' property if not.
-
-`:match'
- Should be a function called with two arguments, the widget and a
- value, and returning non-nil if the widget can represent the
- specified value.
-
-`:validate'
- A function which takes a widget as an argument, and return nil if
- the widgets current value is valid for the widget. Otherwise, it
- should return the widget containing the invalid data, and set that
- widgets `:error' property to a string explaining the error.
-
- The following predefined function can be used:
-
- - Function: widget-children-validate WIDGET
- All the `:children' of WIDGET must be valid.
-
-`:tab-order'
- Specify the order in which widgets are traversed with
- `widget-forward' or `widget-backward'. This is only partially
- implemented.
-
- a. Widgets with tabbing order `-1' are ignored.
-
- b. (Unimplemented) When on a widget with tabbing order N, go to
- the next widget in the buffer with tabbing order N+1 or `nil',
- whichever comes first.
-
- c. When on a widget with no tabbing order specified, go to the
- next widget in the buffer with a positive tabbing order, or
- `nil'
-
-`:parent'
- The parent of a nested widget (e.g. a `menu-choice' item or an
- element of a `editable-list' widget).
-
-`:sibling-args'
- This keyword is only used for members of a `radio-button-choice' or
- `checklist'. The value should be a list of extra keyword
- 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
- `.xpm' (if supported) or `.xbm' extension.
-
- - User Option: widget-glyph-enable
- If non-nil, allow glyphs to appear on displays where they are
- supported.
-
-* Menu:
-
-* link::
-* url-link::
-* info-link::
-* push-button::
-* editable-field::
-* text::
-* menu-choice::
-* radio-button-choice::
-* item::
-* choice-item::
-* toggle::
-* checkbox::
-* checklist::
-* editable-list::
-* group::
-
-\1f
-File: widget.info, Node: link, Next: url-link, Prev: Basic Types, Up: Basic Types
-
-The `link' Widget
------------------
-
- Syntax:
-
- TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ])
-
- The VALUE, if present, is used to initialize the `:value' property.
-The value should be a string, which will be inserted in the buffer.
-
- By default the link will be shown in brackets.
-
- - User Option: widget-link-prefix
- String to prefix links.
-
- - User Option: widget-link-suffix
- String to suffix links.
-
-\1f
-File: widget.info, Node: url-link, Next: info-link, Prev: link, Up: Basic Types
-
-The `url-link' Widget
----------------------
-
- Syntax:
-
- TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
-
- When this link is invoked, the WWW browser specified by
-`browse-url-browser-function' will be called with URL.
-
-\1f
-File: widget.info, Node: info-link, Next: push-button, Prev: url-link, Up: Basic Types
-
-The `info-link' Widget
-----------------------
-
- Syntax:
-
- TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
-
- When this link is invoked, the built-in info browser is started on
-ADDRESS.
-
-\1f
-File: widget.info, Node: push-button, Next: editable-field, Prev: info-link, Up: Basic Types
-
-The `push-button' Widget
-------------------------
-
- Syntax:
-
- TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ])
-
- The VALUE, if present, is used to initialize the `:value' property.
-The value should be a string, which will be inserted in the buffer.
-
- By default the tag will be shown in brackets.
-
- - User Option: widget-push-button-prefix
- String to prefix push buttons.
-
- - User Option: widget-push-button-suffix
- String to suffix push buttons.
-
-\1f
-File: widget.info, Node: editable-field, Next: text, Prev: push-button, Up: Basic Types
-
-The `editable-field' Widget
----------------------------
-
- Syntax:
-
- TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
-
- The VALUE, if present, is used to initialize the `:value' property.
-The value should be a string, which will be inserted in field. This
-widget will match all string values.
-
- The following extra properties are recognized.
-
-`:size'
- The width of the editable field.
- By default the field will reach to the end of the line.
-
-`:value-face'
- Face used for highlighting the editable field. Default is
- `widget-field-face'.
-
-`:secret'
- Character used to display the value. You can set this to e.g. `?*'
- if the field contains a password or other secret information. By
- default, the value is not secret.
-
-`:valid-regexp'
- By default the `:validate' function will match the content of the
- field with the value of this attribute. The default value is `""'
- which matches everything.
-
-`:keymap'
- Keymap used in the editable field. The default value is
- `widget-field-keymap', which allows you to use all the normal
- editing commands, even if the buffers major mode suppress some of
- them. Pressing return invokes the function specified by `:action'.
-
-\1f
-File: widget.info, Node: text, Next: menu-choice, Prev: editable-field, Up: Basic Types
-
-The `text' Widget
------------------
-
- 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.
-
-\1f
-File: widget.info, Node: menu-choice, Next: radio-button-choice, Prev: text, Up: Basic Types
-
-The `menu-choice' Widget
-------------------------
-
- Syntax:
-
- TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
-
- The TYPE arguments represents each possible choice. The widgets
-value of will be the value of the chosen TYPE argument. This widget
-will match any value that matches at least one of the specified TYPE
-arguments.
-
-`:void'
- Widget type used as a fallback when the value does not match any
- of the specified TYPE arguments.
-
-`:case-fold'
- Set this to nil if you don't want to ignore case when prompting
- for a choice through the minibuffer.
-
-`:children'
- A list whose car is the widget representing the currently chosen
- type in the buffer.
-
-`:choice'
- The current chosen type
-
-`:args'
- The list of types.
-
-\1f
-File: widget.info, Node: radio-button-choice, Next: item, Prev: menu-choice, Up: Basic Types
-
-The `radio-button-choice' Widget
---------------------------------
-
- Syntax:
-
- TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
-
- The TYPE arguments represents each possible choice. The widgets
-value of will be the value of the chosen TYPE argument. This widget
-will match any value that matches at least one of the specified TYPE
-arguments.
-
- The following extra properties are recognized.
-
-`:entry-format'
- This string will be inserted for each entry in the list. The
- following `%' escapes are available:
- `%v'
- Replaced with the buffer representation of the TYPE widget.
-
- `%b'
- Replace with the radio button.
-
- `%%'
- Insert a literal `%'.
-
-`button-args'
- A list of keywords to pass to the radio buttons. Useful for
- setting e.g. the `:help-echo' for each button.
-
-`:buttons'
- The widgets representing the radio buttons.
-
-`:children'
- The widgets representing each type.
-
-`:choice'
- The current chosen type
-
-`:args'
- The list of types.
-
- You can add extra radio button items to a `radio-button-choice'
-widget after it has been created with the function
-`widget-radio-add-item'.
-
- - Function: widget-radio-add-item WIDGET TYPE
- Add to `radio-button-choice' widget WIDGET a new radio button item
- of type TYPE.
-
- Please note that such items added after the `radio-button-choice'
-widget has been created will *not* be properly destructed when you call
-`widget-delete'.
-
-\1f
-File: widget.info, Node: item, Next: choice-item, Prev: radio-button-choice, Up: Basic Types
-
-The `item' Widget
------------------
-
- Syntax:
-
- ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
-
- The VALUE, if present, is used to initialize the `:value' property.
-The value should be a string, which will be inserted in the buffer.
-This widget will only match the specified value.
-
-\1f
-File: widget.info, Node: choice-item, Next: toggle, Prev: item, Up: Basic Types
-
-The `choice-item' Widget
-------------------------
-
- Syntax:
-
- ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
-
- The VALUE, if present, is used to initialize the `:value' property.
-The value should be a string, which will be inserted in the buffer as a
-button. Activating the button of a `choice-item' is equivalent to
-activating the parent widget. This widget will only match the
-specified value.
-
-\1f
-File: widget.info, Node: toggle, Next: checkbox, Prev: choice-item, Up: Basic Types
-
-The `toggle' Widget
--------------------
-
- Syntax:
-
- TYPE ::= (toggle [KEYWORD ARGUMENT]...)
-
- The widget has two possible states, `on' and `off', which
-corresponds to a `t' or `nil' value.
-
- The following extra properties are recognized.
-
-`:on'
- String representing the `on' state. By default the string `on'.
-
-`:off'
- String representing the `off' state. By default the string `off'.
-
-`:on-glyph'
- Name of a glyph to be used instead of the `:on' text string, on
- emacsen that supports it.
-
-`:off-glyph'
- Name of a glyph to be used instead of the `:off' text string, on
- emacsen that supports it.
-
-\1f
-File: widget.info, Node: checkbox, Next: checklist, Prev: toggle, Up: Basic Types
-
-The `checkbox' Widget
----------------------
-
- The widget has two possible states, `selected' and `unselected',
-which corresponds to a `t' or `nil' value.
-
- Syntax:
-
- TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
-
-\1f
-File: widget.info, Node: checklist, Next: editable-list, Prev: checkbox, Up: Basic Types
-
-The `checklist' Widget
-----------------------
-
- Syntax:
-
- TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
-
- The TYPE arguments represents each checklist item. The widgets
-value of will be a list containing the value of each ticked TYPE
-argument. The checklist widget will match a list whose elements all
-matches at least one of the specified TYPE arguments.
-
- The following extra properties are recognized.
-
-`:entry-format'
- This string will be inserted for each entry in the list. The
- following `%' escapes are available:
- `%v'
- Replaced with the buffer representation of the TYPE widget.
-
- `%b'
- Replace with the checkbox.
-
- `%%'
- Insert a literal `%'.
-
-`:greedy'
- Usually, a checklist will only match if the items are in the exact
- sequence given in the specification. By setting `:greedy' to
- non-nil, it will allow the items to come in any sequence.
- However, if you extract the value they will be in the sequence
- given in the checklist. I.e. the original sequence is forgotten.
-
-`button-args'
- A list of keywords to pass to the checkboxes. Useful for setting
- e.g. the `:help-echo' for each checkbox.
-
-`:buttons'
- The widgets representing the checkboxes.
-
-`:children'
- The widgets representing each type.
-
-`:args'
- The list of types.
-
-\1f
-File: widget.info, Node: editable-list, Next: group, Prev: checklist, Up: Basic Types
-
-The `editable-list' Widget
---------------------------
-
- Syntax:
-
- TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
-
- The value is a list, where each member represents one widget of type
-TYPE.
-
- The following extra properties are recognized.
-
-`:entry-format'
- This string will be inserted for each entry in the list. The
- following `%' escapes are available:
- `%v'
- This will be replaced with the buffer representation of the
- TYPE widget.
-
- `%i'
- Insert the [INS] button.
-
- `%d'
- Insert the [DEL] button.
-
- `%%'
- Insert a literal `%'.
-
-`:insert-button-args'
- A list of keyword arguments to pass to the insert buttons.
-
-`:delete-button-args'
- A list of keyword arguments to pass to the delete buttons.
-
-`:append-button-args'
- A list of keyword arguments to pass to the trailing insert button.
-
-`:buttons'
- The widgets representing the insert and delete buttons.
-
-`:children'
- The widgets representing the elements of the list.
-
-`: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.
-
- Syntax:
-
- TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
-
- The value is a list, with one member for each TYPE.
-
-\1f
-File: widget.info, Node: Sexp Types, Next: Widget Properties, Prev: Basic Types, Up: Top
-
-Sexp Types
-==========
-
- A number of widgets for editing s-expressions (lisp types) are also
-available. These basically fall in the following categories.
-
-* Menu:
-
-* constants::
-* generic::
-* atoms::
-* composite::
-
-\1f
-File: widget.info, Node: constants, Next: generic, Prev: Sexp Types, Up: Sexp Types
-
-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 syntax for the `const' widget is
-
- TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ])
-
- The VALUE, if present, is used to initialize the `:value' property
-and can be any s-expression.
-
- - Widget: const
- This will display any valid s-expression in an immutable part of
- the buffer.
-
- There are two variations of the `const' widget, namely
-`variable-item' and `function-item'. These should contain a symbol
-with a variable or function binding. The major difference from the
-`const' widget is that they will allow the user to see the variable or
-function documentation for the symbol.
-
- - Widget: variable-item
- An immutable symbol that is bound as a variable.
-
- - Widget: function-item
- An immutable symbol that is bound as a function.
-
-\1f
-File: widget.info, Node: generic, Next: atoms, Prev: constants, Up: Sexp Types
-
-Generic Sexp Widget.
---------------------
-
- 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
-
- TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ])
-
- - Widget: sexp
- This will allow you to edit any valid s-expression in an editable
- buffer field.
-
- The `sexp' widget takes the same keyword arguments as the
- `editable-field' widget.
-
-\1f
-File: widget.info, Node: atoms, Next: composite, Prev: generic, Up: Sexp Types
-
-Atomic Sexp Widgets.
---------------------
-
- 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.
-
- The syntax for all the atoms are
-
- TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ])
-
- The VALUE, if present, is used to initialize the `:value' property
-and must be an expression of the same type as the widget. I.e. the
-string widget can only be initialized with a string.
-
- All the atom widgets take the same keyword arguments as the
-`editable-field' widget.
-
- - Widget: string
- Allows you to edit a string in an editable field.
-
- - Widget: regexp
- Allows you to edit a regular expression in an editable field.
-
- - Widget: character
- Allows you to enter a character in an editable field.
-
- - Widget: file
- Allows you to edit a file name in an editable field. If you invoke
- the tag button, you can edit the file name in the mini-buffer with
- completion.
-
- Keywords:
- `:must-match'
- If this is set to non-nil, only existing file names will be
- allowed in the minibuffer.
-
- - Widget: directory
- Allows you to edit a directory name in an editable field. Similar
- to the `file' widget.
-
- - Widget: symbol
- Allows you to edit a lisp symbol in an editable field.
-
- - Widget: function
- Allows you to edit a lambda expression, or a function name with
- completion.
-
- - Widget: variable
- Allows you to edit a variable name, with completion.
-
- - Widget: integer
- Allows you to edit an integer in an editable field.
-
- - Widget: number
- Allows you to edit a number in an editable field.
-
- - Widget: boolean
- Allows you to edit a boolean. In lisp this means a variable which
- is either nil meaning false, or non-nil meaning true.
-
-\1f
-File: widget.info, Node: composite, Prev: atoms, Up: Sexp Types
-
-Composite Sexp Widgets.
------------------------
-
- The syntax for the composite are
-
- TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
-
- Where each COMPONENT must be a widget type. Each component widget
-will be displayed in the buffer, and be editable to the user.
-
- - Widget: cons
- The value of a `cons' widget is a cons-cell where the car is the
- value of the first component and the cdr is the value of the second
- component. There must be exactly two components.
-
- - Widget: list
- The value of a `list' widget is a list containing the value of
- each of its component.
-
- - Widget: vector
- The value of a `vector' widget is a vector containing the value of
- each of its component.
-
- The above suffice for specifying fixed size lists and vectors. To
-get variable length lists and vectors, you can use a `choice', `set' or
-`repeat' widgets together with the `:inline' keywords. If any
-component of a composite widget has the `: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 arguments should either by the symbol `t' or two
-files, you can use the following widget specification:
-
- (list file
- (choice (const t)
- (list :inline t
- :value ("foo" "bar")
- string string)))
-
- The value of a widget of this type will either have the form `(file
-t)' or `(file string string)'.
-
- This concept of inline is probably hard to understand. It was
-certainly hard to implement so instead of confuse you more by trying to
-explain it here, I'll just suggest you meditate over it for a while.
-
- - Widget: choice
- Allows you to edit a sexp which may have one of fixed set of
- types. It is currently implemented with the `choice-menu' basic
- widget, and has a similar syntax.
-
- - Widget: set
- Allows you to specify a type which must be a list whose elements
- all belong to given set. The elements of the list is not
- significant. This is implemented on top of the `checklist' basic
- widget, and has a similar syntax.
-
- - Widget: repeat
- Allows you to specify a variable length list whose members are all
- of the same type. Implemented on top of the `editable-list' basic
- widget, and has a similar syntax.
-
-\1f
-File: widget.info, Node: Widget Properties, Next: Defining New Widgets, Prev: Sexp Types, Up: Top
-
-Properties
-==========
-
- 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
- call this function on an uninitialized widget.
-
- - Function: widget-value-set WIDGET VALUE
- Set the value contained in WIDGET to VALUE. It is an error to
- call this function with an invalid VALUE.
-
- *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 `widget-put' and `widget-get'. The property names
-must begin with a `:'.
-
- - Function: widget-put WIDGET PROPERTY VALUE
- In WIDGET set PROPERTY to VALUE. PROPERTY should be a symbol,
- while VALUE can be anything.
-
- - Function: widget-get WIDGET PROPERTY
- In WIDGET return the value for PROPERTY. PROPERTY should be a
- symbol, the value is what was last set by `widget-put' for
- PROPERTY.
-
- - Function: widget-member WIDGET PROPERTY
- Non-nil if WIDGET has a value (even nil) for property PROPERTY.
-
- Occasionally it can be useful to know which kind of widget you have,
-i.e. the name of the widget type you gave when the widget was created.
-
- - Function: widget-type WIDGET
- Return the name of WIDGET, a symbol.
-
- 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:
-
- ;; Examine if WIDGET is active or not.
- (if (widget-apply WIDGET :active)
- (message "Widget is active.")
- (message "Widget is inactive.")
-
- ;; Make WIDGET inactive.
- (widget-apply WIDGET :deactivate)
-
- ;; Make WIDGET active.
- (widget-apply WIDGET :activate)
-
- A widget is inactive if itself, or any of its ancestors (found by
-following the `:parent' link) have been deactivated. To make sure a
-widget is really active, you must therefore activate both itself, and
-all its ancestors.
-
- (while widget
- (widget-apply widget :activate)
- (setq widget (widget-get widget :parent)))
-
- You can check if a widget has been made inactive by examining the
-value of `:inactive' keyword. If this is non-nil, the widget itself has
-been deactivated. This is different from using the `:active' keyword,
-in that the later tell you if the widget *or* any of its ancestors have
-been deactivated. Do not attempt to set the `:inactive' keyword
-directly. Use the `:activate' `:deactivated' keywords instead.
-
-\1f
-File: widget.info, Node: Defining New Widgets, Next: Widget Browser, Prev: Widget Properties, Up: Top
-
-Defining New Widgets
-====================
-
- You can define specialized widgets with `define-widget'. It allows
-you to create a shorthand for more complex widgets, including specifying
-component widgets and default new default values for the keyword
-arguments.
-
- - Function: widget-define 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
- the existing widget types.
-
- The third argument DOC is a documentation string for the widget.
-
- After the new widget has been defined, the following two calls will
- create identical widgets:
-
- * (widget-create NAME)
-
- * (apply widget-create CLASS ARGS)
-
-
- Using `widget-define' does just store 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.
-
- 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 widgets parent types, most
- derived first.
-
- The following predefined functions can be used here:
-
- - Function: widget-types-convert-widget WIDGET
- Convert `:args' as widget types in WIDGET.
-
- - Function: widget-value-convert-widget WIDGET
- Initialize `:value' from `:args' in WIDGET.
-
-`: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 `:value'
- when the widget is created, and on any value set later with
- `widget-value-set'.
-
-`: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 internal value. The function is called on the present `:value'
- when the widget is created, and on any value set later with
- `widget-value-set'.
-
-`:create'
- Function to create a widget from scratch. The function takes one
- argument, a widget type, and create a widget of that type, insert
- it in the buffer, and return a widget object.
-
-`:delete'
- Function to delete a widget. The function takes one argument, a
- widget, and should remove all traces of the widget from the buffer.
-
-`:value-create'
- Function to expand the `%v' escape in the format string. It will
- be called with the widget as its argument. Should insert a
- representation of the widgets value in the buffer.
-
-`:value-delete'
- Should remove the representation of the widgets 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 such has been used.
-
- The following predefined function can be used here:
-
- - Function: widget-children-value-delete WIDGET
- Delete all `:children' and `:buttons' in WIDGET.
-
-`:value-get'
- Function to extract the value of a widget, as it is displayed in
- the buffer.
-
- The following predefined function can be used here:
-
- - Function: widget-value-value-get WIDGET
- Return the `:value' property of WIDGET.
-
-`:format-handler'
- Function to handle unknown `%' escapes in the format string. It
- will be called with the widget and the escape character as
- arguments. You can set this to allow your widget to handle
- non-standard escapes.
-
- You should end up calling `widget-default-format-handler' to handle
- unknown escape sequences, which will handle the `%h' and any future
- escape sequences, as well as give an error for unknown escapes.
-
-`:action'
- Function to handle user initiated events. By default, `:notify'
- the parent.
-
- The following predefined function can be used here:
-
- - Function: widget-parent-action WIDGET &optional EVENT
- Tell `:parent' of WIDGET to handle the `:action'.
- Optional EVENT is the event that triggered the action.
-
-`:prompt-value'
- Function to prompt for a value in the minibuffer. The function
- should take four arguments, WIDGET, PROMPT, VALUE, and UNBOUND and
- should return a value for widget entered by the user. PROMPT is
- the prompt to use. VALUE is the default value to use, unless
- UNBOUND is non-nil in which case there are 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.
-
- If you want to define a new widget from scratch, use the `default'
-widget as its base.
-
- - 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.
-
-\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.
-
- - Command: widget-browse WIDGET
- Create a widget browser for WIDGET. When called interactively,
- prompt for WIDGET.
-
- - Command: widget-browse-other-window WIDGET
- Create a widget browser for WIDGET and show it in another window.
- When called interactively, prompt for WIDGET.
-
- - Command: widget-browse-at POS
- Create a widget browser for the widget at POS. When called
- interactively, use the position of point.
-
-\1f
-File: widget.info, Node: Widget Minor Mode, Next: Utilities, Prev: Widget Browser, Up: Top
-
-Widget Minor Mode
-=================
-
- 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.
-
- - Command: widget-minor-mode
- Toggle minor mode for traversing widgets. With arg, turn widget
- mode on if and only if arg is positive.
-
- - Variable: widget-minor-mode-keymap
- Keymap used in `widget-minor-mode'.
-
-\1f
-File: widget.info, Node: Utilities, Next: Widget Wishlist, Prev: Widget Minor Mode, Up: Top
-
-Utilities.
-==========
-
- - Function: widget-prompt-value WIDGET PROMPT [ VALUE UNBOUND ]
- Prompt for a value matching WIDGET, using PROMPT.
- The current value is assumed to be VALUE, unless UNBOUND is
- non-nil.
-
- - Function: widget-get-sibling WIDGET
- Get the item WIDGET is assumed to toggle.
- This is only meaningful for radio buttons or checkboxes in a list.
-
-\1f
-File: widget.info, Node: Widget Wishlist, Prev: Utilities, Up: Top
-
-Wishlist
-========
-
- * It should be possible to add or remove items from a list with `C-k'
- and `C-o' (suggested by RMS).
-
- * The `[INS]' and `[DEL]' buttons should be replaced by a single
- dash (`-'). The dash should be a button that, when invoked, ask
- whether you want to add or delete an item (RMS wanted to git rid of
- the ugly buttons, the dash is my idea).
-
- * The `menu-choice' tag should be prettier, something like the
- abbreviated menus in Open Look.
-
- * Finish `:tab-order'.
-
- * Make indentation work with glyphs and proportional fonts.
-
- * Add commands to show overview of object and class hierarchies to
- the browser.
-
- * Find a way to disable mouse highlight for inactive widgets.
-
- * Find a way to make glyphs look inactive.
-
- * Add `property-list' widget.
-
- * Add `association-list' widget.
-
- * Add `key-binding' widget.
-
- * Add `widget' widget for editing widget specifications.
-
- * Find clean way to implement variable length list. See
- `TeX-printer-list' for an explanation.
-
- * `C-h' in `widget-prompt-value' should give type specific help.
-
- * A mailto widget.
-
- * `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
- accessors for the end points.
-
- * Clicking on documentation links should call `describe-function' or
- `widget-browse-other-window' and friends directly, instead of going
- through `apropos'. If more than one function is valid for the
- symbol, it should pop up a menu.
-
-
-\1f
-Tag Table:
-Node: Top\7f227
-Node: Introduction\7f607
-Node: User Interface\7f4090
-Node: Programming Example\7f8985
-Node: Setting Up the Buffer\7f12302
-Node: Basic Types\7f14019
-Node: link\7f20064
-Node: url-link\7f20578
-Node: info-link\7f20890
-Node: push-button\7f21181
-Node: editable-field\7f21754
-Node: text\7f23093
-Node: menu-choice\7f23391
-Node: radio-button-choice\7f24256
-Node: item\7f25835
-Node: choice-item\7f26223
-Node: toggle\7f26721
-Node: checkbox\7f27446
-Node: checklist\7f27752
-Node: editable-list\7f29196
-Node: group\7f30378
-Node: Sexp Types\7f30665
-Node: constants\7f30978
-Node: generic\7f32057
-Node: atoms\7f32590
-Node: composite\7f34537
-Node: Widget Properties\7f37003
-Node: Defining New Widgets\7f40066
-Node: Widget Browser\7f45366
-Node: Widget Minor Mode\7f46224
-Node: Utilities\7f46781
-Node: Widget Wishlist\7f47262
-\1f
-End Tag Table
projects / chise / xemacs-chise.git.1 / blobdiff