(fast-lock-cache-directories): Remove "." from its
[emacs.git] / man / widget.texi
blob31c9f6bce2d457870a3b0002aa5d4ba72c230ce8
1 \input texinfo.tex
3 @c %**start of header
4 @setfilename ../info/widget
5 @settitle The Emacs Widget Library
6 @syncodeindex fn cp
7 @syncodeindex vr cp
8 @syncodeindex ky cp
9 @afourpaper
10 @c %**end of header
12 @copying
13 Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005,
14 2006, 2007, 2008  Free Software Foundation, Inc.
16 @quotation
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.2 or
19 any later version published by the Free Software Foundation; with the
20 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
21 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
22 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
23 license is included in the section entitled ``GNU Free Documentation
24 License'' in the Emacs manual.
26 This document is part of a collection distributed under the GNU Free
27 Documentation License.  If you want to distribute this document
28 separately from the collection, you can do so by adding a copy of the
29 license to the document, as described in section 6 of the license.
31 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
32 this GNU Manual, like GNU software.  Copies published by the Free
33 Software Foundation raise funds for GNU development.''
34 @end quotation
35 @end copying
37 @dircategory Emacs
38 @direntry
39 * Widget: (widget).      The "widget" package used by the Emacs Customization
40                            facility.
41 @end direntry
43 @node Top, Introduction, (dir), (dir)
44 @comment  node-name,  next,  previous,  up
45 @top The Emacs Widget Library
47 @menu
48 * Introduction::
49 * User Interface::
50 * Programming Example::
51 * Setting Up the Buffer::
52 * Basic Types::
53 * Sexp Types::
54 * Widget Properties::
55 * Defining New Widgets::
56 * Widget Browser::
57 * Widget Minor Mode::
58 * Utilities::
59 * Widget Wishlist::
60 * GNU Free Documentation License::
61 * Index::
62 @end menu
64 @node  Introduction, User Interface, Top, Top
65 @comment  node-name,  next,  previous,  up
66 @section Introduction
68 Most graphical user interface toolkits provide a number of standard
69 user interface controls (sometimes known as `widgets' or `gadgets').
70 Emacs doesn't really support anything like this, except for an
71 incredibly powerful text ``widget.''  On the other hand, Emacs does
72 provide the necessary primitives to implement many other widgets
73 within a text buffer.  The @code{widget} package simplifies this task.
75 @cindex basic widgets
76 @cindex widgets, basic types
77 The basic widgets are:
79 @table @code
80 @item link
81 Areas of text with an associated action.  Intended for hypertext links
82 embedded in text.
83 @item push-button
84 Like link, but intended for stand-alone buttons.
85 @item editable-field
86 An editable text field.  It can be either variable or fixed length.
87 @item menu-choice
88 Allows the user to choose one of multiple options from a menu, each
89 option is itself a widget.  Only the selected option will be visible in
90 the buffer.
91 @item radio-button-choice
92 Allows the user to choose one of multiple options by activating radio
93 buttons.  The options are implemented as widgets.  All options will be
94 visible in the buffer.
95 @item item
96 A simple constant widget intended to be used in the @code{menu-choice} and
97 @code{radio-button-choice} widgets.
98 @item choice-item
99 A button item only intended for use in choices.  When invoked, the user
100 will be asked to select another option from the choice widget.
101 @item toggle
102 A simple @samp{on}/@samp{off} switch.
103 @item checkbox
104 A checkbox (@samp{[ ]}/@samp{[X]}).
105 @item editable-list
106 Create an editable list.  The user can insert or delete items in the
107 list.  Each list item is itself a widget.
108 @end table
110 Now, of what possible use can support for widgets be in a text editor?
111 I'm glad you asked.  The answer is that widgets are useful for
112 implementing forms.  A @dfn{form} in Emacs is a buffer where the user is
113 supposed to fill out a number of fields, each of which has a specific
114 meaning.  The user is not supposed to change or delete any of the text
115 between the fields.  Examples of forms in Emacs are the @file{forms}
116 package (of course), the customize buffers, the mail and news compose
117 modes, and the @acronym{HTML} form support in the @file{w3} browser.
119 @cindex widget library, why use it
120 The advantages for a programmer of using the @code{widget} package to
121 implement forms are:
123 @enumerate
124 @item
125 More complex fields than just editable text are supported.
126 @item
127 You can give the users immediate feedback if they enter invalid data in a
128 text field, and sometimes prevent entering invalid data.
129 @item
130 You can have fixed sized fields, thus allowing multiple fields to be
131 lined up in columns.
132 @item
133 It is simple to query or set the value of a field.
134 @item
135 Editing happens in the buffer, not in the mini-buffer.
136 @item
137 Packages using the library get a uniform look, making them easier for
138 the user to learn.
139 @item
140 As support for embedded graphics improve, the widget library will be
141 extended to use the GUI features.  This means that your code using the
142 widget library will also use the new graphic features automatically.
143 @end enumerate
145 @node User Interface, Programming Example, Introduction, Top
146 @comment  node-name,  next,  previous,  up
147 @section User Interface
149 A form consists of read only text for documentation and some fields,
150 where each field contains two parts, a tag and a value.  The tags are
151 used to identify the fields, so the documentation can refer to the
152 @samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
153 example form:
155 @example
156 Here is some documentation.
158 Name: @i{My Name}     @strong{Choose}: This option
159 Address:  @i{Some Place
160 In some City
161 Some country.}
163 See also @b{_other work_} for more information.
165 Numbers: count to three below
166 @b{[INS]} @b{[DEL]} @i{One}
167 @b{[INS]} @b{[DEL]} @i{Eh, two?}
168 @b{[INS]} @b{[DEL]} @i{Five!}
169 @b{[INS]}
171 Select multiple:
173 @b{[X]} This
174 @b{[ ]} That
175 @b{[X]} Thus
177 Select one:
179 @b{(*)} One
180 @b{( )} Another One.
181 @b{( )} A Final One.
183 @b{[Apply Form]} @b{[Reset Form]}
184 @end example
186 The top level widgets in this example are tagged @samp{Name},
187 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
188 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
189 @samp{[Reset Form]}.  There are basically two things the user can do
190 within a form, namely editing the editable text fields and activating
191 the buttons.
193 @subsection Editable Text Fields
195 In the example, the value for the @samp{Name} is most likely displayed
196 in an editable text field, and so are values for each of the members of
197 the @samp{Numbers} list.  All the normal Emacs editing operations are
198 available for editing these fields.  The only restriction is that each
199 change you make must be contained within a single editable text field.
200 For example, capitalizing all text from the middle of one field to the
201 middle of another field is prohibited.
203 Editable text fields are created by the @code{editable-field} widget.
205 @strong{Warning:} In an @code{editable-field} widget, the editable
206 field must not be adjacent to another widget---that won't work.
207 You must put some text in between.  Either make this text part of
208 the @code{editable-field} widget itself, or insert it with
209 @code{widget-insert}.
211 The @code{:format} keyword is useful for generating the necessary
212 text; for instance, if you give it a value of @code{"Name: %v "},
213 the @samp{Name: } part will provide the necessary separating text
214 before the field and the trailing space will provide the
215 separating text after the field.  If you don't include the
216 @code{:size} keyword, the field will extend to the end of the
217 line, and the terminating newline will provide separation after.
219 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
220 must be preceded by some other text in the @code{:format} string
221 (if specified).
223 The editing text fields are highlighted with the
224 @code{widget-field-face} face, making them easy to find.
226 @deffn Face widget-field-face
227 Face used for other editing fields.
228 @end deffn
230 @subsection Buttons
232 @cindex widget buttons
233 @cindex button widgets
234 Some portions of the buffer have an associated @dfn{action}, which can
235 be @dfn{invoked} by a standard key or mouse command.  These portions
236 are called @dfn{buttons}.  The default commands for activating a button
237 are:
239 @table @kbd
240 @item @key{RET}
241 @deffn Command widget-button-press @var{pos} &optional @var{event}
242 Invoke the button at @var{pos}, defaulting to point.
243 If point is not located on a button, invoke the binding in
244 @code{widget-global-map} (by default the global map).
245 @end deffn
247 @kindex Mouse-2 @r{(on button widgets})
248 @item Mouse-2
249 @deffn Command widget-button-click @var{event}
250 Invoke the button at the location of the mouse pointer.  If the mouse
251 pointer is located in an editable text field, invoke the binding in
252 @code{widget-global-map} (by default the global map).
253 @end deffn
254 @end table
256 There are several different kind of buttons, all of which are present in
257 the example:
259 @table @emph
260 @cindex option field tag
261 @item The Option Field Tags
262 When you invoke one of these buttons, you will be asked to choose
263 between a number of different options.  This is how you edit an option
264 field.  Option fields are created by the @code{menu-choice} widget.  In
265 the example, @samp{@b{Choose}} is an option field tag.
266 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
267 Activating these will insert or delete elements from an editable list.
268 The list is created by the @code{editable-list} widget.
269 @cindex embedded buttons
270 @item Embedded Buttons
271 The @samp{@b{_other work_}} is an example of an embedded
272 button.  Embedded buttons are not associated with any fields, but can serve
273 any purpose, such as implementing hypertext references.  They are
274 usually created by the @code{link} widget.
275 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
276 Activating one of these will convert it to the other.  This is useful
277 for implementing multiple-choice fields.  You can create them with the
278 @code{checkbox} widget.
279 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
280 Only one radio button in a @code{radio-button-choice} widget can be
281 selected at any time.  When you invoke one of the unselected radio
282 buttons, it will be selected and the previous selected radio button will
283 become unselected.
284 @item The @samp{@b{[Apply Form]}} and @samp{@b{[Reset Form]}} buttons
285 These are explicit buttons made with the @code{push-button} widget.  The
286 main difference from the @code{link} widget is that the buttons will be
287 displayed as GUI buttons when possible.
288 @end table
290 To make them easier to locate, buttons are emphasized in the buffer.
292 @deffn Face widget-button-face
293 Face used for buttons.
294 @end deffn
296 @defopt widget-mouse-face
297 Face used for highlighting a button when the mouse pointer moves across
299 @end defopt
301 @subsection Navigation
303 You can use all the normal Emacs commands to move around in a form
304 buffer, plus you will have these additional commands:
306 @table @kbd
307 @item @key{TAB}
308 @deffn Command widget-forward &optional count
309 Move point @var{count} buttons or editing fields forward.
310 @end deffn
311 @item @kbd{M-@key{TAB}}
312 @itemx @kbd{S-@key{TAB}}
313 @deffn Command widget-backward &optional count
314 Move point @var{count} buttons or editing fields backward.
315 @end deffn
316 @end table
318 @node Programming Example, Setting Up the Buffer, User Interface, Top
319 @comment  node-name,  next,  previous,  up
320 @section Programming Example
322 @cindex widgets, programming example
323 @cindex example of using widgets
324 Here is the code to implement the user interface example (@pxref{User
325 Interface}).
327 @lisp
328 (require 'widget)
330 (eval-when-compile
331   (require 'wid-edit))
333 (defvar widget-example-repeat)
335 (defun widget-example ()
336   "Create the widgets from the Widget manual."
337   (interactive)
338   (switch-to-buffer "*Widget Example*")
339   (kill-all-local-variables)
340   (make-local-variable 'widget-example-repeat)
341   (let ((inhibit-read-only t))
342     (erase-buffer))
343   (remove-overlays)
344   (widget-insert "Here is some documentation.\n\n")
345   (widget-create 'editable-field
346                  :size 13
347                  :format "Name: %v " ; Text after the field!
348                  "My Name")
349   (widget-create 'menu-choice
350                  :tag "Choose"
351                  :value "This"
352                  :help-echo "Choose me, please!"
353                  :notify (lambda (widget &rest ignore)
354                            (message "%s is a good choice!"
355                                     (widget-value widget)))
356                  '(item :tag "This option" :value "This")
357                  '(choice-item "That option")
358                  '(editable-field :menu-tag "No option" "Thus option"))
359   (widget-create 'editable-field
360                  :format "Address: %v"
361                  "Some Place\nIn some City\nSome country.")
362   (widget-insert "\nSee also ")
363   (widget-create 'link
364                  :notify (lambda (&rest ignore)
365                            (widget-value-set widget-example-repeat
366                                              '("En" "To" "Tre"))
367                            (widget-setup))
368                  "other work")
369   (widget-insert
370     " for more information.\n\nNumbers: count to three below\n")
371   (setq widget-example-repeat
372         (widget-create 'editable-list
373                        :entry-format "%i %d %v"
374                        :notify (lambda (widget &rest ignore)
375                                  (let ((old (widget-get widget
376                                                         ':example-length))
377                                        (new (length (widget-value widget))))
378                                    (unless (eq old new)
379                                      (widget-put widget ':example-length new)
380                                      (message "You can count to %d." new))))
381                        :value '("One" "Eh, two?" "Five!")
382                        '(editable-field :value "three")))
383   (widget-insert "\n\nSelect multiple:\n\n")
384   (widget-create 'checkbox t)
385   (widget-insert " This\n")
386   (widget-create 'checkbox nil)
387   (widget-insert " That\n")
388   (widget-create 'checkbox
389                  :notify (lambda (&rest ignore) (message "Tickle"))
390                  t)
391   (widget-insert " Thus\n\nSelect one:\n\n")
392   (widget-create 'radio-button-choice
393                  :value "One"
394                  :notify (lambda (widget &rest ignore)
395                            (message "You selected %s"
396                                     (widget-value widget)))
397                  '(item "One") '(item "Another One.") '(item "A Final One."))
398   (widget-insert "\n")
399   (widget-create 'push-button
400                  :notify (lambda (&rest ignore)
401                            (if (= (length (widget-value widget-example-repeat))
402                                   3)
403                                (message "Congratulation!")
404                              (error "Three was the count!")))
405                  "Apply Form")
406   (widget-insert " ")
407   (widget-create 'push-button
408                  :notify (lambda (&rest ignore)
409                            (widget-example))
410                  "Reset Form")
411   (widget-insert "\n")
412   (use-local-map widget-keymap)
413   (widget-setup))
414 @end lisp
416 @node Setting Up the Buffer, Basic Types, Programming Example, Top
417 @comment  node-name,  next,  previous,  up
418 @section Setting Up the Buffer
420 Widgets are created with @code{widget-create}, which returns a
421 @dfn{widget} object.  This object can be queried and manipulated by
422 other widget functions, until it is deleted with @code{widget-delete}.
423 After the widgets have been created, @code{widget-setup} must be called
424 to enable them.
426 @defun widget-create type [ keyword argument ]@dots{}
427 Create and return a widget of type @var{type}.
428 The syntax for the @var{type} argument is described in @ref{Basic Types}.
430 The keyword arguments can be used to overwrite the keyword arguments
431 that are part of @var{type}.
432 @end defun
434 @defun widget-delete widget
435 Delete @var{widget} and remove it from the buffer.
436 @end defun
438 @defun widget-setup
439 Set up a buffer to support widgets.
441 This should be called after creating all the widgets and before allowing
442 the user to edit them.
443 @refill
444 @end defun
446 If you want to insert text outside the widgets in the form, the
447 recommended way to do that is with @code{widget-insert}.
449 @defun widget-insert
450 Insert the arguments, either strings or characters, at point.
451 The inserted text will be read-only.
452 @end defun
454 There is a standard widget keymap which you might find useful.
456 @findex widget-button-press
457 @findex widget-button-click
458 @defvr Const widget-keymap
459 A keymap with the global keymap as its parent.@*
460 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
461 @code{widget-backward}, respectively.  @key{RET} and @kbd{Mouse-2}
462 are bound to @code{widget-button-press} and
463 @code{widget-button-click}.@refill
464 @end defvr
466 @defvar widget-global-map
467 Keymap used by @code{widget-button-press} and @code{widget-button-click}
468 when not on a button.  By default this is @code{global-map}.
469 @end defvar
471 @node Basic Types, Sexp Types, Setting Up the Buffer, Top
472 @comment  node-name,  next,  previous,  up
473 @section Basic Types
475 This is the general syntax of a type specification:
477 @example
478 @var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
479      |   @var{name}
480 @end example
482 Where, @var{name} is a widget name, @var{keyword} is the name of a
483 property, @var{argument} is the value of the property, and @var{args}
484 are interpreted in a widget specific way.
486 @cindex keyword arguments
487 The following keyword arguments apply to all widgets:
489 @table @code
490 @vindex value@r{ keyword}
491 @item :value
492 The initial value for widgets of this type.
494 @vindex format@r{ keyword}
495 @item :format
496 This string will be inserted in the buffer when you create a widget.
497 The following @samp{%} escapes are available:
499 @table @samp
500 @item %[
501 @itemx %]
502 The text inside will be marked as a button.
504 By default, the text will be shown in @code{widget-button-face}, and
505 surrounded by brackets.
507 @defopt widget-button-prefix
508 String to prefix buttons.
509 @end defopt
511 @defopt widget-button-suffix
512 String to suffix buttons.
513 @end defopt
515 @item %@{
516 @itemx %@}
517 The text inside will be displayed with the face specified by
518 @code{:sample-face}.
520 @item %v
521 This will be replaced with the buffer representation of the widget's
522 value.  What this is depends on the widget type.
524 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
525 must be preceded by some other text in the format string (if specified).
527 @item %d
528 Insert the string specified by @code{:doc} here.
530 @item %h
531 Like @samp{%d}, with the following modifications: If the documentation
532 string is more than one line, it will add a button which will toggle
533 between showing only the first line, and showing the full text.
534 Furthermore, if there is no @code{:doc} property in the widget, it will
535 instead examine the @code{:documentation-property} property.  If it is a
536 lambda expression, it will be called with the widget's value as an
537 argument, and the result will be used as the documentation text.
539 @item %t
540 Insert the string specified by @code{:tag} here, or the @code{princ}
541 representation of the value if there is no tag.
543 @item %%
544 Insert a literal @samp{%}.
545 @end table
547 @vindex button-face@r{ keyword}
548 @item :button-face
549 Face used to highlight text inside %[ %] in the format.
551 @vindex button-prefix@r{ keyword}
552 @vindex button-suffix@r{ keyword}
553 @item :button-prefix
554 @itemx :button-suffix
555 Text around %[ %] in the format.
557 These can be
558 @table @emph
559 @item nil
560 No text is inserted.
562 @item a string
563 The string is inserted literally.
565 @item a symbol
566 The value of the symbol is expanded according to this table.
567 @end table
569 @vindex doc@r{ keyword}
570 @item :doc
571 The string inserted by the @samp{%d} escape in the format
572 string.
574 @vindex tag@r{ keyword}
575 @item :tag
576 The string inserted by the @samp{%t} escape in the format
577 string.
579 @vindex tag-glyph@r{ keyword}
580 @item :tag-glyph
581 Name of image to use instead of the string specified by @code{:tag} on
582 Emacsen that supports it.
584 @vindex help-echo@r{ keyword}
585 @item :help-echo
586 Specifies how to display a message whenever you move to the widget with
587 either @code{widget-forward} or @code{widget-backward} or move the mouse
588 over it (using the standard @code{help-echo} mechanism).  The argument
589 is either a string to display, a function of one argument, the widget,
590 which should return a string to display, or a form that evaluates to
591 such a string.
593 @vindex follow-link@r{ keyword}
594 @item :follow-link
595 Specifies how to interpret a @key{mouse-1} click on the widget.
596 @xref{Links and Mouse-1,,, elisp, the Emacs Lisp Reference Manual}.
598 @vindex indent@r{ keyword}
599 @item :indent
600 An integer indicating the absolute number of spaces to indent children
601 of this widget.
603 @vindex offset@r{ keyword}
604 @item :offset
605 An integer indicating how many extra spaces to add to the widget's
606 grandchildren compared to this widget.
608 @vindex extra-offset@r{ keyword}
609 @item :extra-offset
610 An integer indicating how many extra spaces to add to the widget's
611 children compared to this widget.
613 @vindex notify@r{ keyword}
614 @item :notify
615 A function called each time the widget or a nested widget is changed.
616 The function is called with two or three arguments.  The first argument
617 is the widget itself, the second argument is the widget that was
618 changed, and the third argument is the event leading to the change, if
619 any.
621 @vindex menu-tag@r{ keyword}
622 @item :menu-tag
623 Tag used in the menu when the widget is used as an option in a
624 @code{menu-choice} widget.
626 @vindex menu-tag-get@r{ keyword}
627 @item :menu-tag-get
628 Function used for finding the tag when the widget is used as an option
629 in a @code{menu-choice} widget.  By default, the tag used will be either the
630 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
631 representation of the @code{:value} property if not.
633 @vindex match@r{ keyword}
634 @item :match
635 Should be a function called with two arguments, the widget and a value,
636 and returning non-@code{nil} if the widget can represent the specified value.
638 @vindex validate@r{ keyword}
639 @item :validate
640 A function which takes a widget as an argument, and returns @code{nil}
641 if the widget's current value is valid for the widget.  Otherwise it
642 should return the widget containing the invalid data, and set that
643 widget's @code{:error} property to a string explaining the error.
645 The following predefined function can be used:
647 @defun widget-children-validate widget
648 All the @code{:children} of @var{widget} must be valid.
649 @end defun
651 @vindex tab-order@r{ keyword}
652 @item :tab-order
653 Specify the order in which widgets are traversed with
654 @code{widget-forward} or @code{widget-backward}.  This is only partially
655 implemented.
657 @enumerate a
658 @item
659 Widgets with tabbing order @code{-1} are ignored.
661 @item
662 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
663 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
664 whichever comes first.
666 @item
667 When on a widget with no tabbing order specified, go to the next widget
668 in the buffer with a positive tabbing order, or @code{nil}
669 @end enumerate
671 @vindex parent@r{ keyword}
672 @item :parent
673 The parent of a nested widget (e.g.@: a @code{menu-choice} item or an
674 element of a @code{editable-list} widget).
676 @vindex sibling-args@r{ keyword}
677 @item :sibling-args
678 This keyword is only used for members of a @code{radio-button-choice} or
679 @code{checklist}.  The value should be a list of extra keyword
680 arguments, which will be used when creating the @code{radio-button} or
681 @code{checkbox} associated with this item.
683 @end table
685 @deffn {User Option} widget-glyph-directory
686 Directory where glyphs are found.
687 Widget will look here for a file with the same name as specified for the
688 image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
689 @end deffn
691 @deffn{User Option} widget-glyph-enable
692 If non-@code{nil}, allow glyphs to appear on displays where they are supported.
693 @end deffn
696 @menu
697 * link::
698 * url-link::
699 * info-link::
700 * push-button::
701 * editable-field::
702 * text::
703 * menu-choice::
704 * radio-button-choice::
705 * item::
706 * choice-item::
707 * toggle::
708 * checkbox::
709 * checklist::
710 * editable-list::
711 * group::
712 @end menu
714 @node link, url-link, Basic Types, Basic Types
715 @comment  node-name,  next,  previous,  up
716 @subsection The @code{link} Widget
717 @findex link@r{ widget}
719 Syntax:
721 @example
722 @var{type} ::= (link [@var{keyword} @var{argument}]...  [ @var{value} ])
723 @end example
725 The @var{value}, if present, is used to initialize the @code{:value}
726 property.  The value should be a string, which will be inserted in the
727 buffer.
729 By default the link will be shown in brackets.
731 @defopt widget-link-prefix
732 String to prefix links.
733 @end defopt
735 @defopt widget-link-suffix
736 String to suffix links.
737 @end defopt
739 @node url-link, info-link, link, Basic Types
740 @comment  node-name,  next,  previous,  up
741 @subsection The @code{url-link} Widget
742 @findex url-link@r{ widget}
744 Syntax:
746 @example
747 @var{type} ::= (url-link [@var{keyword} @var{argument}]...  @var{url})
748 @end example
750 @findex browse-url-browser-function@r{, and @code{url-link} widget}
751 When this link is invoked, the @acronym{WWW} browser specified by
752 @code{browse-url-browser-function} will be called with @var{url}.
754 @node info-link, push-button, url-link, Basic Types
755 @comment  node-name,  next,  previous,  up
756 @subsection The @code{info-link} Widget
757 @findex info-link@r{ widget}
759 Syntax:
761 @example
762 @var{type} ::= (info-link [@var{keyword} @var{argument}]...  @var{address})
763 @end example
765 When this link is invoked, the built-in Info reader is started on
766 @var{address}.
768 @node  push-button, editable-field, info-link, Basic Types
769 @comment  node-name,  next,  previous,  up
770 @subsection The @code{push-button} Widget
771 @findex push-button@r{ widget}
773 Syntax:
775 @example
776 @var{type} ::= (push-button [@var{keyword} @var{argument}]...  [ @var{value} ])
777 @end example
779 The @var{value}, if present, is used to initialize the @code{:value}
780 property.  The value should be a string, which will be inserted in the
781 buffer.
783 By default the tag will be shown in brackets.
785 @defopt widget-push-button-prefix
786 String to prefix push buttons.
787 @end defopt
789 @defopt widget-push-button-suffix
790 String to suffix push buttons.
791 @end defopt
793 @node editable-field, text, push-button, Basic Types
794 @comment  node-name,  next,  previous,  up
795 @subsection The @code{editable-field} Widget
796 @findex editable-field@r{ widget}
798 Syntax:
800 @example
801 @var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{value} ])
802 @end example
804 The @var{value}, if present, is used to initialize the @code{:value}
805 property.  The value should be a string, which will be inserted in the
806 field.  This widget will match all string values.
808 The following extra properties are recognized:
810 @table @code
811 @vindex size@r{ keyword}
812 @item :size
813 The width of the editable field.@*
814 By default the field will reach to the end of the line.
816 @vindex value-face@r{ keyword}
817 @item :value-face
818 Face used for highlighting the editable field.  Default is
819 @code{widget-field-face}, see @ref{User Interface}.
821 @vindex secret@r{ keyword}
822 @item :secret
823 Character used to display the value.  You can set this to e.g.@: @code{?*}
824 if the field contains a password or other secret information.  By
825 default, this is @code{nil}, and the value is not secret.
827 @vindex valid-regexp@r{ keyword}
828 @item :valid-regexp
829 By default the @code{:validate} function will match the content of the
830 field with the value of this attribute.  The default value is @code{""}
831 which matches everything.
833 @vindex keymap@r{ keyword}
834 @vindex widget-field-keymap
835 @item :keymap
836 Keymap used in the editable field.  The default value is
837 @code{widget-field-keymap}, which allows you to use all the normal
838 editing commands, even if the buffer's major mode suppresses some of
839 them.  Pressing @key{RET} invokes the function specified by
840 @code{:action}.
841 @end table
843 @node text, menu-choice, editable-field, Basic Types
844 @comment  node-name,  next,  previous,  up
845 @subsection The @code{text} Widget
846 @findex text@r{ widget}
848 @vindex widget-text-keymap
849 This is just like @code{editable-field}, but intended for multiline text
850 fields.  The default @code{:keymap} is @code{widget-text-keymap}, which
851 does not rebind the @key{RET} key.
853 @node menu-choice, radio-button-choice, text, Basic Types
854 @comment  node-name,  next,  previous,  up
855 @subsection The @code{menu-choice} Widget
856 @findex menu-choice@r{ widget}
858 Syntax:
860 @example
861 @var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
862 @end example
864 The @var{type} argument represents each possible choice.  The widget's
865 value will be that of the chosen @var{type} argument.  This widget will
866 match any value matching at least one of the specified @var{type}
867 arguments.
869 @table @code
870 @vindex void@r{ keyword}
871 @item :void
872 Widget type used as a fallback when the value does not match any of the
873 specified @var{type} arguments.
875 @vindex case-fold@r{ keyword}
876 @item :case-fold
877 Set this to @code{nil} if you don't want to ignore case when prompting for a
878 choice through the minibuffer.
880 @vindex children@r{ keyword}
881 @item :children
882 A list whose @sc{car} is the widget representing the currently chosen
883 type in the buffer.
885 @vindex choice@r{ keyword}
886 @item :choice
887 The current chosen type.
889 @vindex args@r{ keyword}
890 @item :args
891 The list of types.
892 @end table
894 @node radio-button-choice, item, menu-choice, Basic Types
895 @comment  node-name,  next,  previous,  up
896 @subsection The @code{radio-button-choice} Widget
897 @findex radio-button-choice@r{ widget}
899 Syntax:
901 @example
902 @var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]...  @var{type} ... )
903 @end example
905 The component types specify the choices, with one radio button for
906 each.  The widget's value will be that of the chosen @var{type}
907 argument.  This widget matches any value that matches at least one of
908 the specified @var{type} arguments.
910 The following extra properties are recognized.
912 @table @code
913 @vindex entry-format@r{ keyword}
914 @item :entry-format
915 This string will be inserted for each entry in the list.
916 The following @samp{%} escapes are available:
917 @table @samp
918 @item %v
919 Replace with the buffer representation of the @var{type} widget.
920 @item %b
921 Replace with the radio button.
922 @item %%
923 Insert a literal @samp{%}.
924 @end table
926 @vindex button-args@r{ keyword}
927 @item :button-args
928 A list of keywords to pass to the radio buttons.  Useful for setting
929 e.g.@: the @samp{:help-echo} for each button.
931 @vindex buttons@r{ keyword}
932 @item :buttons
933 The widgets representing the radio buttons.
935 @vindex children@r{ keyword}
936 @item :children
937 The widgets representing each type.
939 @vindex choice@r{ keyword}
940 @item :choice
941 The current chosen type
943 @vindex args@r{ keyword}
944 @item :args
945 The list of types.
946 @end table
948 You can add extra radio button items to a @code{radio-button-choice}
949 widget after it has been created with the function
950 @code{widget-radio-add-item}.
952 @defun widget-radio-add-item widget type
953 Add to @code{radio-button-choice} widget @var{widget} a new radio button
954 item of type @var{type}.
955 @end defun
957 Please note that such items added after the @code{radio-button-choice}
958 widget has been created will @strong{not} be properly destructed when
959 you call @code{widget-delete}.
961 @node item, choice-item, radio-button-choice, Basic Types
962 @comment  node-name,  next,  previous,  up
963 @subsection The @code{item} Widget
964 @findex item@r{ widget}
966 Syntax:
968 @example
969 @var{item} ::= (item [@var{keyword} @var{argument}]... @var{value})
970 @end example
972 The @var{value}, if present, is used to initialize the @code{:value}
973 property.  The value should be a string, which will be inserted in the
974 buffer.  This widget will only match the specified value.
976 @node choice-item, toggle, item, Basic Types
977 @comment  node-name,  next,  previous,  up
978 @subsection The @code{choice-item} Widget
979 @findex choice-item@r{ widget}
981 Syntax:
983 @example
984 @var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{value})
985 @end example
987 The @var{value}, if present, is used to initialize the @code{:value}
988 property.  The value should be a string, which will be inserted in the
989 buffer as a button.  Activating the button of a @code{choice-item} is
990 equivalent to activating the parent widget.  This widget will only match
991 the specified value.
993 @node toggle, checkbox, choice-item, Basic Types
994 @comment  node-name,  next,  previous,  up
995 @subsection The @code{toggle} Widget
996 @findex toggle@r{ widget}
998 Syntax:
1000 @example
1001 @var{type} ::= (toggle [@var{keyword} @var{argument}]...)
1002 @end example
1004 The widget has two possible states, @samp{on} and @samp{off}, which
1005 correspond to a @code{t} or @code{nil} value, respectively.
1007 The following extra properties are recognized:
1009 @table @code
1010 @item :on
1011 A string representing the @samp{on} state.  By default the string
1012 @samp{on}.
1013 @item :off
1014 A string representing the @samp{off} state.  By default the string
1015 @samp{off}.
1016 @vindex on-glyph@r{ keyword}
1017 @item :on-glyph
1018 Name of a glyph to be used instead of the @samp{:on} text string, on
1019 emacsen that supports this.
1020 @vindex off-glyph@r{ keyword}
1021 @item :off-glyph
1022 Name of a glyph to be used instead of the @samp{:off} text string, on
1023 emacsen that supports this.
1024 @end table
1026 @node checkbox, checklist, toggle, Basic Types
1027 @comment  node-name,  next,  previous,  up
1028 @subsection The @code{checkbox} Widget
1029 @findex checkbox@r{ widget}
1031 This widget has two possible states, @samp{selected} and
1032 @samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
1034 Syntax:
1036 @example
1037 @var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
1038 @end example
1040 @node checklist, editable-list, checkbox, Basic Types
1041 @comment  node-name,  next,  previous,  up
1042 @subsection The @code{checklist} Widget
1043 @findex checklist@r{ widget}
1045 Syntax:
1047 @example
1048 @var{type} ::= (checklist [@var{keyword} @var{argument}]...  @var{type} ... )
1049 @end example
1051 The @var{type} arguments represent each checklist item.  The widget's
1052 value will be a list containing the values of all checked @var{type}
1053 arguments.  The checklist widget will match a list whose elements all
1054 match at least one of the specified @var{type} arguments.
1056 The following extra properties are recognized:
1058 @table @code
1059 @vindex entry-format@r{ keyword}
1060 @item :entry-format
1061 This string will be inserted for each entry in the list.
1062 The following @samp{%} escapes are available:
1063 @table @samp
1064 @item %v
1065 Replaced with the buffer representation of the @var{type} widget.
1066 @item %b
1067 Replace with the checkbox.
1068 @item %%
1069 Insert a literal @samp{%}.
1070 @end table
1072 @vindex greedy@r{ keyword}
1073 @item :greedy
1074 Usually a checklist will only match if the items are in the exact
1075 sequence given in the specification.  By setting @code{:greedy} to
1076 non-@code{nil}, it will allow the items to come in any sequence.
1077 However, if you extract the value they will be in the sequence given
1078 in the checklist, i.e.@: the original sequence is forgotten.
1080 @vindex button-args@r{ keyword}
1081 @item :button-args
1082 A list of keywords to pass to the checkboxes.  Useful for setting
1083 e.g.@: the @samp{:help-echo} for each checkbox.
1085 @vindex buttons@r{ keyword}
1086 @item :buttons
1087 The widgets representing the checkboxes.
1089 @vindex children@r{ keyword}
1090 @item :children
1091 The widgets representing each type.
1093 @vindex args@r{ keyword}
1094 @item :args
1095 The list of types.
1096 @end table
1098 @node editable-list, group, checklist, Basic Types
1099 @comment  node-name,  next,  previous,  up
1100 @subsection The @code{editable-list} Widget
1101 @findex editable-list@r{ widget}
1103 Syntax:
1105 @example
1106 @var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{type})
1107 @end example
1109 The value is a list, where each member represents one widget of type
1110 @var{type}.
1112 The following extra properties are recognized:
1114 @table @code
1115 @vindex entry-format@r{ keyword}
1116 @item :entry-format
1117 This string will be inserted for each entry in the list.
1118 The following @samp{%} escapes are available:
1119 @table @samp
1120 @item %v
1121 This will be replaced with the buffer representation of the @var{type}
1122 widget.
1123 @item %i
1124 Insert the @b{[INS]} button.
1125 @item %d
1126 Insert the @b{[DEL]} button.
1127 @item %%
1128 Insert a literal @samp{%}.
1129 @end table
1131 @vindex insert-button-args@r{ keyword}
1132 @item :insert-button-args
1133 A list of keyword arguments to pass to the insert buttons.
1135 @vindex delete-button-args@r{ keyword}
1136 @item :delete-button-args
1137 A list of keyword arguments to pass to the delete buttons.
1139 @vindex append-button-args@r{ keyword}
1140 @item :append-button-args
1141 A list of keyword arguments to pass to the trailing insert button.
1143 @vindex buttons@r{ keyword}
1144 @item :buttons
1145 The widgets representing the insert and delete buttons.
1147 @vindex children@r{ keyword}
1148 @item :children
1149 The widgets representing the elements of the list.
1151 @vindex args@r{ keyword}
1152 @item :args
1153 List whose @sc{car} is the type of the list elements.
1154 @end table
1156 @node group,  , editable-list, Basic Types
1157 @comment  node-name,  next,  previous,  up
1158 @subsection The @code{group} Widget
1159 @findex group@r{ widget}
1161 This widget simply group other widgets together.
1163 Syntax:
1165 @example
1166 @var{type} ::= (group [@var{keyword} @var{argument}]... @var{type}...)
1167 @end example
1169 The value is a list, with one member for each @var{type}.
1171 @node Sexp Types, Widget Properties, Basic Types, Top
1172 @comment
1173 @section Sexp Types
1174 @cindex sexp types
1176 A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp
1177 for short, are also available.  These basically fall in several
1178 categories described in this section.
1180 @menu
1181 * constants::
1182 * generic::
1183 * atoms::
1184 * composite::
1185 @end menu
1187 @node constants, generic, Sexp Types, Sexp Types
1188 @comment  node-name,  next,  previous,  up
1189 @subsection The Constant Widgets
1190 @cindex constant widgets
1192 The @code{const} widget can contain any Lisp expression, but the user is
1193 prohibited from editing it, which is mainly useful as a component of one
1194 of the composite widgets.
1196 The syntax for the @code{const} widget is:
1198 @example
1199 @var{type} ::= (const [@var{keyword} @var{argument}]...  [ @var{value} ])
1200 @end example
1202 The @var{value}, if present, is used to initialize the @code{:value}
1203 property and can be any s-expression.
1205 @deffn Widget const
1206 This will display any valid s-expression in an immutable part of the
1207 buffer.
1208 @end deffn
1210 There are two variations of the @code{const} widget, namely
1211 @code{variable-item} and @code{function-item}.  These should contain a
1212 symbol with a variable or function binding.  The major difference from
1213 the @code{const} widget is that they will allow the user to see the
1214 variable or function documentation for the symbol.
1216 @deffn Widget variable-item
1217 An immutable symbol that is bound as a variable.
1218 @end deffn
1220 @deffn Widget function-item
1221 An immutable symbol that is bound as a function.
1222 @end deffn
1224 @node generic, atoms, constants, Sexp Types
1225 @comment  node-name,  next,  previous,  up
1226 @subsection Generic Sexp Widget
1227 @cindex generic sexp widget
1229 The @code{sexp} widget can contain any Lisp expression, and allows the
1230 user to edit it inline in the buffer.
1232 The syntax for the @code{sexp} widget is:
1234 @example
1235 @var{type} ::= (sexp [@var{keyword} @var{argument}]...  [ @var{value} ])
1236 @end example
1238 @deffn Widget sexp
1239 This will allow you to edit any valid s-expression in an editable buffer
1240 field.
1242 The @code{sexp} widget takes the same keyword arguments as the
1243 @code{editable-field} widget.  @xref{editable-field}.
1244 @end deffn
1246 @node atoms, composite, generic, Sexp Types
1247 @comment  node-name,  next,  previous,  up
1248 @subsection Atomic Sexp Widgets
1249 @cindex atomic sexp widget
1251 The atoms are s-expressions that do not consist of other s-expressions.
1252 For example, a string, a file name, or a symbol are atoms, while a list
1253 is a composite type.  You can edit the value of an atom with the
1254 following widgets.
1256 The syntax for all the atoms are:
1258 @example
1259 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]...  [ @var{value} ])
1260 @end example
1262 The @var{value}, if present, is used to initialize the @code{:value}
1263 property and must be an expression of the same type as the widget.
1264 That is, the string widget can only be initialized with a string.
1266 All the atom widgets take the same keyword arguments as the
1267 @code{editable-field} widget.  @xref{editable-field}.
1269 @deffn Widget string
1270 Allows you to edit a string in an editable field.
1271 @end deffn
1273 @deffn Widget regexp
1274 Allows you to edit a regular expression in an editable field.
1275 @end deffn
1277 @deffn Widget character
1278 Allows you to enter a character in an editable field.
1279 @end deffn
1281 @deffn Widget file
1282 Allows you to edit a file name in an editable field.
1284 Keywords:
1285 @table @code
1286 @vindex must-match@r{ keyword}
1287 @item :must-match
1288 If this is set to non-@code{nil}, only existing file names will be
1289 allowed in the minibuffer.
1290 @end table
1291 @end deffn
1293 @deffn Widget directory
1294 Allows you to edit a directory name in an editable field.
1295 Similar to the @code{file} widget.
1296 @end deffn
1298 @deffn Widget symbol
1299 Allows you to edit a Lisp symbol in an editable field.
1300 @end deffn
1302 @deffn Widget function
1303 Allows you to edit a lambda expression, or a function name with completion.
1304 @end deffn
1306 @deffn Widget variable
1307 Allows you to edit a variable name, with completion.
1308 @end deffn
1310 @deffn Widget integer
1311 Allows you to edit an integer in an editable field.
1312 @end deffn
1314 @deffn Widget number
1315 Allows you to edit a number in an editable field.
1316 @end deffn
1318 @deffn Widget boolean
1319 Allows you to edit a boolean.  In Lisp this means a variable which is
1320 either @code{nil} meaning false, or non-@code{nil} meaning true.
1321 @end deffn
1324 @node composite,  , atoms, Sexp Types
1325 @comment  node-name,  next,  previous,  up
1326 @subsection Composite Sexp Widgets
1327 @cindex composite sexp widgets
1329 The syntax for the composite widget construct is:
1331 @example
1332 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]...  @var{component}...)
1333 @end example
1335 @noindent
1336 where each @var{component} must be a widget type.  Each component widget
1337 will be displayed in the buffer, and will be editable by the user.
1339 @deffn Widget cons
1340 The value of a @code{cons} widget must be a cons-cell whose @sc{car}
1341 and @sc{cdr} have two specified types.  It uses this syntax:
1343 @example
1344 @var{type} ::= (cons [@var{keyword} @var{argument}]...  @var{car-type} @var{cdr-type})
1345 @end example
1346 @end deffn
1348 @deffn Widget choice
1349 The value matched by a @code{choice} widget must have one of a fixed
1350 set of types.  The widget's syntax is as follows:
1352 @example
1353 @var{type} ::= (choice [@var{keyword} @var{argument}]...  @var{type} ... )
1354 @end example
1356 The value of a @code{choice} widget can be anything that matches any of the
1357 @var{types}.
1358 @end deffn
1360 @deffn Widget list
1361 The value of a @code{list} widget must be a list whose element types
1362 match the specified component types:
1364 @example
1365 @var{type} ::= (list [@var{keyword} @var{argument}]...  @var{component-type}...)
1366 @end example
1368 Thus, @code{(list string number)} matches lists of two elements,
1369 the first being a string and the second being a number.
1370 @end deffn
1372 @deffn Widget vector
1373 The @code{vector} widget is like the @code{list} widget but matches
1374 vectors instead of lists.  Thus, @code{(vector string number)} matches
1375 vectors of two elements, the first being a string and the second being
1376 a number.
1377 @end deffn
1379 The above suffice for specifying fixed size lists and vectors.  To get
1380 variable length lists and vectors, you can use a @code{choice},
1381 @code{set}, or @code{repeat} widget together with the @code{:inline}
1382 keyword.  If any component of a composite widget has the
1383 @code{:inline} keyword set, its value must be a list which will then
1384 be spliced into the composite.  For example, to specify a list whose
1385 first element must be a file name, and whose remaining elements should
1386 either be the symbol @code{t} or two strings (file names), you can use
1387 the following widget specification:
1389 @example
1390 (list file
1391       (choice (const t)
1392               (list :inline t
1393                     :value ("foo" "bar")
1394                     string string)))
1395 @end example
1397 The value of a widget of this type will either have the form
1398 @code{(file t)} or @code{(file @var{string} @var{string})}.
1400 This concept of @code{:inline} may be hard to understand.  It was
1401 certainly hard to implement, so instead of confusing you more by
1402 trying to explain it here, I'll just suggest you meditate over it for
1403 a while.
1405 @deffn Widget set
1406 Specifies a type whose values are the lists whose elements all belong
1407 to a given set.  The order of elements of the list is not significant.
1408 Here's the syntax:
1410 @example
1411 @var{type} ::= (set [@var{keyword} @var{argument}]...  @var{permitted-element} ... )
1412 @end example
1414 Use @code{const} to specify each permitted element, like this:
1415 @code{(set (const a) (const b))}.
1416 @end deffn
1418 @deffn Widget repeat
1419 Specifies a list of any number of elements that fit a certain type.
1421 @example
1422 @var{type} ::= (repeat [@var{keyword} @var{argument}]...  @var{type})
1423 @end example
1424 @end deffn
1426 @node Widget Properties, Defining New Widgets, Sexp Types, Top
1427 @comment  node-name,  next,  previous,  up
1428 @section Properties
1429 @cindex properties of widgets
1430 @cindex widget properties
1432 You can examine or set the value of a widget by using the widget object
1433 that was returned by @code{widget-create}.
1435 @defun widget-value widget
1436 Return the current value contained in @var{widget}.
1437 It is an error to call this function on an uninitialized widget.
1438 @end defun
1440 @defun widget-value-set widget value
1441 Set the value contained in @var{widget} to @var{value}.
1442 It is an error to call this function with an invalid @var{value}.
1443 @end defun
1445 @strong{Important:} You @emph{must} call @code{widget-setup} after
1446 modifying the value of a widget before the user is allowed to edit the
1447 widget again.  It is enough to call @code{widget-setup} once if you
1448 modify multiple widgets.  This is currently only necessary if the widget
1449 contains an editing field, but may be necessary for other widgets in the
1450 future.
1452 If your application needs to associate some information with the widget
1453 objects, for example a reference to the item being edited, it can be
1454 done with @code{widget-put} and @code{widget-get}.  The property names
1455 must begin with a @samp{:}.
1457 @defun widget-put widget property value
1458 In @var{widget} set @var{property} to @var{value}.
1459 @var{property} should be a symbol, while @var{value} can be anything.
1460 @end defun
1462 @defun widget-get widget property
1463 In @var{widget} return the value for @var{property}.
1464 @var{property} should be a symbol, the value is what was last set by
1465 @code{widget-put} for @var{property}.
1466 @end defun
1468 @defun widget-member widget property
1469 Non-@code{nil} if @var{widget} has a value (even @code{nil}) for
1470 property @var{property}.
1471 @end defun
1473 Occasionally it can be useful to know which kind of widget you have,
1474 i.e.@: the name of the widget type you gave when the widget was created.
1476 @defun widget-type widget
1477 Return the name of @var{widget}, a symbol.
1478 @end defun
1480 @cindex active widget
1481 @cindex inactive widget
1482 @cindex activate a widget
1483 @cindex deactivate a widget
1484 Widgets can be in two states: active, which means they are modifiable by
1485 the user, or inactive, which means they cannot be modified by the user.
1486 You can query or set the state with the following code:
1488 @lisp
1489 ;; Examine if @var{widget} is active or not.
1490 (if (widget-apply @var{widget} :active)
1491     (message "Widget is active.")
1492   (message "Widget is inactive.")
1494 ;; Make @var{widget} inactive.
1495 (widget-apply @var{widget} :deactivate)
1497 ;; Make @var{widget} active.
1498 (widget-apply @var{widget} :activate)
1499 @end lisp
1501 A widget is inactive if it, or any of its ancestors (found by
1502 following the @code{:parent} link), have been deactivated.  To make sure
1503 a widget is really active, you must therefore activate both it and
1504 all its ancestors.
1506 @lisp
1507 (while widget
1508   (widget-apply widget :activate)
1509   (setq widget (widget-get widget :parent)))
1510 @end lisp
1512 You can check if a widget has been made inactive by examining the value
1513 of the @code{:inactive} keyword.  If this is non-@code{nil}, the widget itself
1514 has been deactivated.  This is different from using the @code{:active}
1515 keyword, in that the latter tells you if the widget @strong{or} any of
1516 its ancestors have been deactivated.  Do not attempt to set the
1517 @code{:inactive} keyword directly.  Use the @code{:activate}
1518 @code{:deactivate} keywords instead.
1521 @node Defining New Widgets, Widget Browser, Widget Properties, Top
1522 @comment  node-name,  next,  previous,  up
1523 @section Defining New Widgets
1524 @cindex new widgets
1525 @cindex defining new widgets
1527 You can define specialized widgets with @code{define-widget}.  It allows
1528 you to create a shorthand for more complex widgets, including specifying
1529 component widgets and new default values for the keyword
1530 arguments.
1532 @defun define-widget name class doc &rest args
1533 Define a new widget type named @var{name} from @code{class}.
1535 @var{name} and class should both be symbols, @code{class} should be one
1536 of the existing widget types.
1538 The third argument @var{doc} is a documentation string for the widget.
1540 After the new widget has been defined, the following two calls will
1541 create identical widgets:
1543 @itemize @bullet
1544 @item
1545 @lisp
1546 (widget-create @var{name})
1547 @end lisp
1549 @item
1550 @lisp
1551 (apply widget-create @var{class} @var{args})
1552 @end lisp
1553 @end itemize
1555 @end defun
1557 Using @code{define-widget} just stores the definition of the widget type
1558 in the @code{widget-type} property of @var{name}, which is what
1559 @code{widget-create} uses.
1561 If you only want to specify defaults for keywords with no complex
1562 conversions, you can use @code{identity} as your conversion function.
1564 The following additional keyword arguments are useful when defining new
1565 widgets:
1566 @table @code
1567 @vindex convert-widget@r{ keyword}
1568 @item :convert-widget
1569 Function to convert a widget type before creating a widget of that
1570 type.  It takes a widget type as an argument, and returns the converted
1571 widget type.  When a widget is created, this function is called for the
1572 widget type and all the widget's parent types, most derived first.
1574 The following predefined functions can be used here:
1576 @defun widget-types-convert-widget widget
1577 Convert @code{:args} as widget types in @var{widget}.
1578 @end defun
1580 @defun widget-value-convert-widget widget
1581 Initialize @code{:value} from @code{:args} in @var{widget}.
1582 @end defun
1584 @vindex copy@r{ keyword}
1585 @item :copy
1586 Function to deep copy a widget type.  It takes a shallow copy of the
1587 widget type as an argument (made by @code{copy-sequence}), and returns a
1588 deep copy.  The purpose of this is to avoid having different instances
1589 of combined widgets share nested attributes.
1591 The following predefined functions can be used here:
1593 @defun widget-types-copy widget
1594 Copy @code{:args} as widget types in @var{widget}.
1595 @end defun
1597 @vindex value-to-internal@r{ keyword}
1598 @item :value-to-internal
1599 Function to convert the value to the internal format.  The function
1600 takes two arguments, a widget and an external value, and returns the
1601 internal value.  The function is called on the present @code{:value}
1602 when the widget is created, and on any value set later with
1603 @code{widget-value-set}.
1605 @vindex value-to-external@r{ keyword}
1606 @item :value-to-external
1607 Function to convert the value to the external format.  The function
1608 takes two arguments, a widget and an internal value, and returns the
1609 external value.  The function is called on the present @code{:value}
1610 when the widget is created, and on any value set later with
1611 @code{widget-value-set}.
1613 @vindex create@r{ keyword}
1614 @item :create
1615 Function to create a widget from scratch.  The function takes one
1616 argument, a widget type, and creates a widget of that type, inserts it
1617 in the buffer, and returns a widget object.
1619 @vindex delete@r{ keyword}
1620 @item :delete
1621 Function to delete a widget.  The function takes one argument, a widget,
1622 and should remove all traces of the widget from the buffer.
1624 The default value is:
1626 @defun widget-default-delete widget
1627 Remove @var{widget} from the buffer.
1628 Delete all @code{:children} and @code{:buttons} in @var{widget}.
1629 @end defun
1631 In most cases you should not change this value, but instead use
1632 @code{:value-delete} to make any additional cleanup.
1634 @vindex value-create@r{ keyword}
1635 @item :value-create
1636 Function to expand the @samp{%v} escape in the format string.  It will
1637 be called with the widget as its argument and should insert a
1638 representation of the widget's value in the buffer.
1640 Nested widgets should be listed in @code{:children} or @code{:buttons}
1641 to make sure they are automatically deleted.
1643 @vindex value-delete@r{ keyword}
1644 @item :value-delete
1645 Should remove the representation of the widget's value from the buffer.
1646 It will be called with the widget as its argument.  It doesn't have to
1647 remove the text, but it should release markers and delete nested widgets
1648 if these are not listed in @code{:children} or @code{:buttons}.
1650 @vindex value-get@r{ keyword}
1651 @item :value-get
1652 Function to extract the value of a widget, as it is displayed in the
1653 buffer.
1655 The following predefined function can be used here:
1657 @defun widget-value-value-get widget
1658 Return the @code{:value} property of @var{widget}.
1659 @end defun
1661 @vindex format-handler@r{ keyword}
1662 @item :format-handler
1663 Function to handle unknown @samp{%} escapes in the format string.  It
1664 will be called with the widget and the character that follows the
1665 @samp{%} as arguments.  You can set this to allow your widget to handle
1666 non-standard escapes.
1668 @findex widget-default-format-handler
1669 You should end up calling @code{widget-default-format-handler} to handle
1670 unknown escape sequences, which will handle the @samp{%h} and any future
1671 escape sequences, as well as give an error for unknown escapes.
1673 @vindex action@r{ keyword}
1674 @item :action
1675 Function to handle user initiated events.  By default, @code{:notify}
1676 the parent.
1678 The following predefined function can be used here:
1680 @defun widget-parent-action widget &optional event
1681 Tell @code{:parent} of @var{widget} to handle the @code{:action}.
1682 Optional @var{event} is the event that triggered the action.
1683 @end defun
1685 @vindex prompt-value@r{ keyword}
1686 @item :prompt-value
1687 Function to prompt for a value in the minibuffer.  The function should
1688 take four arguments, @var{widget}, @var{prompt}, @var{value}, and
1689 @var{unbound} and should return a value for widget entered by the user.
1690 @var{prompt} is the prompt to use.  @var{value} is the default value to
1691 use, unless @var{unbound} is non-@code{nil}, in which case there is no default
1692 value.  The function should read the value using the method most natural
1693 for this widget, and does not have to check that it matches.
1694 @end table
1696 If you want to define a new widget from scratch, use the @code{default}
1697 widget as its base.
1699 @deffn Widget default
1700 Widget used as a base for other widgets.
1702 It provides most of the functionality that is referred to as ``by
1703 default'' in this text.
1704 @end deffn
1706 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
1707 @comment  node-name,  next,  previous,  up
1708 @section Widget Browser
1709 @cindex widget browser
1711 There is a separate package to browse widgets.  This is intended to help
1712 programmers who want to examine the content of a widget.  The browser
1713 shows the value of each keyword, but uses links for certain keywords
1714 such as @samp{:parent}, which avoids printing cyclic structures.
1716 @deffn Command widget-browse @var{widget}
1717 Create a widget browser for @var{widget}.
1718 When called interactively, prompt for @var{widget}.
1719 @end deffn
1721 @deffn Command widget-browse-other-window @var{widget}
1722 Create a widget browser for @var{widget} and show it in another window.
1723 When called interactively, prompt for @var{widget}.
1724 @end deffn
1726 @deffn Command widget-browse-at @var{pos}
1727 Create a widget browser for the widget at @var{pos}.
1728 When called interactively, use the position of point.
1729 @end deffn
1731 @node  Widget Minor Mode, Utilities, Widget Browser, Top
1732 @comment  node-name,  next,  previous,  up
1733 @section Widget Minor Mode
1734 @cindex widget minor mode
1736 There is a minor mode for manipulating widgets in major modes that
1737 don't provide any support for widgets themselves.  This is mostly
1738 intended to be useful for programmers doing experiments.
1740 @deffn Command widget-minor-mode
1741 Toggle minor mode for traversing widgets.
1742 With arg, turn widget mode on if and only if arg is positive.
1743 @end deffn
1745 @defvar widget-minor-mode-keymap
1746 Keymap used in @code{widget-minor-mode}.
1747 @end defvar
1749 @node  Utilities, Widget Wishlist, Widget Minor Mode, Top
1750 @comment  node-name,  next,  previous,  up
1751 @section Utilities.
1752 @cindex utility functions for widgets
1754 @defun widget-prompt-value widget prompt [ value unbound ]
1755 Prompt for a value matching @var{widget}, using @var{prompt}.
1756 The current value is assumed to be @var{value}, unless @var{unbound} is
1757 non-@code{nil}.@refill
1758 @end defun
1760 @defun widget-get-sibling widget
1761 Get the item which @var{widget} is assumed to toggle.
1762 This is only meaningful for radio buttons or checkboxes in a list.
1763 @end defun
1765 @node  Widget Wishlist, GNU Free Documentation License, Utilities, Top
1766 @comment  node-name,  next,  previous,  up
1767 @section Wishlist
1768 @cindex todo
1770 @itemize @bullet
1771 @item
1772 It should be possible to add or remove items from a list with @kbd{C-k}
1773 and @kbd{C-o} (suggested by @sc{rms}).
1775 @item
1776 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
1777 dash (@samp{-}).  The dash should be a button that, when invoked, asks
1778 whether you want to add or delete an item (@sc{rms} wanted to git rid of
1779 the ugly buttons, the dash is my idea).
1781 @item
1782 The @code{menu-choice} tag should be prettier, something like the abbreviated
1783 menus in Open Look.
1785 @item
1786 Finish @code{:tab-order}.
1788 @item
1789 Make indentation work with glyphs and proportional fonts.
1791 @item
1792 Add commands to show overview of object and class hierarchies to the
1793 browser.
1795 @item
1796 Find a way to disable mouse highlight for inactive widgets.
1798 @item
1799 Find a way to make glyphs look inactive.
1801 @item
1802 Add @code{property-list} widget.
1804 @item
1805 Add @code{association-list} widget.
1807 @item
1808 Add @code{key-binding} widget.
1810 @item
1811 Add @code{widget} widget for editing widget specifications.
1813 @item
1814 Find clean way to implement variable length list.
1815 See @code{TeX-printer-list} for an explanation.
1817 @item
1818 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
1820 @item
1821 Add a @code{mailto} widget.
1822 @end itemize
1824 @node GNU Free Documentation License, Index, Widget Wishlist, Top
1825 @appendix GNU Free Documentation License
1826 @include doclicense.texi
1828 @node Index, , GNU Free Documentation License, Top
1829 @comment  node-name,  next,  previous,  up
1830 @unnumbered Index
1832 This is an alphabetical listing of all concepts, functions, commands,
1833 variables, and widgets described in this manual.
1834 @printindex cp
1836 @setchapternewpage odd
1837 @contents
1838 @bye
1840 @ignore
1841    arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
1842 @end ignore