Add 2009 to copyright years.
[emacs.git] / doc / misc / widget.texi
blob0d847debde5ef02871a3648979fe0a9cab077e40
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, 2009  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.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
21 and with the Back-Cover Texts as in (a) below.  A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.  Buying copies from the FSF supports it in
26 developing GNU and promoting software freedom.''
27 @end quotation
28 @end copying
30 @dircategory Emacs
31 @direntry
32 * Widget: (widget).      The "widget" package used by the Emacs Customization
33                            facility.
34 @end direntry
36 @node Top, Introduction, (dir), (dir)
37 @comment  node-name,  next,  previous,  up
38 @top The Emacs Widget Library
40 @menu
41 * Introduction::
42 * User Interface::
43 * Programming Example::
44 * Setting Up the Buffer::
45 * Basic Types::
46 * Sexp Types::
47 * Widget Properties::
48 * Defining New Widgets::
49 * Widget Browser::
50 * Widget Minor Mode::
51 * Utilities::
52 * Widget Wishlist::
53 * GNU Free Documentation License::
54 * Index::
55 @end menu
57 @node  Introduction, User Interface, Top, Top
58 @comment  node-name,  next,  previous,  up
59 @section Introduction
61 Most graphical user interface toolkits provide a number of standard
62 user interface controls (sometimes known as `widgets' or `gadgets').
63 Emacs doesn't really support anything like this, except for an
64 incredibly powerful text ``widget.''  On the other hand, Emacs does
65 provide the necessary primitives to implement many other widgets
66 within a text buffer.  The @code{widget} package simplifies this task.
68 @cindex basic widgets
69 @cindex widgets, basic types
70 The basic widgets are:
72 @table @code
73 @item link
74 Areas of text with an associated action.  Intended for hypertext links
75 embedded in text.
76 @item push-button
77 Like link, but intended for stand-alone buttons.
78 @item editable-field
79 An editable text field.  It can be either variable or fixed length.
80 @item menu-choice
81 Allows the user to choose one of multiple options from a menu, each
82 option is itself a widget.  Only the selected option will be visible in
83 the buffer.
84 @item radio-button-choice
85 Allows the user to choose one of multiple options by activating radio
86 buttons.  The options are implemented as widgets.  All options will be
87 visible in the buffer.
88 @item item
89 A simple constant widget intended to be used in the @code{menu-choice} and
90 @code{radio-button-choice} widgets.
91 @item choice-item
92 A button item only intended for use in choices.  When invoked, the user
93 will be asked to select another option from the choice widget.
94 @item toggle
95 A simple @samp{on}/@samp{off} switch.
96 @item checkbox
97 A checkbox (@samp{[ ]}/@samp{[X]}).
98 @item editable-list
99 Create an editable list.  The user can insert or delete items in the
100 list.  Each list item is itself a widget.
101 @end table
103 Now, of what possible use can support for widgets be in a text editor?
104 I'm glad you asked.  The answer is that widgets are useful for
105 implementing forms.  A @dfn{form} in Emacs is a buffer where the user is
106 supposed to fill out a number of fields, each of which has a specific
107 meaning.  The user is not supposed to change or delete any of the text
108 between the fields.  Examples of forms in Emacs are the @file{forms}
109 package (of course), the customize buffers, the mail and news compose
110 modes, and the @acronym{HTML} form support in the @file{w3} browser.
112 @cindex widget library, why use it
113 The advantages for a programmer of using the @code{widget} package to
114 implement forms are:
116 @enumerate
117 @item
118 More complex fields than just editable text are supported.
119 @item
120 You can give the users immediate feedback if they enter invalid data in a
121 text field, and sometimes prevent entering invalid data.
122 @item
123 You can have fixed sized fields, thus allowing multiple fields to be
124 lined up in columns.
125 @item
126 It is simple to query or set the value of a field.
127 @item
128 Editing happens in the buffer, not in the mini-buffer.
129 @item
130 Packages using the library get a uniform look, making them easier for
131 the user to learn.
132 @item
133 As support for embedded graphics improve, the widget library will be
134 extended to use the GUI features.  This means that your code using the
135 widget library will also use the new graphic features automatically.
136 @end enumerate
138 @node User Interface, Programming Example, Introduction, Top
139 @comment  node-name,  next,  previous,  up
140 @section User Interface
142 A form consists of read only text for documentation and some fields,
143 where each field contains two parts, a tag and a value.  The tags are
144 used to identify the fields, so the documentation can refer to the
145 @samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
146 example form:
148 @example
149 Here is some documentation.
151 Name: @i{My Name}     @strong{Choose}: This option
152 Address:  @i{Some Place
153 In some City
154 Some country.}
156 See also @b{_other work_} for more information.
158 Numbers: count to three below
159 @b{[INS]} @b{[DEL]} @i{One}
160 @b{[INS]} @b{[DEL]} @i{Eh, two?}
161 @b{[INS]} @b{[DEL]} @i{Five!}
162 @b{[INS]}
164 Select multiple:
166 @b{[X]} This
167 @b{[ ]} That
168 @b{[X]} Thus
170 Select one:
172 @b{(*)} One
173 @b{( )} Another One.
174 @b{( )} A Final One.
176 @b{[Apply Form]} @b{[Reset Form]}
177 @end example
179 The top level widgets in this example are tagged @samp{Name},
180 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
181 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
182 @samp{[Reset Form]}.  There are basically two things the user can do
183 within a form, namely editing the editable text fields and activating
184 the buttons.
186 @subsection Editable Text Fields
188 In the example, the value for the @samp{Name} is most likely displayed
189 in an editable text field, and so are values for each of the members of
190 the @samp{Numbers} list.  All the normal Emacs editing operations are
191 available for editing these fields.  The only restriction is that each
192 change you make must be contained within a single editable text field.
193 For example, capitalizing all text from the middle of one field to the
194 middle of another field is prohibited.
196 Editable text fields are created by the @code{editable-field} widget.
198 @strong{Warning:} In an @code{editable-field} widget, the editable
199 field must not be adjacent to another widget---that won't work.
200 You must put some text in between.  Either make this text part of
201 the @code{editable-field} widget itself, or insert it with
202 @code{widget-insert}.
204 The @code{:format} keyword is useful for generating the necessary
205 text; for instance, if you give it a value of @code{"Name: %v "},
206 the @samp{Name: } part will provide the necessary separating text
207 before the field and the trailing space will provide the
208 separating text after the field.  If you don't include the
209 @code{:size} keyword, the field will extend to the end of the
210 line, and the terminating newline will provide separation after.
212 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
213 must be preceded by some other text in the @code{:format} string
214 (if specified).
216 The editing text fields are highlighted with the
217 @code{widget-field-face} face, making them easy to find.
219 @deffn Face widget-field-face
220 Face used for other editing fields.
221 @end deffn
223 @subsection Buttons
225 @cindex widget buttons
226 @cindex button widgets
227 Some portions of the buffer have an associated @dfn{action}, which can
228 be @dfn{invoked} by a standard key or mouse command.  These portions
229 are called @dfn{buttons}.  The default commands for activating a button
230 are:
232 @table @kbd
233 @item @key{RET}
234 @deffn Command widget-button-press @var{pos} &optional @var{event}
235 Invoke the button at @var{pos}, defaulting to point.
236 If point is not located on a button, invoke the binding in
237 @code{widget-global-map} (by default the global map).
238 @end deffn
240 @kindex Mouse-2 @r{(on button widgets})
241 @item Mouse-2
242 @deffn Command widget-button-click @var{event}
243 Invoke the button at the location of the mouse pointer.  If the mouse
244 pointer is located in an editable text field, invoke the binding in
245 @code{widget-global-map} (by default the global map).
246 @end deffn
247 @end table
249 There are several different kind of buttons, all of which are present in
250 the example:
252 @table @emph
253 @cindex option field tag
254 @item The Option Field Tags
255 When you invoke one of these buttons, you will be asked to choose
256 between a number of different options.  This is how you edit an option
257 field.  Option fields are created by the @code{menu-choice} widget.  In
258 the example, @samp{@b{Choose}} is an option field tag.
259 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
260 Activating these will insert or delete elements from an editable list.
261 The list is created by the @code{editable-list} widget.
262 @cindex embedded buttons
263 @item Embedded Buttons
264 The @samp{@b{_other work_}} is an example of an embedded
265 button.  Embedded buttons are not associated with any fields, but can serve
266 any purpose, such as implementing hypertext references.  They are
267 usually created by the @code{link} widget.
268 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
269 Activating one of these will convert it to the other.  This is useful
270 for implementing multiple-choice fields.  You can create them with the
271 @code{checkbox} widget.
272 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
273 Only one radio button in a @code{radio-button-choice} widget can be
274 selected at any time.  When you invoke one of the unselected radio
275 buttons, it will be selected and the previous selected radio button will
276 become unselected.
277 @item The @samp{@b{[Apply Form]}} and @samp{@b{[Reset Form]}} buttons
278 These are explicit buttons made with the @code{push-button} widget.  The
279 main difference from the @code{link} widget is that the buttons will be
280 displayed as GUI buttons when possible.
281 @end table
283 To make them easier to locate, buttons are emphasized in the buffer.
285 @deffn Face widget-button-face
286 Face used for buttons.
287 @end deffn
289 @defopt widget-mouse-face
290 Face used for highlighting a button when the mouse pointer moves across
292 @end defopt
294 @subsection Navigation
296 You can use all the normal Emacs commands to move around in a form
297 buffer, plus you will have these additional commands:
299 @table @kbd
300 @item @key{TAB}
301 @deffn Command widget-forward &optional count
302 Move point @var{count} buttons or editing fields forward.
303 @end deffn
304 @item @kbd{M-@key{TAB}}
305 @itemx @kbd{S-@key{TAB}}
306 @deffn Command widget-backward &optional count
307 Move point @var{count} buttons or editing fields backward.
308 @end deffn
309 @end table
311 @node Programming Example, Setting Up the Buffer, User Interface, Top
312 @comment  node-name,  next,  previous,  up
313 @section Programming Example
315 @cindex widgets, programming example
316 @cindex example of using widgets
317 Here is the code to implement the user interface example (@pxref{User
318 Interface}).
320 @lisp
321 (require 'widget)
323 (eval-when-compile
324   (require 'wid-edit))
326 (defvar widget-example-repeat)
328 (defun widget-example ()
329   "Create the widgets from the Widget manual."
330   (interactive)
331   (switch-to-buffer "*Widget Example*")
332   (kill-all-local-variables)
333   (make-local-variable 'widget-example-repeat)
334   (let ((inhibit-read-only t))
335     (erase-buffer))
336   (remove-overlays)
337   (widget-insert "Here is some documentation.\n\n")
338   (widget-create 'editable-field
339                  :size 13
340                  :format "Name: %v " ; Text after the field!
341                  "My Name")
342   (widget-create 'menu-choice
343                  :tag "Choose"
344                  :value "This"
345                  :help-echo "Choose me, please!"
346                  :notify (lambda (widget &rest ignore)
347                            (message "%s is a good choice!"
348                                     (widget-value widget)))
349                  '(item :tag "This option" :value "This")
350                  '(choice-item "That option")
351                  '(editable-field :menu-tag "No option" "Thus option"))
352   (widget-create 'editable-field
353                  :format "Address: %v"
354                  "Some Place\nIn some City\nSome country.")
355   (widget-insert "\nSee also ")
356   (widget-create 'link
357                  :notify (lambda (&rest ignore)
358                            (widget-value-set widget-example-repeat
359                                              '("En" "To" "Tre"))
360                            (widget-setup))
361                  "other work")
362   (widget-insert
363     " for more information.\n\nNumbers: count to three below\n")
364   (setq widget-example-repeat
365         (widget-create 'editable-list
366                        :entry-format "%i %d %v"
367                        :notify (lambda (widget &rest ignore)
368                                  (let ((old (widget-get widget
369                                                         ':example-length))
370                                        (new (length (widget-value widget))))
371                                    (unless (eq old new)
372                                      (widget-put widget ':example-length new)
373                                      (message "You can count to %d." new))))
374                        :value '("One" "Eh, two?" "Five!")
375                        '(editable-field :value "three")))
376   (widget-insert "\n\nSelect multiple:\n\n")
377   (widget-create 'checkbox t)
378   (widget-insert " This\n")
379   (widget-create 'checkbox nil)
380   (widget-insert " That\n")
381   (widget-create 'checkbox
382                  :notify (lambda (&rest ignore) (message "Tickle"))
383                  t)
384   (widget-insert " Thus\n\nSelect one:\n\n")
385   (widget-create 'radio-button-choice
386                  :value "One"
387                  :notify (lambda (widget &rest ignore)
388                            (message "You selected %s"
389                                     (widget-value widget)))
390                  '(item "One") '(item "Another One.") '(item "A Final One."))
391   (widget-insert "\n")
392   (widget-create 'push-button
393                  :notify (lambda (&rest ignore)
394                            (if (= (length (widget-value widget-example-repeat))
395                                   3)
396                                (message "Congratulation!")
397                              (error "Three was the count!")))
398                  "Apply Form")
399   (widget-insert " ")
400   (widget-create 'push-button
401                  :notify (lambda (&rest ignore)
402                            (widget-example))
403                  "Reset Form")
404   (widget-insert "\n")
405   (use-local-map widget-keymap)
406   (widget-setup))
407 @end lisp
409 @node Setting Up the Buffer, Basic Types, Programming Example, Top
410 @comment  node-name,  next,  previous,  up
411 @section Setting Up the Buffer
413 Widgets are created with @code{widget-create}, which returns a
414 @dfn{widget} object.  This object can be queried and manipulated by
415 other widget functions, until it is deleted with @code{widget-delete}.
416 After the widgets have been created, @code{widget-setup} must be called
417 to enable them.
419 @defun widget-create type [ keyword argument ]@dots{}
420 Create and return a widget of type @var{type}.
421 The syntax for the @var{type} argument is described in @ref{Basic Types}.
423 The keyword arguments can be used to overwrite the keyword arguments
424 that are part of @var{type}.
425 @end defun
427 @defun widget-delete widget
428 Delete @var{widget} and remove it from the buffer.
429 @end defun
431 @defun widget-setup
432 Set up a buffer to support widgets.
434 This should be called after creating all the widgets and before allowing
435 the user to edit them.
436 @refill
437 @end defun
439 If you want to insert text outside the widgets in the form, the
440 recommended way to do that is with @code{widget-insert}.
442 @defun widget-insert
443 Insert the arguments, either strings or characters, at point.
444 The inserted text will be read-only.
445 @end defun
447 There is a standard widget keymap which you might find useful.
449 @findex widget-button-press
450 @findex widget-button-click
451 @defvr Const widget-keymap
452 A keymap with the global keymap as its parent.@*
453 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
454 @code{widget-backward}, respectively.  @key{RET} and @kbd{Mouse-2}
455 are bound to @code{widget-button-press} and
456 @code{widget-button-click}.@refill
457 @end defvr
459 @defvar widget-global-map
460 Keymap used by @code{widget-button-press} and @code{widget-button-click}
461 when not on a button.  By default this is @code{global-map}.
462 @end defvar
464 @node Basic Types, Sexp Types, Setting Up the Buffer, Top
465 @comment  node-name,  next,  previous,  up
466 @section Basic Types
468 This is the general syntax of a type specification:
470 @example
471 @var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
472      |   @var{name}
473 @end example
475 Where, @var{name} is a widget name, @var{keyword} is the name of a
476 property, @var{argument} is the value of the property, and @var{args}
477 are interpreted in a widget specific way.
479 @cindex keyword arguments
480 The following keyword arguments apply to all widgets:
482 @table @code
483 @vindex value@r{ keyword}
484 @item :value
485 The initial value for widgets of this type.
487 @vindex format@r{ keyword}
488 @item :format
489 This string will be inserted in the buffer when you create a widget.
490 The following @samp{%} escapes are available:
492 @table @samp
493 @item %[
494 @itemx %]
495 The text inside will be marked as a button.
497 By default, the text will be shown in @code{widget-button-face}, and
498 surrounded by brackets.
500 @defopt widget-button-prefix
501 String to prefix buttons.
502 @end defopt
504 @defopt widget-button-suffix
505 String to suffix buttons.
506 @end defopt
508 @item %@{
509 @itemx %@}
510 The text inside will be displayed with the face specified by
511 @code{:sample-face}.
513 @item %v
514 This will be replaced with the buffer representation of the widget's
515 value.  What this is depends on the widget type.
517 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
518 must be preceded by some other text in the format string (if specified).
520 @item %d
521 Insert the string specified by @code{:doc} here.
523 @item %h
524 Like @samp{%d}, with the following modifications: If the documentation
525 string is more than one line, it will add a button which will toggle
526 between showing only the first line, and showing the full text.
527 Furthermore, if there is no @code{:doc} property in the widget, it will
528 instead examine the @code{:documentation-property} property.  If it is a
529 lambda expression, it will be called with the widget's value as an
530 argument, and the result will be used as the documentation text.
532 @item %t
533 Insert the string specified by @code{:tag} here, or the @code{princ}
534 representation of the value if there is no tag.
536 @item %%
537 Insert a literal @samp{%}.
538 @end table
540 @vindex button-face@r{ keyword}
541 @item :button-face
542 Face used to highlight text inside %[ %] in the format.
544 @vindex button-prefix@r{ keyword}
545 @vindex button-suffix@r{ keyword}
546 @item :button-prefix
547 @itemx :button-suffix
548 Text around %[ %] in the format.
550 These can be
551 @table @emph
552 @item nil
553 No text is inserted.
555 @item a string
556 The string is inserted literally.
558 @item a symbol
559 The value of the symbol is expanded according to this table.
560 @end table
562 @vindex doc@r{ keyword}
563 @item :doc
564 The string inserted by the @samp{%d} escape in the format
565 string.
567 @vindex tag@r{ keyword}
568 @item :tag
569 The string inserted by the @samp{%t} escape in the format
570 string.
572 @vindex tag-glyph@r{ keyword}
573 @item :tag-glyph
574 Name of image to use instead of the string specified by @code{:tag} on
575 Emacsen that supports it.
577 @vindex help-echo@r{ keyword}
578 @item :help-echo
579 Specifies how to display a message whenever you move to the widget with
580 either @code{widget-forward} or @code{widget-backward} or move the mouse
581 over it (using the standard @code{help-echo} mechanism).  The argument
582 is either a string to display, a function of one argument, the widget,
583 which should return a string to display, or a form that evaluates to
584 such a string.
586 @vindex follow-link@r{ keyword}
587 @item :follow-link
588 Specifies how to interpret a @key{mouse-1} click on the widget.
589 @xref{Links and Mouse-1,,, elisp, the Emacs Lisp Reference Manual}.
591 @vindex indent@r{ keyword}
592 @item :indent
593 An integer indicating the absolute number of spaces to indent children
594 of this widget.
596 @vindex offset@r{ keyword}
597 @item :offset
598 An integer indicating how many extra spaces to add to the widget's
599 grandchildren compared to this widget.
601 @vindex extra-offset@r{ keyword}
602 @item :extra-offset
603 An integer indicating how many extra spaces to add to the widget's
604 children compared to this widget.
606 @vindex notify@r{ keyword}
607 @item :notify
608 A function called each time the widget or a nested widget is changed.
609 The function is called with two or three arguments.  The first argument
610 is the widget itself, the second argument is the widget that was
611 changed, and the third argument is the event leading to the change, if
612 any.
614 @vindex menu-tag@r{ keyword}
615 @item :menu-tag
616 Tag used in the menu when the widget is used as an option in a
617 @code{menu-choice} widget.
619 @vindex menu-tag-get@r{ keyword}
620 @item :menu-tag-get
621 Function used for finding the tag when the widget is used as an option
622 in a @code{menu-choice} widget.  By default, the tag used will be either the
623 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
624 representation of the @code{:value} property if not.
626 @vindex match@r{ keyword}
627 @item :match
628 Should be a function called with two arguments, the widget and a value,
629 and returning non-@code{nil} if the widget can represent the specified value.
631 @vindex validate@r{ keyword}
632 @item :validate
633 A function which takes a widget as an argument, and returns @code{nil}
634 if the widget's current value is valid for the widget.  Otherwise it
635 should return the widget containing the invalid data, and set that
636 widget's @code{:error} property to a string explaining the error.
638 The following predefined function can be used:
640 @defun widget-children-validate widget
641 All the @code{:children} of @var{widget} must be valid.
642 @end defun
644 @vindex tab-order@r{ keyword}
645 @item :tab-order
646 Specify the order in which widgets are traversed with
647 @code{widget-forward} or @code{widget-backward}.  This is only partially
648 implemented.
650 @enumerate a
651 @item
652 Widgets with tabbing order @code{-1} are ignored.
654 @item
655 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
656 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
657 whichever comes first.
659 @item
660 When on a widget with no tabbing order specified, go to the next widget
661 in the buffer with a positive tabbing order, or @code{nil}
662 @end enumerate
664 @vindex parent@r{ keyword}
665 @item :parent
666 The parent of a nested widget (e.g.@: a @code{menu-choice} item or an
667 element of a @code{editable-list} widget).
669 @vindex sibling-args@r{ keyword}
670 @item :sibling-args
671 This keyword is only used for members of a @code{radio-button-choice} or
672 @code{checklist}.  The value should be a list of extra keyword
673 arguments, which will be used when creating the @code{radio-button} or
674 @code{checkbox} associated with this item.
676 @end table
678 @deffn {User Option} widget-glyph-directory
679 Directory where glyphs are found.
680 Widget will look here for a file with the same name as specified for the
681 image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
682 @end deffn
684 @deffn{User Option} widget-glyph-enable
685 If non-@code{nil}, allow glyphs to appear on displays where they are supported.
686 @end deffn
689 @menu
690 * link::
691 * url-link::
692 * info-link::
693 * push-button::
694 * editable-field::
695 * text::
696 * menu-choice::
697 * radio-button-choice::
698 * item::
699 * choice-item::
700 * toggle::
701 * checkbox::
702 * checklist::
703 * editable-list::
704 * group::
705 @end menu
707 @node link, url-link, Basic Types, Basic Types
708 @comment  node-name,  next,  previous,  up
709 @subsection The @code{link} Widget
710 @findex link@r{ widget}
712 Syntax:
714 @example
715 @var{type} ::= (link [@var{keyword} @var{argument}]...  [ @var{value} ])
716 @end example
718 The @var{value}, if present, is used to initialize the @code{:value}
719 property.  The value should be a string, which will be inserted in the
720 buffer.
722 By default the link will be shown in brackets.
724 @defopt widget-link-prefix
725 String to prefix links.
726 @end defopt
728 @defopt widget-link-suffix
729 String to suffix links.
730 @end defopt
732 @node url-link, info-link, link, Basic Types
733 @comment  node-name,  next,  previous,  up
734 @subsection The @code{url-link} Widget
735 @findex url-link@r{ widget}
737 Syntax:
739 @example
740 @var{type} ::= (url-link [@var{keyword} @var{argument}]...  @var{url})
741 @end example
743 @findex browse-url-browser-function@r{, and @code{url-link} widget}
744 When this link is invoked, the @acronym{WWW} browser specified by
745 @code{browse-url-browser-function} will be called with @var{url}.
747 @node info-link, push-button, url-link, Basic Types
748 @comment  node-name,  next,  previous,  up
749 @subsection The @code{info-link} Widget
750 @findex info-link@r{ widget}
752 Syntax:
754 @example
755 @var{type} ::= (info-link [@var{keyword} @var{argument}]...  @var{address})
756 @end example
758 When this link is invoked, the built-in Info reader is started on
759 @var{address}.
761 @node  push-button, editable-field, info-link, Basic Types
762 @comment  node-name,  next,  previous,  up
763 @subsection The @code{push-button} Widget
764 @findex push-button@r{ widget}
766 Syntax:
768 @example
769 @var{type} ::= (push-button [@var{keyword} @var{argument}]...  [ @var{value} ])
770 @end example
772 The @var{value}, if present, is used to initialize the @code{:value}
773 property.  The value should be a string, which will be inserted in the
774 buffer.
776 By default the tag will be shown in brackets.
778 @defopt widget-push-button-prefix
779 String to prefix push buttons.
780 @end defopt
782 @defopt widget-push-button-suffix
783 String to suffix push buttons.
784 @end defopt
786 @node editable-field, text, push-button, Basic Types
787 @comment  node-name,  next,  previous,  up
788 @subsection The @code{editable-field} Widget
789 @findex editable-field@r{ widget}
791 Syntax:
793 @example
794 @var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{value} ])
795 @end example
797 The @var{value}, if present, is used to initialize the @code{:value}
798 property.  The value should be a string, which will be inserted in the
799 field.  This widget will match all string values.
801 The following extra properties are recognized:
803 @table @code
804 @vindex size@r{ keyword}
805 @item :size
806 The width of the editable field.@*
807 By default the field will reach to the end of the line.
809 @vindex value-face@r{ keyword}
810 @item :value-face
811 Face used for highlighting the editable field.  Default is
812 @code{widget-field-face}, see @ref{User Interface}.
814 @vindex secret@r{ keyword}
815 @item :secret
816 Character used to display the value.  You can set this to e.g.@: @code{?*}
817 if the field contains a password or other secret information.  By
818 default, this is @code{nil}, and the value is not secret.
820 @vindex valid-regexp@r{ keyword}
821 @item :valid-regexp
822 By default the @code{:validate} function will match the content of the
823 field with the value of this attribute.  The default value is @code{""}
824 which matches everything.
826 @vindex keymap@r{ keyword}
827 @vindex widget-field-keymap
828 @item :keymap
829 Keymap used in the editable field.  The default value is
830 @code{widget-field-keymap}, which allows you to use all the normal
831 editing commands, even if the buffer's major mode suppresses some of
832 them.  Pressing @key{RET} invokes the function specified by
833 @code{:action}.
834 @end table
836 @node text, menu-choice, editable-field, Basic Types
837 @comment  node-name,  next,  previous,  up
838 @subsection The @code{text} Widget
839 @findex text@r{ widget}
841 @vindex widget-text-keymap
842 This is just like @code{editable-field}, but intended for multiline text
843 fields.  The default @code{:keymap} is @code{widget-text-keymap}, which
844 does not rebind the @key{RET} key.
846 @node menu-choice, radio-button-choice, text, Basic Types
847 @comment  node-name,  next,  previous,  up
848 @subsection The @code{menu-choice} Widget
849 @findex menu-choice@r{ widget}
851 Syntax:
853 @example
854 @var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
855 @end example
857 The @var{type} argument represents each possible choice.  The widget's
858 value will be that of the chosen @var{type} argument.  This widget will
859 match any value matching at least one of the specified @var{type}
860 arguments.
862 @table @code
863 @vindex void@r{ keyword}
864 @item :void
865 Widget type used as a fallback when the value does not match any of the
866 specified @var{type} arguments.
868 @vindex case-fold@r{ keyword}
869 @item :case-fold
870 Set this to @code{nil} if you don't want to ignore case when prompting for a
871 choice through the minibuffer.
873 @vindex children@r{ keyword}
874 @item :children
875 A list whose @sc{car} is the widget representing the currently chosen
876 type in the buffer.
878 @vindex choice@r{ keyword}
879 @item :choice
880 The current chosen type.
882 @vindex args@r{ keyword}
883 @item :args
884 The list of types.
885 @end table
887 @node radio-button-choice, item, menu-choice, Basic Types
888 @comment  node-name,  next,  previous,  up
889 @subsection The @code{radio-button-choice} Widget
890 @findex radio-button-choice@r{ widget}
892 Syntax:
894 @example
895 @var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]...  @var{type} ... )
896 @end example
898 The component types specify the choices, with one radio button for
899 each.  The widget's value will be that of the chosen @var{type}
900 argument.  This widget matches any value that matches at least one of
901 the specified @var{type} arguments.
903 The following extra properties are recognized.
905 @table @code
906 @vindex entry-format@r{ keyword}
907 @item :entry-format
908 This string will be inserted for each entry in the list.
909 The following @samp{%} escapes are available:
910 @table @samp
911 @item %v
912 Replace with the buffer representation of the @var{type} widget.
913 @item %b
914 Replace with the radio button.
915 @item %%
916 Insert a literal @samp{%}.
917 @end table
919 @vindex button-args@r{ keyword}
920 @item :button-args
921 A list of keywords to pass to the radio buttons.  Useful for setting
922 e.g.@: the @samp{:help-echo} for each button.
924 @vindex buttons@r{ keyword}
925 @item :buttons
926 The widgets representing the radio buttons.
928 @vindex children@r{ keyword}
929 @item :children
930 The widgets representing each type.
932 @vindex choice@r{ keyword}
933 @item :choice
934 The current chosen type
936 @vindex args@r{ keyword}
937 @item :args
938 The list of types.
939 @end table
941 You can add extra radio button items to a @code{radio-button-choice}
942 widget after it has been created with the function
943 @code{widget-radio-add-item}.
945 @defun widget-radio-add-item widget type
946 Add to @code{radio-button-choice} widget @var{widget} a new radio button
947 item of type @var{type}.
948 @end defun
950 Please note that such items added after the @code{radio-button-choice}
951 widget has been created will @strong{not} be properly destructed when
952 you call @code{widget-delete}.
954 @node item, choice-item, radio-button-choice, Basic Types
955 @comment  node-name,  next,  previous,  up
956 @subsection The @code{item} Widget
957 @findex item@r{ widget}
959 Syntax:
961 @example
962 @var{item} ::= (item [@var{keyword} @var{argument}]... @var{value})
963 @end example
965 The @var{value}, if present, is used to initialize the @code{:value}
966 property.  The value should be a string, which will be inserted in the
967 buffer.  This widget will only match the specified value.
969 @node choice-item, toggle, item, Basic Types
970 @comment  node-name,  next,  previous,  up
971 @subsection The @code{choice-item} Widget
972 @findex choice-item@r{ widget}
974 Syntax:
976 @example
977 @var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{value})
978 @end example
980 The @var{value}, if present, is used to initialize the @code{:value}
981 property.  The value should be a string, which will be inserted in the
982 buffer as a button.  Activating the button of a @code{choice-item} is
983 equivalent to activating the parent widget.  This widget will only match
984 the specified value.
986 @node toggle, checkbox, choice-item, Basic Types
987 @comment  node-name,  next,  previous,  up
988 @subsection The @code{toggle} Widget
989 @findex toggle@r{ widget}
991 Syntax:
993 @example
994 @var{type} ::= (toggle [@var{keyword} @var{argument}]...)
995 @end example
997 The widget has two possible states, @samp{on} and @samp{off}, which
998 correspond to a @code{t} or @code{nil} value, respectively.
1000 The following extra properties are recognized:
1002 @table @code
1003 @item :on
1004 A string representing the @samp{on} state.  By default the string
1005 @samp{on}.
1006 @item :off
1007 A string representing the @samp{off} state.  By default the string
1008 @samp{off}.
1009 @vindex on-glyph@r{ keyword}
1010 @item :on-glyph
1011 Name of a glyph to be used instead of the @samp{:on} text string, on
1012 emacsen that supports this.
1013 @vindex off-glyph@r{ keyword}
1014 @item :off-glyph
1015 Name of a glyph to be used instead of the @samp{:off} text string, on
1016 emacsen that supports this.
1017 @end table
1019 @node checkbox, checklist, toggle, Basic Types
1020 @comment  node-name,  next,  previous,  up
1021 @subsection The @code{checkbox} Widget
1022 @findex checkbox@r{ widget}
1024 This widget has two possible states, @samp{selected} and
1025 @samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
1027 Syntax:
1029 @example
1030 @var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
1031 @end example
1033 @node checklist, editable-list, checkbox, Basic Types
1034 @comment  node-name,  next,  previous,  up
1035 @subsection The @code{checklist} Widget
1036 @findex checklist@r{ widget}
1038 Syntax:
1040 @example
1041 @var{type} ::= (checklist [@var{keyword} @var{argument}]...  @var{type} ... )
1042 @end example
1044 The @var{type} arguments represent each checklist item.  The widget's
1045 value will be a list containing the values of all checked @var{type}
1046 arguments.  The checklist widget will match a list whose elements all
1047 match at least one of the specified @var{type} arguments.
1049 The following extra properties are recognized:
1051 @table @code
1052 @vindex entry-format@r{ keyword}
1053 @item :entry-format
1054 This string will be inserted for each entry in the list.
1055 The following @samp{%} escapes are available:
1056 @table @samp
1057 @item %v
1058 Replaced with the buffer representation of the @var{type} widget.
1059 @item %b
1060 Replace with the checkbox.
1061 @item %%
1062 Insert a literal @samp{%}.
1063 @end table
1065 @vindex greedy@r{ keyword}
1066 @item :greedy
1067 Usually a checklist will only match if the items are in the exact
1068 sequence given in the specification.  By setting @code{:greedy} to
1069 non-@code{nil}, it will allow the items to come in any sequence.
1070 However, if you extract the value they will be in the sequence given
1071 in the checklist, i.e.@: the original sequence is forgotten.
1073 @vindex button-args@r{ keyword}
1074 @item :button-args
1075 A list of keywords to pass to the checkboxes.  Useful for setting
1076 e.g.@: the @samp{:help-echo} for each checkbox.
1078 @vindex buttons@r{ keyword}
1079 @item :buttons
1080 The widgets representing the checkboxes.
1082 @vindex children@r{ keyword}
1083 @item :children
1084 The widgets representing each type.
1086 @vindex args@r{ keyword}
1087 @item :args
1088 The list of types.
1089 @end table
1091 @node editable-list, group, checklist, Basic Types
1092 @comment  node-name,  next,  previous,  up
1093 @subsection The @code{editable-list} Widget
1094 @findex editable-list@r{ widget}
1096 Syntax:
1098 @example
1099 @var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{type})
1100 @end example
1102 The value is a list, where each member represents one widget of type
1103 @var{type}.
1105 The following extra properties are recognized:
1107 @table @code
1108 @vindex entry-format@r{ keyword}
1109 @item :entry-format
1110 This string will be inserted for each entry in the list.
1111 The following @samp{%} escapes are available:
1112 @table @samp
1113 @item %v
1114 This will be replaced with the buffer representation of the @var{type}
1115 widget.
1116 @item %i
1117 Insert the @b{[INS]} button.
1118 @item %d
1119 Insert the @b{[DEL]} button.
1120 @item %%
1121 Insert a literal @samp{%}.
1122 @end table
1124 @vindex insert-button-args@r{ keyword}
1125 @item :insert-button-args
1126 A list of keyword arguments to pass to the insert buttons.
1128 @vindex delete-button-args@r{ keyword}
1129 @item :delete-button-args
1130 A list of keyword arguments to pass to the delete buttons.
1132 @vindex append-button-args@r{ keyword}
1133 @item :append-button-args
1134 A list of keyword arguments to pass to the trailing insert button.
1136 @vindex buttons@r{ keyword}
1137 @item :buttons
1138 The widgets representing the insert and delete buttons.
1140 @vindex children@r{ keyword}
1141 @item :children
1142 The widgets representing the elements of the list.
1144 @vindex args@r{ keyword}
1145 @item :args
1146 List whose @sc{car} is the type of the list elements.
1147 @end table
1149 @node group,  , editable-list, Basic Types
1150 @comment  node-name,  next,  previous,  up
1151 @subsection The @code{group} Widget
1152 @findex group@r{ widget}
1154 This widget simply group other widgets together.
1156 Syntax:
1158 @example
1159 @var{type} ::= (group [@var{keyword} @var{argument}]... @var{type}...)
1160 @end example
1162 The value is a list, with one member for each @var{type}.
1164 @node Sexp Types, Widget Properties, Basic Types, Top
1165 @comment
1166 @section Sexp Types
1167 @cindex sexp types
1169 A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp
1170 for short, are also available.  These basically fall in several
1171 categories described in this section.
1173 @menu
1174 * constants::
1175 * generic::
1176 * atoms::
1177 * composite::
1178 @end menu
1180 @node constants, generic, Sexp Types, Sexp Types
1181 @comment  node-name,  next,  previous,  up
1182 @subsection The Constant Widgets
1183 @cindex constant widgets
1185 The @code{const} widget can contain any Lisp expression, but the user is
1186 prohibited from editing it, which is mainly useful as a component of one
1187 of the composite widgets.
1189 The syntax for the @code{const} widget is:
1191 @example
1192 @var{type} ::= (const [@var{keyword} @var{argument}]...  [ @var{value} ])
1193 @end example
1195 The @var{value}, if present, is used to initialize the @code{:value}
1196 property and can be any s-expression.
1198 @deffn Widget const
1199 This will display any valid s-expression in an immutable part of the
1200 buffer.
1201 @end deffn
1203 There are two variations of the @code{const} widget, namely
1204 @code{variable-item} and @code{function-item}.  These should contain a
1205 symbol with a variable or function binding.  The major difference from
1206 the @code{const} widget is that they will allow the user to see the
1207 variable or function documentation for the symbol.
1209 @deffn Widget variable-item
1210 An immutable symbol that is bound as a variable.
1211 @end deffn
1213 @deffn Widget function-item
1214 An immutable symbol that is bound as a function.
1215 @end deffn
1217 @node generic, atoms, constants, Sexp Types
1218 @comment  node-name,  next,  previous,  up
1219 @subsection Generic Sexp Widget
1220 @cindex generic sexp widget
1222 The @code{sexp} widget can contain any Lisp expression, and allows the
1223 user to edit it inline in the buffer.
1225 The syntax for the @code{sexp} widget is:
1227 @example
1228 @var{type} ::= (sexp [@var{keyword} @var{argument}]...  [ @var{value} ])
1229 @end example
1231 @deffn Widget sexp
1232 This will allow you to edit any valid s-expression in an editable buffer
1233 field.
1235 The @code{sexp} widget takes the same keyword arguments as the
1236 @code{editable-field} widget.  @xref{editable-field}.
1237 @end deffn
1239 @node atoms, composite, generic, Sexp Types
1240 @comment  node-name,  next,  previous,  up
1241 @subsection Atomic Sexp Widgets
1242 @cindex atomic sexp widget
1244 The atoms are s-expressions that do not consist of other s-expressions.
1245 For example, a string, a file name, or a symbol are atoms, while a list
1246 is a composite type.  You can edit the value of an atom with the
1247 following widgets.
1249 The syntax for all the atoms are:
1251 @example
1252 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]...  [ @var{value} ])
1253 @end example
1255 The @var{value}, if present, is used to initialize the @code{:value}
1256 property and must be an expression of the same type as the widget.
1257 That is, the string widget can only be initialized with a string.
1259 All the atom widgets take the same keyword arguments as the
1260 @code{editable-field} widget.  @xref{editable-field}.
1262 @deffn Widget string
1263 Allows you to edit a string in an editable field.
1264 @end deffn
1266 @deffn Widget regexp
1267 Allows you to edit a regular expression in an editable field.
1268 @end deffn
1270 @deffn Widget character
1271 Allows you to enter a character in an editable field.
1272 @end deffn
1274 @deffn Widget file
1275 Allows you to edit a file name in an editable field.
1277 Keywords:
1278 @table @code
1279 @vindex must-match@r{ keyword}
1280 @item :must-match
1281 If this is set to non-@code{nil}, only existing file names will be
1282 allowed in the minibuffer.
1283 @end table
1284 @end deffn
1286 @deffn Widget directory
1287 Allows you to edit a directory name in an editable field.
1288 Similar to the @code{file} widget.
1289 @end deffn
1291 @deffn Widget symbol
1292 Allows you to edit a Lisp symbol in an editable field.
1293 @end deffn
1295 @deffn Widget function
1296 Allows you to edit a lambda expression, or a function name with completion.
1297 @end deffn
1299 @deffn Widget variable
1300 Allows you to edit a variable name, with completion.
1301 @end deffn
1303 @deffn Widget integer
1304 Allows you to edit an integer in an editable field.
1305 @end deffn
1307 @deffn Widget number
1308 Allows you to edit a number in an editable field.
1309 @end deffn
1311 @deffn Widget boolean
1312 Allows you to edit a boolean.  In Lisp this means a variable which is
1313 either @code{nil} meaning false, or non-@code{nil} meaning true.
1314 @end deffn
1317 @node composite,  , atoms, Sexp Types
1318 @comment  node-name,  next,  previous,  up
1319 @subsection Composite Sexp Widgets
1320 @cindex composite sexp widgets
1322 The syntax for the composite widget construct is:
1324 @example
1325 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]...  @var{component}...)
1326 @end example
1328 @noindent
1329 where each @var{component} must be a widget type.  Each component widget
1330 will be displayed in the buffer, and will be editable by the user.
1332 @deffn Widget cons
1333 The value of a @code{cons} widget must be a cons-cell whose @sc{car}
1334 and @sc{cdr} have two specified types.  It uses this syntax:
1336 @example
1337 @var{type} ::= (cons [@var{keyword} @var{argument}]...  @var{car-type} @var{cdr-type})
1338 @end example
1339 @end deffn
1341 @deffn Widget choice
1342 The value matched by a @code{choice} widget must have one of a fixed
1343 set of types.  The widget's syntax is as follows:
1345 @example
1346 @var{type} ::= (choice [@var{keyword} @var{argument}]...  @var{type} ... )
1347 @end example
1349 The value of a @code{choice} widget can be anything that matches any of the
1350 @var{types}.
1351 @end deffn
1353 @deffn Widget list
1354 The value of a @code{list} widget must be a list whose element types
1355 match the specified component types:
1357 @example
1358 @var{type} ::= (list [@var{keyword} @var{argument}]...  @var{component-type}...)
1359 @end example
1361 Thus, @code{(list string number)} matches lists of two elements,
1362 the first being a string and the second being a number.
1363 @end deffn
1365 @deffn Widget vector
1366 The @code{vector} widget is like the @code{list} widget but matches
1367 vectors instead of lists.  Thus, @code{(vector string number)} matches
1368 vectors of two elements, the first being a string and the second being
1369 a number.
1370 @end deffn
1372 The above suffice for specifying fixed size lists and vectors.  To get
1373 variable length lists and vectors, you can use a @code{choice},
1374 @code{set}, or @code{repeat} widget together with the @code{:inline}
1375 keyword.  If any component of a composite widget has the
1376 @code{:inline} keyword set, its value must be a list which will then
1377 be spliced into the composite.  For example, to specify a list whose
1378 first element must be a file name, and whose remaining elements should
1379 either be the symbol @code{t} or two strings (file names), you can use
1380 the following widget specification:
1382 @example
1383 (list file
1384       (choice (const t)
1385               (list :inline t
1386                     :value ("foo" "bar")
1387                     string string)))
1388 @end example
1390 The value of a widget of this type will either have the form
1391 @code{(file t)} or @code{(file @var{string} @var{string})}.
1393 This concept of @code{:inline} may be hard to understand.  It was
1394 certainly hard to implement, so instead of confusing you more by
1395 trying to explain it here, I'll just suggest you meditate over it for
1396 a while.
1398 @deffn Widget set
1399 Specifies a type whose values are the lists whose elements all belong
1400 to a given set.  The order of elements of the list is not significant.
1401 Here's the syntax:
1403 @example
1404 @var{type} ::= (set [@var{keyword} @var{argument}]...  @var{permitted-element} ... )
1405 @end example
1407 Use @code{const} to specify each permitted element, like this:
1408 @code{(set (const a) (const b))}.
1409 @end deffn
1411 @deffn Widget repeat
1412 Specifies a list of any number of elements that fit a certain type.
1414 @example
1415 @var{type} ::= (repeat [@var{keyword} @var{argument}]...  @var{type})
1416 @end example
1417 @end deffn
1419 @node Widget Properties, Defining New Widgets, Sexp Types, Top
1420 @comment  node-name,  next,  previous,  up
1421 @section Properties
1422 @cindex properties of widgets
1423 @cindex widget properties
1425 You can examine or set the value of a widget by using the widget object
1426 that was returned by @code{widget-create}.
1428 @defun widget-value widget
1429 Return the current value contained in @var{widget}.
1430 It is an error to call this function on an uninitialized widget.
1431 @end defun
1433 @defun widget-value-set widget value
1434 Set the value contained in @var{widget} to @var{value}.
1435 It is an error to call this function with an invalid @var{value}.
1436 @end defun
1438 @strong{Important:} You @emph{must} call @code{widget-setup} after
1439 modifying the value of a widget before the user is allowed to edit the
1440 widget again.  It is enough to call @code{widget-setup} once if you
1441 modify multiple widgets.  This is currently only necessary if the widget
1442 contains an editing field, but may be necessary for other widgets in the
1443 future.
1445 If your application needs to associate some information with the widget
1446 objects, for example a reference to the item being edited, it can be
1447 done with @code{widget-put} and @code{widget-get}.  The property names
1448 must begin with a @samp{:}.
1450 @defun widget-put widget property value
1451 In @var{widget} set @var{property} to @var{value}.
1452 @var{property} should be a symbol, while @var{value} can be anything.
1453 @end defun
1455 @defun widget-get widget property
1456 In @var{widget} return the value for @var{property}.
1457 @var{property} should be a symbol, the value is what was last set by
1458 @code{widget-put} for @var{property}.
1459 @end defun
1461 @defun widget-member widget property
1462 Non-@code{nil} if @var{widget} has a value (even @code{nil}) for
1463 property @var{property}.
1464 @end defun
1466 Occasionally it can be useful to know which kind of widget you have,
1467 i.e.@: the name of the widget type you gave when the widget was created.
1469 @defun widget-type widget
1470 Return the name of @var{widget}, a symbol.
1471 @end defun
1473 @cindex active widget
1474 @cindex inactive widget
1475 @cindex activate a widget
1476 @cindex deactivate a widget
1477 Widgets can be in two states: active, which means they are modifiable by
1478 the user, or inactive, which means they cannot be modified by the user.
1479 You can query or set the state with the following code:
1481 @lisp
1482 ;; Examine if @var{widget} is active or not.
1483 (if (widget-apply @var{widget} :active)
1484     (message "Widget is active.")
1485   (message "Widget is inactive.")
1487 ;; Make @var{widget} inactive.
1488 (widget-apply @var{widget} :deactivate)
1490 ;; Make @var{widget} active.
1491 (widget-apply @var{widget} :activate)
1492 @end lisp
1494 A widget is inactive if it, or any of its ancestors (found by
1495 following the @code{:parent} link), have been deactivated.  To make sure
1496 a widget is really active, you must therefore activate both it and
1497 all its ancestors.
1499 @lisp
1500 (while widget
1501   (widget-apply widget :activate)
1502   (setq widget (widget-get widget :parent)))
1503 @end lisp
1505 You can check if a widget has been made inactive by examining the value
1506 of the @code{:inactive} keyword.  If this is non-@code{nil}, the widget itself
1507 has been deactivated.  This is different from using the @code{:active}
1508 keyword, in that the latter tells you if the widget @strong{or} any of
1509 its ancestors have been deactivated.  Do not attempt to set the
1510 @code{:inactive} keyword directly.  Use the @code{:activate}
1511 @code{:deactivate} keywords instead.
1514 @node Defining New Widgets, Widget Browser, Widget Properties, Top
1515 @comment  node-name,  next,  previous,  up
1516 @section Defining New Widgets
1517 @cindex new widgets
1518 @cindex defining new widgets
1520 You can define specialized widgets with @code{define-widget}.  It allows
1521 you to create a shorthand for more complex widgets, including specifying
1522 component widgets and new default values for the keyword
1523 arguments.
1525 @defun define-widget name class doc &rest args
1526 Define a new widget type named @var{name} from @code{class}.
1528 @var{name} and class should both be symbols, @code{class} should be one
1529 of the existing widget types.
1531 The third argument @var{doc} is a documentation string for the widget.
1533 After the new widget has been defined, the following two calls will
1534 create identical widgets:
1536 @itemize @bullet
1537 @item
1538 @lisp
1539 (widget-create @var{name})
1540 @end lisp
1542 @item
1543 @lisp
1544 (apply widget-create @var{class} @var{args})
1545 @end lisp
1546 @end itemize
1548 @end defun
1550 Using @code{define-widget} just stores the definition of the widget type
1551 in the @code{widget-type} property of @var{name}, which is what
1552 @code{widget-create} uses.
1554 If you only want to specify defaults for keywords with no complex
1555 conversions, you can use @code{identity} as your conversion function.
1557 The following additional keyword arguments are useful when defining new
1558 widgets:
1559 @table @code
1560 @vindex convert-widget@r{ keyword}
1561 @item :convert-widget
1562 Function to convert a widget type before creating a widget of that
1563 type.  It takes a widget type as an argument, and returns the converted
1564 widget type.  When a widget is created, this function is called for the
1565 widget type and all the widget's parent types, most derived first.
1567 The following predefined functions can be used here:
1569 @defun widget-types-convert-widget widget
1570 Convert @code{:args} as widget types in @var{widget}.
1571 @end defun
1573 @defun widget-value-convert-widget widget
1574 Initialize @code{:value} from @code{:args} in @var{widget}.
1575 @end defun
1577 @vindex copy@r{ keyword}
1578 @item :copy
1579 Function to deep copy a widget type.  It takes a shallow copy of the
1580 widget type as an argument (made by @code{copy-sequence}), and returns a
1581 deep copy.  The purpose of this is to avoid having different instances
1582 of combined widgets share nested attributes.
1584 The following predefined functions can be used here:
1586 @defun widget-types-copy widget
1587 Copy @code{:args} as widget types in @var{widget}.
1588 @end defun
1590 @vindex value-to-internal@r{ keyword}
1591 @item :value-to-internal
1592 Function to convert the value to the internal format.  The function
1593 takes two arguments, a widget and an external value, and returns the
1594 internal value.  The function is called on the present @code{:value}
1595 when the widget is created, and on any value set later with
1596 @code{widget-value-set}.
1598 @vindex value-to-external@r{ keyword}
1599 @item :value-to-external
1600 Function to convert the value to the external format.  The function
1601 takes two arguments, a widget and an internal value, and returns the
1602 external value.  The function is called on the present @code{:value}
1603 when the widget is created, and on any value set later with
1604 @code{widget-value-set}.
1606 @vindex create@r{ keyword}
1607 @item :create
1608 Function to create a widget from scratch.  The function takes one
1609 argument, a widget type, and creates a widget of that type, inserts it
1610 in the buffer, and returns a widget object.
1612 @vindex delete@r{ keyword}
1613 @item :delete
1614 Function to delete a widget.  The function takes one argument, a widget,
1615 and should remove all traces of the widget from the buffer.
1617 The default value is:
1619 @defun widget-default-delete widget
1620 Remove @var{widget} from the buffer.
1621 Delete all @code{:children} and @code{:buttons} in @var{widget}.
1622 @end defun
1624 In most cases you should not change this value, but instead use
1625 @code{:value-delete} to make any additional cleanup.
1627 @vindex value-create@r{ keyword}
1628 @item :value-create
1629 Function to expand the @samp{%v} escape in the format string.  It will
1630 be called with the widget as its argument and should insert a
1631 representation of the widget's value in the buffer.
1633 Nested widgets should be listed in @code{:children} or @code{:buttons}
1634 to make sure they are automatically deleted.
1636 @vindex value-delete@r{ keyword}
1637 @item :value-delete
1638 Should remove the representation of the widget's value from the buffer.
1639 It will be called with the widget as its argument.  It doesn't have to
1640 remove the text, but it should release markers and delete nested widgets
1641 if these are not listed in @code{:children} or @code{:buttons}.
1643 @vindex value-get@r{ keyword}
1644 @item :value-get
1645 Function to extract the value of a widget, as it is displayed in the
1646 buffer.
1648 The following predefined function can be used here:
1650 @defun widget-value-value-get widget
1651 Return the @code{:value} property of @var{widget}.
1652 @end defun
1654 @vindex format-handler@r{ keyword}
1655 @item :format-handler
1656 Function to handle unknown @samp{%} escapes in the format string.  It
1657 will be called with the widget and the character that follows the
1658 @samp{%} as arguments.  You can set this to allow your widget to handle
1659 non-standard escapes.
1661 @findex widget-default-format-handler
1662 You should end up calling @code{widget-default-format-handler} to handle
1663 unknown escape sequences, which will handle the @samp{%h} and any future
1664 escape sequences, as well as give an error for unknown escapes.
1666 @vindex action@r{ keyword}
1667 @item :action
1668 Function to handle user initiated events.  By default, @code{:notify}
1669 the parent.
1671 The following predefined function can be used here:
1673 @defun widget-parent-action widget &optional event
1674 Tell @code{:parent} of @var{widget} to handle the @code{:action}.
1675 Optional @var{event} is the event that triggered the action.
1676 @end defun
1678 @vindex prompt-value@r{ keyword}
1679 @item :prompt-value
1680 Function to prompt for a value in the minibuffer.  The function should
1681 take four arguments, @var{widget}, @var{prompt}, @var{value}, and
1682 @var{unbound} and should return a value for widget entered by the user.
1683 @var{prompt} is the prompt to use.  @var{value} is the default value to
1684 use, unless @var{unbound} is non-@code{nil}, in which case there is no default
1685 value.  The function should read the value using the method most natural
1686 for this widget, and does not have to check that it matches.
1687 @end table
1689 If you want to define a new widget from scratch, use the @code{default}
1690 widget as its base.
1692 @deffn Widget default
1693 Widget used as a base for other widgets.
1695 It provides most of the functionality that is referred to as ``by
1696 default'' in this text.
1697 @end deffn
1699 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
1700 @comment  node-name,  next,  previous,  up
1701 @section Widget Browser
1702 @cindex widget browser
1704 There is a separate package to browse widgets.  This is intended to help
1705 programmers who want to examine the content of a widget.  The browser
1706 shows the value of each keyword, but uses links for certain keywords
1707 such as @samp{:parent}, which avoids printing cyclic structures.
1709 @deffn Command widget-browse @var{widget}
1710 Create a widget browser for @var{widget}.
1711 When called interactively, prompt for @var{widget}.
1712 @end deffn
1714 @deffn Command widget-browse-other-window @var{widget}
1715 Create a widget browser for @var{widget} and show it in another window.
1716 When called interactively, prompt for @var{widget}.
1717 @end deffn
1719 @deffn Command widget-browse-at @var{pos}
1720 Create a widget browser for the widget at @var{pos}.
1721 When called interactively, use the position of point.
1722 @end deffn
1724 @node  Widget Minor Mode, Utilities, Widget Browser, Top
1725 @comment  node-name,  next,  previous,  up
1726 @section Widget Minor Mode
1727 @cindex widget minor mode
1729 There is a minor mode for manipulating widgets in major modes that
1730 don't provide any support for widgets themselves.  This is mostly
1731 intended to be useful for programmers doing experiments.
1733 @deffn Command widget-minor-mode
1734 Toggle minor mode for traversing widgets.
1735 With arg, turn widget mode on if and only if arg is positive.
1736 @end deffn
1738 @defvar widget-minor-mode-keymap
1739 Keymap used in @code{widget-minor-mode}.
1740 @end defvar
1742 @node  Utilities, Widget Wishlist, Widget Minor Mode, Top
1743 @comment  node-name,  next,  previous,  up
1744 @section Utilities.
1745 @cindex utility functions for widgets
1747 @defun widget-prompt-value widget prompt [ value unbound ]
1748 Prompt for a value matching @var{widget}, using @var{prompt}.
1749 The current value is assumed to be @var{value}, unless @var{unbound} is
1750 non-@code{nil}.@refill
1751 @end defun
1753 @defun widget-get-sibling widget
1754 Get the item which @var{widget} is assumed to toggle.
1755 This is only meaningful for radio buttons or checkboxes in a list.
1756 @end defun
1758 @node  Widget Wishlist, GNU Free Documentation License, Utilities, Top
1759 @comment  node-name,  next,  previous,  up
1760 @section Wishlist
1761 @cindex todo
1763 @itemize @bullet
1764 @item
1765 It should be possible to add or remove items from a list with @kbd{C-k}
1766 and @kbd{C-o} (suggested by @sc{rms}).
1768 @item
1769 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
1770 dash (@samp{-}).  The dash should be a button that, when invoked, asks
1771 whether you want to add or delete an item (@sc{rms} wanted to git rid of
1772 the ugly buttons, the dash is my idea).
1774 @item
1775 The @code{menu-choice} tag should be prettier, something like the abbreviated
1776 menus in Open Look.
1778 @item
1779 Finish @code{:tab-order}.
1781 @item
1782 Make indentation work with glyphs and proportional fonts.
1784 @item
1785 Add commands to show overview of object and class hierarchies to the
1786 browser.
1788 @item
1789 Find a way to disable mouse highlight for inactive widgets.
1791 @item
1792 Find a way to make glyphs look inactive.
1794 @item
1795 Add @code{property-list} widget.
1797 @item
1798 Add @code{association-list} widget.
1800 @item
1801 Add @code{key-binding} widget.
1803 @item
1804 Add @code{widget} widget for editing widget specifications.
1806 @item
1807 Find clean way to implement variable length list.
1808 See @code{TeX-printer-list} for an explanation.
1810 @item
1811 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
1813 @item
1814 Add a @code{mailto} widget.
1815 @end itemize
1817 @node GNU Free Documentation License, Index, Widget Wishlist, Top
1818 @appendix GNU Free Documentation License
1819 @include doclicense.texi
1821 @node Index, , GNU Free Documentation License, Top
1822 @comment  node-name,  next,  previous,  up
1823 @unnumbered Index
1825 This is an alphabetical listing of all concepts, functions, commands,
1826 variables, and widgets described in this manual.
1827 @printindex cp
1829 @setchapternewpage odd
1830 @contents
1831 @bye
1833 @ignore
1834    arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
1835 @end ignore