Mercurial > emacs
comparison man/widget.texi @ 30775:33d2bde9a99a
(Top): Add Index in the menu.
(many nodes): Add index entries.
(Index): New node.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sun, 13 Aug 2000 18:28:04 +0000 |
parents | 95bdbefcdac6 |
children | f4da0c6d4336 |
comparison
equal
deleted
inserted
replaced
30774:aa8e1dfb2873 | 30775:33d2bde9a99a |
---|---|
6 @iftex | 6 @iftex |
7 @afourpaper | 7 @afourpaper |
8 @headings double | 8 @headings double |
9 @end iftex | 9 @end iftex |
10 @c %**end of header | 10 @c %**end of header |
11 | |
12 @syncodeindex fn cp | |
13 @syncodeindex vr cp | |
14 @syncodeindex ky cp | |
11 | 15 |
12 @dircategory Emacs | 16 @dircategory Emacs |
13 @direntry | 17 @direntry |
14 * Widget: (widget). Documenting the "widget" package used by the | 18 * Widget: (widget). Documenting the "widget" package used by the |
15 Emacs Custom facility. | 19 Emacs Custom facility. |
30 * Defining New Widgets:: | 34 * Defining New Widgets:: |
31 * Widget Browser:: | 35 * Widget Browser:: |
32 * Widget Minor Mode:: | 36 * Widget Minor Mode:: |
33 * Utilities:: | 37 * Utilities:: |
34 * Widget Wishlist:: | 38 * Widget Wishlist:: |
39 * Index:: | |
35 @end menu | 40 @end menu |
36 | 41 |
37 @node Introduction, User Interface, Top, Top | 42 @node Introduction, User Interface, Top, Top |
38 @comment node-name, next, previous, up | 43 @comment node-name, next, previous, up |
39 @section Introduction | 44 @section Introduction |
40 | 45 |
41 Most graphical user interface toolkits, such as Motif and XView, provide | 46 Most graphical user interface toolkits, such as Motif and XView, provide |
42 a number of standard user interface controls (sometimes known as | 47 a number of standard user interface controls (sometimes known as |
43 `widgets' or `gadgets'). Emacs doesn't really support anything like | 48 `widgets' or `gadgets'). Emacs doesn't really support anything like |
44 this, except for an incredible powerful text ``widget''. On the other | 49 this, except for an incredibly powerful text ``widget''. On the other |
45 hand, Emacs does provide the necessary primitives to implement many | 50 hand, Emacs does provide the necessary primitives to implement many |
46 other widgets within a text buffer. The @code{widget} package | 51 other widgets within a text buffer. The @code{widget} package |
47 simplifies this task. | 52 simplifies this task. |
48 | 53 |
54 @cindex basic widgets | |
55 @cindex widgets, basic types | |
49 The basic widgets are: | 56 The basic widgets are: |
50 | 57 |
51 @table @code | 58 @table @code |
52 @item link | 59 @item link |
53 Areas of text with an associated action. Intended for hypertext links | 60 Areas of text with an associated action. Intended for hypertext links |
66 visible in the buffer. | 73 visible in the buffer. |
67 @item item | 74 @item item |
68 A simple constant widget intended to be used in the @code{menu-choice} and | 75 A simple constant widget intended to be used in the @code{menu-choice} and |
69 @code{radio-button-choice} widgets. | 76 @code{radio-button-choice} widgets. |
70 @item choice-item | 77 @item choice-item |
71 An button item only intended for use in choices. When invoked, the user | 78 A button item only intended for use in choices. When invoked, the user |
72 will be asked to select another option from the choice widget. | 79 will be asked to select another option from the choice widget. |
73 @item toggle | 80 @item toggle |
74 A simple @samp{on}/@samp{off} switch. | 81 A simple @samp{on}/@samp{off} switch. |
75 @item checkbox | 82 @item checkbox |
76 A checkbox (@samp{[ ]}/@samp{[X]}). | 83 A checkbox (@samp{[ ]}/@samp{[X]}). |
77 @item editable-list | 84 @item editable-list |
78 Create an editable list. The user can insert or delete items in the | 85 Create an editable list. The user can insert or delete items in the |
79 list. Each list item is itself a widget. | 86 list. Each list item is itself a widget. |
80 @end table | 87 @end table |
81 | 88 |
82 Now of what possible use can support for widgets be in a text editor? | 89 Now, of what possible use can support for widgets be in a text editor? |
83 I'm glad you asked. The answer is that widgets are useful for | 90 I'm glad you asked. The answer is that widgets are useful for |
84 implementing forms. A @dfn{form} in Emacs is a buffer where the user is | 91 implementing forms. A @dfn{form} in Emacs is a buffer where the user is |
85 supposed to fill out a number of fields, each of which has a specific | 92 supposed to fill out a number of fields, each of which has a specific |
86 meaning. The user is not supposed to change or delete any of the text | 93 meaning. The user is not supposed to change or delete any of the text |
87 between the fields. Examples of forms in Emacs are the @file{forms} | 94 between the fields. Examples of forms in Emacs are the @file{forms} |
88 package (of course), the customize buffers, the mail and news compose | 95 package (of course), the customize buffers, the mail and news compose |
89 modes, and the @sc{html} form support in the @file{w3} browser. | 96 modes, and the @sc{html} form support in the @file{w3} browser. |
90 | 97 |
98 @cindex widget library, why use it | |
91 The advantages for a programmer of using the @code{widget} package to | 99 The advantages for a programmer of using the @code{widget} package to |
92 implement forms are: | 100 implement forms are: |
93 | 101 |
94 @enumerate | 102 @enumerate |
95 @item | 103 @item |
96 More complex field than just editable text are supported. | 104 More complex fields than just editable text are supported. |
97 @item | 105 @item |
98 You can give the user immediate feedback if he enters invalid data in a | 106 You can give the users immediate feedback if they enter invalid data in a |
99 text field, and sometimes prevent entering invalid data. | 107 text field, and sometimes prevent entering invalid data. |
100 @item | 108 @item |
101 You can have fixed sized fields, thus allowing multiple field to be | 109 You can have fixed sized fields, thus allowing multiple fields to be |
102 lined up in columns. | 110 lined up in columns. |
103 @item | 111 @item |
104 It is simple to query or set the value of a field. | 112 It is simple to query or set the value of a field. |
105 @item | 113 @item |
106 Editing happens in buffer, not in the mini-buffer. | 114 Editing happens in the buffer, not in the mini-buffer. |
107 @item | 115 @item |
108 Packages using the library get a uniform look, making them easier for | 116 Packages using the library get a uniform look, making them easier for |
109 the user to learn. | 117 the user to learn. |
110 @item | 118 @item |
111 As support for embedded graphics improve, the widget library will | 119 As support for embedded graphics improve, the widget library will be |
112 extended to support it. This means that your code using the widget | 120 extended to use the GUI features. This means that your code using the |
113 library will also use the new graphic features by automatic. | 121 widget library will also use the new graphic features automatically. |
114 @end enumerate | 122 @end enumerate |
115 | 123 |
116 In order to minimize the code that is loaded by users who does not | 124 In order to minimize the code that is loaded by users who does not |
117 create any widgets, the code has been split in two files: | 125 create any widgets, the code has been split in two files: |
118 | 126 |
127 @cindex widget library, files | |
119 @table @file | 128 @table @file |
120 @item widget.el | 129 @item widget.el |
121 This will declare the user variables, define the function | 130 This will declare the user variables, define the function |
122 @code{widget-define}, and autoload the function @code{widget-create}. | 131 @code{widget-define}, and autoload the function @code{widget-create}. |
123 @item wid-edit.el | 132 @item wid-edit.el |
128 @node User Interface, Programming Example, Introduction, Top | 137 @node User Interface, Programming Example, Introduction, Top |
129 @comment node-name, next, previous, up | 138 @comment node-name, next, previous, up |
130 @section User Interface | 139 @section User Interface |
131 | 140 |
132 A form consist of read only text for documentation and some fields, | 141 A form consist of read only text for documentation and some fields, |
133 where each the fields contain two parts, as tag and a value. The tags | 142 where each field contains two parts, a tag and a value. The tags are |
134 are used to identify the fields, so the documentation can refer to the | 143 used to identify the fields, so the documentation can refer to the |
135 foo field, meaning the field tagged with @samp{Foo}. Here is an example | 144 @samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an |
136 form: | 145 example form: |
137 | 146 |
138 @example | 147 @example |
139 Here is some documentation. | 148 Here is some documentation. |
140 | 149 |
141 Name: @i{My Name} @strong{Choose}: This option | 150 Name: @i{My Name} @strong{Choose}: This option |
167 @end example | 176 @end example |
168 | 177 |
169 The top level widgets in is example are tagged @samp{Name}, | 178 The top level widgets in is example are tagged @samp{Name}, |
170 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers}, | 179 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers}, |
171 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and | 180 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and |
172 @samp{[Reset Form]}. There are basically two thing the user can do within | 181 @samp{[Reset Form]}. There are basically two things the user can do |
173 a form, namely editing the editable text fields and activating the | 182 within a form, namely editing the editable text fields and activating |
174 buttons. | 183 the buttons. |
175 | 184 |
176 @subsection Editable Text Fields | 185 @subsection Editable Text Fields |
177 | 186 |
178 In the example, the value for the @samp{Name} is most likely displayed | 187 In the example, the value for the @samp{Name} is most likely displayed |
179 in an editable text field, and so are values for each of the members of | 188 in an editable text field, and so are values for each of the members of |
192 Face used for other editing fields. | 201 Face used for other editing fields. |
193 @end deffn | 202 @end deffn |
194 | 203 |
195 @subsection Buttons | 204 @subsection Buttons |
196 | 205 |
206 @cindex widget buttons | |
207 @cindex button widgets | |
197 Some portions of the buffer have an associated @dfn{action}, which can | 208 Some portions of the buffer have an associated @dfn{action}, which can |
198 be @dfn{invoked} by a standard key or mouse command. These portions | 209 be @dfn{invoked} by a standard key or mouse command. These portions |
199 are called @dfn{buttons}. The default commands for activating a button | 210 are called @dfn{buttons}. The default commands for activating a button |
200 are: | 211 are: |
201 | 212 |
205 Invoke the button at @var{pos}, defaulting to point. | 216 Invoke the button at @var{pos}, defaulting to point. |
206 If point is not located on a button, invoke the binding in | 217 If point is not located on a button, invoke the binding in |
207 @code{widget-global-map} (by default the global map). | 218 @code{widget-global-map} (by default the global map). |
208 @end deffn | 219 @end deffn |
209 | 220 |
221 @kindex mouse-2, on button widgets | |
210 @item mouse-2 | 222 @item mouse-2 |
211 @deffn Command widget-button-click @var{event} | 223 @deffn Command widget-button-click @var{event} |
212 Invoke the button at the location of the mouse pointer. If the mouse | 224 Invoke the button at the location of the mouse pointer. If the mouse |
213 pointer is located in an editable text field, invoke the binding in | 225 pointer is located in an editable text field, invoke the binding in |
214 @code{widget-global-map} (by default the global map). | 226 @code{widget-global-map} (by default the global map). |
217 | 229 |
218 There are several different kind of buttons, all of which are present in | 230 There are several different kind of buttons, all of which are present in |
219 the example: | 231 the example: |
220 | 232 |
221 @table @emph | 233 @table @emph |
222 @item The Option Field Tags. | 234 @cindex option field tag |
235 @item The Option Field Tags | |
223 When you invoke one of these buttons, you will be asked to choose | 236 When you invoke one of these buttons, you will be asked to choose |
224 between a number of different options. This is how you edit an option | 237 between a number of different options. This is how you edit an option |
225 field. Option fields are created by the @code{menu-choice} widget. In | 238 field. Option fields are created by the @code{menu-choice} widget. In |
226 the example, @samp{@b{Choose}} is an option field tag. | 239 the example, @samp{@b{Choose}} is an option field tag. |
227 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons. | 240 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons |
228 Activating these will insert or delete elements from a editable list. | 241 Activating these will insert or delete elements from an editable list. |
229 The list is created by the @code{editable-list} widget. | 242 The list is created by the @code{editable-list} widget. |
230 @item Embedded Buttons. | 243 @cindex embedded buttons |
244 @item Embedded Buttons | |
231 The @samp{@b{_other work_}} is an example of an embedded | 245 The @samp{@b{_other work_}} is an example of an embedded |
232 button. Embedded buttons are not associated with a fields, but can serve | 246 button. Embedded buttons are not associated with a fields, but can serve |
233 any purpose, such as implementing hypertext references. They are | 247 any purpose, such as implementing hypertext references. They are |
234 usually created by the @code{link} widget. | 248 usually created by the @code{link} widget. |
235 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons. | 249 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons |
236 Activating one of these will convert it to the other. This is useful | 250 Activating one of these will convert it to the other. This is useful |
237 for implementing multiple-choice fields. You can create it wit | 251 for implementing multiple-choice fields. You can create it with the |
238 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons. | 252 @code{checkbox} widget. |
253 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons | |
239 Only one radio button in a @code{radio-button-choice} widget can be | 254 Only one radio button in a @code{radio-button-choice} widget can be |
240 selected at any time. When you invoke one of the unselected radio | 255 selected at any time. When you invoke one of the unselected radio |
241 buttons, it will be selected and the previous selected radio button will | 256 buttons, it will be selected and the previous selected radio button will |
242 become unselected. | 257 become unselected. |
243 @item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons. | 258 @item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons |
244 These are explicit buttons made with the @code{push-button} widget. The main | 259 These are explicit buttons made with the @code{push-button} widget. The |
245 difference from the @code{link} widget is that the buttons are will be | 260 main difference from the @code{link} widget is that the buttons will be |
246 displayed as GUI buttons when possible. | 261 displayed as GUI buttons when possible. |
247 enough. | |
248 @end table | 262 @end table |
249 | 263 |
250 To make them easier to locate, buttons are emphasized in the buffer. | 264 To make them easier to locate, buttons are emphasized in the buffer. |
251 | 265 |
252 @deffn Face widget-button-face | 266 @deffn Face widget-button-face |
253 Face used for buttons. | 267 Face used for buttons. |
254 @end deffn | 268 @end deffn |
255 | 269 |
256 @defopt widget-mouse-face | 270 @defopt widget-mouse-face |
257 Face used for buttons when the mouse pointer is above it. | 271 Face used for highlighting a button when the mouse pointer moves across |
272 it. | |
258 @end defopt | 273 @end defopt |
259 | 274 |
260 @subsection Navigation | 275 @subsection Navigation |
261 | 276 |
262 You can use all the normal Emacs commands to move around in a form | 277 You can use all the normal Emacs commands to move around in a form |
275 | 290 |
276 @node Programming Example, Setting Up the Buffer, User Interface, Top | 291 @node Programming Example, Setting Up the Buffer, User Interface, Top |
277 @comment node-name, next, previous, up | 292 @comment node-name, next, previous, up |
278 @section Programming Example | 293 @section Programming Example |
279 | 294 |
295 @cindex widgets, programming example | |
296 @cindex example of using widgets | |
280 Here is the code to implement the user interface example (@pxref{User | 297 Here is the code to implement the user interface example (@pxref{User |
281 Interface}). | 298 Interface}). |
282 | 299 |
283 @lisp | 300 @lisp |
284 (require 'widget) | 301 (require 'widget) |
387 @defun widget-delete widget | 404 @defun widget-delete widget |
388 Delete @var{widget} and remove it from the buffer. | 405 Delete @var{widget} and remove it from the buffer. |
389 @end defun | 406 @end defun |
390 | 407 |
391 @defun widget-setup | 408 @defun widget-setup |
392 Setup a buffer to support widgets. | 409 Set up a buffer to support widgets. |
393 | 410 |
394 This should be called after creating all the widgets and before allowing | 411 This should be called after creating all the widgets and before allowing |
395 the user to edit them. | 412 the user to edit them. |
396 @refill | 413 @refill |
397 @end defun | 414 @end defun |
399 If you want to insert text outside the widgets in the form, the | 416 If you want to insert text outside the widgets in the form, the |
400 recommended way to do that is with @code{widget-insert}. | 417 recommended way to do that is with @code{widget-insert}. |
401 | 418 |
402 @defun widget-insert | 419 @defun widget-insert |
403 Insert the arguments, either strings or characters, at point. | 420 Insert the arguments, either strings or characters, at point. |
404 The inserted text will be read only. | 421 The inserted text will be read-only. |
405 @end defun | 422 @end defun |
406 | 423 |
407 There is a standard widget keymap which you might find useful. | 424 There is a standard widget keymap which you might find useful. |
408 | 425 |
426 @findex widget-button-press | |
427 @findex widget-button-click | |
409 @defvr Const widget-keymap | 428 @defvr Const widget-keymap |
410 A keymap with the global keymap as its parent.@* | 429 A keymap with the global keymap as its parent.@* |
411 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and | 430 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and |
412 @code{widget-backward}, respectively. @kbd{@key{RET}} and @kbd{mouse-2} | 431 @code{widget-backward}, respectively. @kbd{@key{RET}} and @kbd{mouse-2} |
413 are bound to @code{widget-button-press} and | 432 are bound to @code{widget-button-press} and |
414 @code{widget-button-}.@refill | 433 @code{widget-button-click}.@refill |
415 @end defvr | 434 @end defvr |
416 | 435 |
417 @defvar widget-global-map | 436 @defvar widget-global-map |
418 Keymap used by @code{widget-button-press} and @code{widget-button-click} | 437 Keymap used by @code{widget-button-press} and @code{widget-button-click} |
419 when not on a button. By default this is @code{global-map}. | 438 when not on a button. By default this is @code{global-map}. |
432 | 451 |
433 Where, @var{name} is a widget name, @var{keyword} is the name of a | 452 Where, @var{name} is a widget name, @var{keyword} is the name of a |
434 property, @var{argument} is the value of the property, and @var{args} | 453 property, @var{argument} is the value of the property, and @var{args} |
435 are interpreted in a widget specific way. | 454 are interpreted in a widget specific way. |
436 | 455 |
437 There following keyword arguments that apply to all widgets: | 456 @cindex keyword arguments |
457 The following keyword arguments that apply to all widgets: | |
438 | 458 |
439 @table @code | 459 @table @code |
460 @vindex value@r{ keyword} | |
440 @item :value | 461 @item :value |
441 The initial value for widgets of this type. | 462 The initial value for widgets of this type. |
442 | 463 |
464 @vindex format@r{ keyword} | |
443 @item :format | 465 @item :format |
444 This string will be inserted in the buffer when you create a widget. | 466 This string will be inserted in the buffer when you create a widget. |
445 The following @samp{%} escapes are available: | 467 The following @samp{%} escapes are available: |
446 | 468 |
447 @table @samp | 469 @table @samp |
487 | 509 |
488 @item %% | 510 @item %% |
489 Insert a literal @samp{%}. | 511 Insert a literal @samp{%}. |
490 @end table | 512 @end table |
491 | 513 |
514 @vindex button-face@r{ keyword} | |
492 @item :button-face | 515 @item :button-face |
493 Face used to highlight text inside %[ %] in the format. | 516 Face used to highlight text inside %[ %] in the format. |
494 | 517 |
518 @vindex button-prefix@r{ keyword} | |
519 @vindex button-suffix@r{ keyword} | |
495 @item :button-prefix | 520 @item :button-prefix |
496 @itemx :button-suffix | 521 @itemx :button-suffix |
497 | |
498 Text around %[ %] in the format. | 522 Text around %[ %] in the format. |
499 | 523 |
500 These can be | 524 These can be |
501 @table @emph | 525 @table @emph |
502 @item nil | 526 @item nil |
507 | 531 |
508 @item a symbol | 532 @item a symbol |
509 The value of the symbol is expanded according to this table. | 533 The value of the symbol is expanded according to this table. |
510 @end table | 534 @end table |
511 | 535 |
536 @vindex doc@r{ keyword} | |
512 @item :doc | 537 @item :doc |
513 The string inserted by the @samp{%d} escape in the format | 538 The string inserted by the @samp{%d} escape in the format |
514 string. | 539 string. |
515 | 540 |
541 @vindex tag@r{ keyword} | |
516 @item :tag | 542 @item :tag |
517 The string inserted by the @samp{%t} escape in the format | 543 The string inserted by the @samp{%t} escape in the format |
518 string. | 544 string. |
519 | 545 |
546 @vindex tag-glyph@r{ keyword} | |
520 @item :tag-glyph | 547 @item :tag-glyph |
521 Name of image to use instead of the string specified by `:tag' on | 548 Name of image to use instead of the string specified by @code{:tag} on |
522 Emacsen that supports it. | 549 Emacsen that supports it. |
523 | 550 |
551 @vindex help-echo@r{ keyword} | |
524 @item :help-echo | 552 @item :help-echo |
525 Message displayed whenever you move to the widget with either | 553 Message displayed whenever you move to the widget with either |
526 @code{widget-forward} or @code{widget-backward}. | 554 @code{widget-forward} or @code{widget-backward}. |
527 | 555 |
556 @vindex indent@r{ keyword} | |
528 @item :indent | 557 @item :indent |
529 An integer indicating the absolute number of spaces to indent children | 558 An integer indicating the absolute number of spaces to indent children |
530 of this widget. | 559 of this widget. |
531 | 560 |
561 @vindex offset@r{ keyword} | |
532 @item :offset | 562 @item :offset |
533 An integer indicating how many extra spaces to add to the widget's | 563 An integer indicating how many extra spaces to add to the widget's |
534 grandchildren compared to this widget. | 564 grandchildren compared to this widget. |
535 | 565 |
566 @vindex extra-offset@r{ keyword} | |
536 @item :extra-offset | 567 @item :extra-offset |
537 An integer indicating how many extra spaces to add to the widget's | 568 An integer indicating how many extra spaces to add to the widget's |
538 children compared to this widget. | 569 children compared to this widget. |
539 | 570 |
571 @vindex notify@r{ keyword} | |
540 @item :notify | 572 @item :notify |
541 A function called each time the widget or a nested widget is changed. | 573 A function called each time the widget or a nested widget is changed. |
542 The function is called with two or three arguments. The first argument | 574 The function is called with two or three arguments. The first argument |
543 is the widget itself, the second argument is the widget that was | 575 is the widget itself, the second argument is the widget that was |
544 changed, and the third argument is the event leading to the change, if | 576 changed, and the third argument is the event leading to the change, if |
545 any. | 577 any. |
546 | 578 |
579 @vindex menu-tag@r{ keyword} | |
547 @item :menu-tag | 580 @item :menu-tag |
548 Tag used in the menu when the widget is used as an option in a | 581 Tag used in the menu when the widget is used as an option in a |
549 @code{menu-choice} widget. | 582 @code{menu-choice} widget. |
550 | 583 |
584 @vindex menu-tag-get@r{ keyword} | |
551 @item :menu-tag-get | 585 @item :menu-tag-get |
552 Function used for finding the tag when the widget is used as an option | 586 Function used for finding the tag when the widget is used as an option |
553 in a @code{menu-choice} widget. By default, the tag used will be either the | 587 in a @code{menu-choice} widget. By default, the tag used will be either the |
554 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | 588 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} |
555 representation of the @code{:value} property if not. | 589 representation of the @code{:value} property if not. |
556 | 590 |
591 @vindex match@r{ keyword} | |
557 @item :match | 592 @item :match |
558 Should be a function called with two arguments, the widget and a value, | 593 Should be a function called with two arguments, the widget and a value, |
559 and returning non-nil if the widget can represent the specified value. | 594 and returning non-nil if the widget can represent the specified value. |
560 | 595 |
596 @vindex validate@r{ keyword} | |
561 @item :validate | 597 @item :validate |
562 A function which takes a widget as an argument, and return nil if the | 598 A function which takes a widget as an argument, and returns @code{nil} |
563 widget's current value is valid for the widget. Otherwise it should | 599 if the widget's current value is valid for the widget. Otherwise it |
564 return the widget containing the invalid data, and set that widget's | 600 should return the widget containing the invalid data, and set that |
565 @code{:error} property to a string explaining the error. | 601 widget's @code{:error} property to a string explaining the error. |
566 | 602 |
567 The following predefined function can be used: | 603 The following predefined function can be used: |
568 | 604 |
569 @defun widget-children-validate widget | 605 @defun widget-children-validate widget |
570 All the @code{:children} of @var{widget} must be valid. | 606 All the @code{:children} of @var{widget} must be valid. |
571 @end defun | 607 @end defun |
572 | 608 |
609 @vindex tab-order@r{ keyword} | |
573 @item :tab-order | 610 @item :tab-order |
574 Specify the order in which widgets are traversed with | 611 Specify the order in which widgets are traversed with |
575 @code{widget-forward} or @code{widget-backward}. This is only partially | 612 @code{widget-forward} or @code{widget-backward}. This is only partially |
576 implemented. | 613 implemented. |
577 | 614 |
587 @item | 624 @item |
588 When on a widget with no tabbing order specified, go to the next widget | 625 When on a widget with no tabbing order specified, go to the next widget |
589 in the buffer with a positive tabbing order, or @code{nil} | 626 in the buffer with a positive tabbing order, or @code{nil} |
590 @end enumerate | 627 @end enumerate |
591 | 628 |
629 @vindex parent@r{ keyword} | |
592 @item :parent | 630 @item :parent |
593 The parent of a nested widget (e.g. a @code{menu-choice} item or an | 631 The parent of a nested widget (e.g. a @code{menu-choice} item or an |
594 element of a @code{editable-list} widget). | 632 element of a @code{editable-list} widget). |
595 | 633 |
634 @vindex sibling-args@r{ keyword} | |
596 @item :sibling-args | 635 @item :sibling-args |
597 This keyword is only used for members of a @code{radio-button-choice} or | 636 This keyword is only used for members of a @code{radio-button-choice} or |
598 @code{checklist}. The value should be a list of extra keyword | 637 @code{checklist}. The value should be a list of extra keyword |
599 arguments, which will be used when creating the @code{radio-button} or | 638 arguments, which will be used when creating the @code{radio-button} or |
600 @code{checkbox} associated with this item. | 639 @code{checkbox} associated with this item. |
602 @end table | 641 @end table |
603 | 642 |
604 @deffn {User Option} widget-glyph-directory | 643 @deffn {User Option} widget-glyph-directory |
605 Directory where glyphs are found. | 644 Directory where glyphs are found. |
606 Widget will look here for a file with the same name as specified for the | 645 Widget will look here for a file with the same name as specified for the |
607 image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension. | 646 image, with either a @file{.xpm} (if supported) or @file{.xbm} extension. |
608 @end deffn | 647 @end deffn |
609 | 648 |
610 @deffn{User Option} widget-glyph-enable | 649 @deffn{User Option} widget-glyph-enable |
611 If non-nil, allow glyphs to appear on displays where they are supported. | 650 If non-nil, allow glyphs to appear on displays where they are supported. |
612 @end deffn | 651 @end deffn |
631 @end menu | 670 @end menu |
632 | 671 |
633 @node link, url-link, Basic Types, Basic Types | 672 @node link, url-link, Basic Types, Basic Types |
634 @comment node-name, next, previous, up | 673 @comment node-name, next, previous, up |
635 @subsection The @code{link} Widget | 674 @subsection The @code{link} Widget |
675 @findex link@r{ widget} | |
636 | 676 |
637 Syntax: | 677 Syntax: |
638 | 678 |
639 @example | 679 @example |
640 TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ]) | 680 TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ]) |
655 @end defopt | 695 @end defopt |
656 | 696 |
657 @node url-link, info-link, link, Basic Types | 697 @node url-link, info-link, link, Basic Types |
658 @comment node-name, next, previous, up | 698 @comment node-name, next, previous, up |
659 @subsection The @code{url-link} Widget | 699 @subsection The @code{url-link} Widget |
700 @findex url-link@r{ widget} | |
660 | 701 |
661 Syntax: | 702 Syntax: |
662 | 703 |
663 @example | 704 @example |
664 TYPE ::= (url-link [KEYWORD ARGUMENT]... URL) | 705 TYPE ::= (url-link [KEYWORD ARGUMENT]... URL) |
665 @end example | 706 @end example |
666 | 707 |
708 @findex browse-url-browser-function@r{, and @code{url-link} widget} | |
667 When this link is invoked, the @sc{www} browser specified by | 709 When this link is invoked, the @sc{www} browser specified by |
668 @code{browse-url-browser-function} will be called with @var{url}. | 710 @code{browse-url-browser-function} will be called with @var{url}. |
669 | 711 |
670 @node info-link, push-button, url-link, Basic Types | 712 @node info-link, push-button, url-link, Basic Types |
671 @comment node-name, next, previous, up | 713 @comment node-name, next, previous, up |
672 @subsection The @code{info-link} Widget | 714 @subsection The @code{info-link} Widget |
715 @findex info-link@r{ widget} | |
673 | 716 |
674 Syntax: | 717 Syntax: |
675 | 718 |
676 @example | 719 @example |
677 TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS) | 720 TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS) |
678 @end example | 721 @end example |
679 | 722 |
680 When this link is invoked, the built-in info browser is started on | 723 When this link is invoked, the built-in Info reader is started on |
681 @var{address}. | 724 @var{address}. |
682 | 725 |
683 @node push-button, editable-field, info-link, Basic Types | 726 @node push-button, editable-field, info-link, Basic Types |
684 @comment node-name, next, previous, up | 727 @comment node-name, next, previous, up |
685 @subsection The @code{push-button} Widget | 728 @subsection The @code{push-button} Widget |
729 @findex push-button@r{ widget} | |
686 | 730 |
687 Syntax: | 731 Syntax: |
688 | 732 |
689 @example | 733 @example |
690 TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ]) | 734 TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ]) |
691 @end example | 735 @end example |
692 | 736 |
693 The @var{value}, if present, is used to initialize the @code{:value} | 737 The @var{value}, if present, is used to initialize the @code{:value} |
694 property. The value should be a string, which will be inserted in the | 738 property. The value should be a string, which will be inserted in the |
695 buffer. | 739 buffer. |
696 | 740 |
697 By default the tag will be shown in brackets. | 741 By default the tag will be shown in brackets. |
698 | 742 |
699 @defopt widget-push-button-prefix | 743 @defopt widget-push-button-prefix |
705 @end defopt | 749 @end defopt |
706 | 750 |
707 @node editable-field, text, push-button, Basic Types | 751 @node editable-field, text, push-button, Basic Types |
708 @comment node-name, next, previous, up | 752 @comment node-name, next, previous, up |
709 @subsection The @code{editable-field} Widget | 753 @subsection The @code{editable-field} Widget |
754 @findex editable-field@r{ widget} | |
710 | 755 |
711 Syntax: | 756 Syntax: |
712 | 757 |
713 @example | 758 @example |
714 TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ]) | 759 TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ]) |
716 | 761 |
717 The @var{value}, if present, is used to initialize the @code{:value} | 762 The @var{value}, if present, is used to initialize the @code{:value} |
718 property. The value should be a string, which will be inserted in | 763 property. The value should be a string, which will be inserted in |
719 field. This widget will match all string values. | 764 field. This widget will match all string values. |
720 | 765 |
721 The following extra properties are recognized. | 766 The following extra properties are recognized: |
722 | 767 |
723 @table @code | 768 @table @code |
769 @vindex size@r{ keyword} | |
724 @item :size | 770 @item :size |
725 The width of the editable field.@* | 771 The width of the editable field.@* |
726 By default the field will reach to the end of the line. | 772 By default the field will reach to the end of the line. |
727 | 773 |
774 @vindex value-face@r{ keyword} | |
728 @item :value-face | 775 @item :value-face |
729 Face used for highlighting the editable field. Default is | 776 Face used for highlighting the editable field. Default is |
730 @code{widget-field-face}. | 777 @code{widget-field-face}, see @ref{User Interface}. |
731 | 778 |
779 @vindex secret@r{ keyword} | |
732 @item :secret | 780 @item :secret |
733 Character used to display the value. You can set this to e.g. @code{?*} | 781 Character used to display the value. You can set this to e.g. @code{?*} |
734 if the field contains a password or other secret information. By | 782 if the field contains a password or other secret information. By |
735 default, the value is not secret. | 783 default, this is nil, and the value is not secret. |
736 | 784 |
785 @vindex valid-regexp@r{ keyword} | |
737 @item :valid-regexp | 786 @item :valid-regexp |
738 By default the @code{:validate} function will match the content of the | 787 By default the @code{:validate} function will match the content of the |
739 field with the value of this attribute. The default value is @code{""} | 788 field with the value of this attribute. The default value is @code{""} |
740 which matches everything. | 789 which matches everything. |
741 | 790 |
791 @vindex keymap@r{ keyword} | |
792 @vindex widget-field-keymap | |
742 @item :keymap | 793 @item :keymap |
743 Keymap used in the editable field. The default value is | 794 Keymap used in the editable field. The default value is |
744 @code{widget-field-keymap}, which allows you to use all the normal | 795 @code{widget-field-keymap}, which allows you to use all the normal |
745 editing commands, even if the buffers major mode suppress some of them. | 796 editing commands, even if the buffer's major mode suppresses some of |
746 Pressing return invokes the function specified by @code{:action}. | 797 them. Pressing @key{RET} invokes the function specified by |
798 @code{:action}. | |
747 @end table | 799 @end table |
748 | 800 |
749 @node text, menu-choice, editable-field, Basic Types | 801 @node text, menu-choice, editable-field, Basic Types |
750 @comment node-name, next, previous, up | 802 @comment node-name, next, previous, up |
751 @subsection The @code{text} Widget | 803 @subsection The @code{text} Widget |
752 | 804 @findex text@r{ widget} |
805 | |
806 @vindex widget-text-keymap | |
753 This is just like @code{editable-field}, but intended for multiline text | 807 This is just like @code{editable-field}, but intended for multiline text |
754 fields. The default @code{:keymap} is @code{widget-text-keymap}, which | 808 fields. The default @code{:keymap} is @code{widget-text-keymap}, which |
755 does not rebind the return key. | 809 does not rebind the @key{RET} key. |
756 | 810 |
757 @node menu-choice, radio-button-choice, text, Basic Types | 811 @node menu-choice, radio-button-choice, text, Basic Types |
758 @comment node-name, next, previous, up | 812 @comment node-name, next, previous, up |
759 @subsection The @code{menu-choice} Widget | 813 @subsection The @code{menu-choice} Widget |
814 @findex menu-choice@r{ widget} | |
760 | 815 |
761 Syntax: | 816 Syntax: |
762 | 817 |
763 @example | 818 @example |
764 TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... ) | 819 TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... ) |
768 value will be that of the chosen @var{type} argument. This widget will | 823 value will be that of the chosen @var{type} argument. This widget will |
769 match any value matching at least one of the specified @var{type} | 824 match any value matching at least one of the specified @var{type} |
770 arguments. | 825 arguments. |
771 | 826 |
772 @table @code | 827 @table @code |
828 @vindex void@r{ keyword} | |
773 @item :void | 829 @item :void |
774 Widget type used as a fallback when the value does not match any of the | 830 Widget type used as a fallback when the value does not match any of the |
775 specified @var{type} arguments. | 831 specified @var{type} arguments. |
776 | 832 |
833 @vindex case-fold@r{ keyword} | |
777 @item :case-fold | 834 @item :case-fold |
778 Set this to nil if you don't want to ignore case when prompting for a | 835 Set this to nil if you don't want to ignore case when prompting for a |
779 choice through the minibuffer. | 836 choice through the minibuffer. |
780 | 837 |
838 @vindex children@r{ keyword} | |
781 @item :children | 839 @item :children |
782 A list whose car is the widget representing the currently chosen type in | 840 A list whose @code{car} is the widget representing the currently chosen |
783 the buffer. | 841 type in the buffer. |
784 | 842 |
843 @vindex choice@r{ keyword} | |
785 @item :choice | 844 @item :choice |
786 The current chosen type | 845 The current chosen type. |
787 | 846 |
847 @vindex args@r{ keyword} | |
788 @item :args | 848 @item :args |
789 The list of types. | 849 The list of types. |
790 @end table | 850 @end table |
791 | 851 |
792 @node radio-button-choice, item, menu-choice, Basic Types | 852 @node radio-button-choice, item, menu-choice, Basic Types |
793 @comment node-name, next, previous, up | 853 @comment node-name, next, previous, up |
794 @subsection The @code{radio-button-choice} Widget | 854 @subsection The @code{radio-button-choice} Widget |
855 @findex radio-button-choice@r{ widget} | |
795 | 856 |
796 Syntax: | 857 Syntax: |
797 | 858 |
798 @example | 859 @example |
799 TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... ) | 860 TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... ) |
805 arguments. | 866 arguments. |
806 | 867 |
807 The following extra properties are recognized. | 868 The following extra properties are recognized. |
808 | 869 |
809 @table @code | 870 @table @code |
871 @vindex entry-format@r{ keyword} | |
810 @item :entry-format | 872 @item :entry-format |
811 This string will be inserted for each entry in the list. | 873 This string will be inserted for each entry in the list. |
812 The following @samp{%} escapes are available: | 874 The following @samp{%} escapes are available: |
813 @table @samp | 875 @table @samp |
814 @item %v | 876 @item %v |
815 Replaced with the buffer representation of the @var{type} widget. | 877 Replace with the buffer representation of the @var{type} widget. |
816 @item %b | 878 @item %b |
817 Replace with the radio button. | 879 Replace with the radio button. |
818 @item %% | 880 @item %% |
819 Insert a literal @samp{%}. | 881 Insert a literal @samp{%}. |
820 @end table | 882 @end table |
821 | 883 |
822 @item button-args | 884 @vindex button-args@r{ keyword} |
885 @item :button-args | |
823 A list of keywords to pass to the radio buttons. Useful for setting | 886 A list of keywords to pass to the radio buttons. Useful for setting |
824 e.g. the @samp{:help-echo} for each button. | 887 e.g. the @samp{:help-echo} for each button. |
825 | 888 |
889 @vindex buttons@r{ keyword} | |
826 @item :buttons | 890 @item :buttons |
827 The widgets representing the radio buttons. | 891 The widgets representing the radio buttons. |
828 | 892 |
893 @vindex children@r{ keyword} | |
829 @item :children | 894 @item :children |
830 The widgets representing each type. | 895 The widgets representing each type. |
831 | 896 |
897 @vindex choice@r{ keyword} | |
832 @item :choice | 898 @item :choice |
833 The current chosen type | 899 The current chosen type |
834 | 900 |
901 @vindex args@r{ keyword} | |
835 @item :args | 902 @item :args |
836 The list of types. | 903 The list of types. |
837 @end table | 904 @end table |
838 | 905 |
839 You can add extra radio button items to a @code{radio-button-choice} | 906 You can add extra radio button items to a @code{radio-button-choice} |
840 widget after it has been created with the function | 907 widget after it has been created with the function |
841 @code{widget-radio-add-item}. | 908 @code{widget-radio-add-item}. |
842 | 909 |
843 @defun widget-radio-add-item widget type | 910 @defun widget-radio-add-item widget type |
844 Add to @code{radio-button-choice} widget @var{widget} a new radio button item of type | 911 Add to @code{radio-button-choice} widget @var{widget} a new radio button |
845 @var{type}. | 912 item of type @var{type}. |
846 @end defun | 913 @end defun |
847 | 914 |
848 Please note that such items added after the @code{radio-button-choice} | 915 Please note that such items added after the @code{radio-button-choice} |
849 widget has been created will @strong{not} be properly destructed when | 916 widget has been created will @strong{not} be properly destructed when |
850 you call @code{widget-delete}. | 917 you call @code{widget-delete}. |
851 | 918 |
852 @node item, choice-item, radio-button-choice, Basic Types | 919 @node item, choice-item, radio-button-choice, Basic Types |
853 @comment node-name, next, previous, up | 920 @comment node-name, next, previous, up |
854 @subsection The @code{item} Widget | 921 @subsection The @code{item} Widget |
922 @findex item@r{ widget} | |
855 | 923 |
856 Syntax: | 924 Syntax: |
857 | 925 |
858 @example | 926 @example |
859 ITEM ::= (item [KEYWORD ARGUMENT]... VALUE) | 927 ITEM ::= (item [KEYWORD ARGUMENT]... VALUE) |
864 buffer. This widget will only match the specified value. | 932 buffer. This widget will only match the specified value. |
865 | 933 |
866 @node choice-item, toggle, item, Basic Types | 934 @node choice-item, toggle, item, Basic Types |
867 @comment node-name, next, previous, up | 935 @comment node-name, next, previous, up |
868 @subsection The @code{choice-item} Widget | 936 @subsection The @code{choice-item} Widget |
937 @findex choice-item@r{ widget} | |
869 | 938 |
870 Syntax: | 939 Syntax: |
871 | 940 |
872 @example | 941 @example |
873 ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE) | 942 ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE) |
880 the specified value. | 949 the specified value. |
881 | 950 |
882 @node toggle, checkbox, choice-item, Basic Types | 951 @node toggle, checkbox, choice-item, Basic Types |
883 @comment node-name, next, previous, up | 952 @comment node-name, next, previous, up |
884 @subsection The @code{toggle} Widget | 953 @subsection The @code{toggle} Widget |
954 @findex toggle@r{ widget} | |
885 | 955 |
886 Syntax: | 956 Syntax: |
887 | 957 |
888 @example | 958 @example |
889 TYPE ::= (toggle [KEYWORD ARGUMENT]...) | 959 TYPE ::= (toggle [KEYWORD ARGUMENT]...) |
890 @end example | 960 @end example |
891 | 961 |
892 The widget has two possible states, `on' and `off', which correspond to | 962 The widget has two possible states, @samp{on} and @samp{off}, which |
893 a @code{t} or @code{nil} value respectively. | 963 correspond to a @code{t} or @code{nil} value, respectively. |
894 | 964 |
895 The following extra properties are recognized. | 965 The following extra properties are recognized: |
896 | 966 |
897 @table @code | 967 @table @code |
898 @item :on | 968 @item :on |
899 String representing the `on' state. By default the string @samp{on}. | 969 A string representing the @samp{on} state. By default the string |
970 @samp{on}. | |
900 @item :off | 971 @item :off |
901 String representing the `off' state. By default the string @samp{off}. | 972 A string representing the @samp{off} state. By default the string |
973 @samp{off}. | |
974 @vindex on-glyph@r{ keyword} | |
902 @item :on-glyph | 975 @item :on-glyph |
903 Name of a glyph to be used instead of the `:on' text string, on emacsen | 976 Name of a glyph to be used instead of the @samp{:on} text string, on |
904 that supports it. | 977 emacsen that supports this. |
978 @vindex off-glyph@r{ keyword} | |
905 @item :off-glyph | 979 @item :off-glyph |
906 Name of a glyph to be used instead of the `:off' text string, on emacsen | 980 Name of a glyph to be used instead of the @samp{:off} text string, on |
907 that supports it. | 981 emacsen that supports this. |
908 @end table | 982 @end table |
909 | 983 |
910 @node checkbox, checklist, toggle, Basic Types | 984 @node checkbox, checklist, toggle, Basic Types |
911 @comment node-name, next, previous, up | 985 @comment node-name, next, previous, up |
912 @subsection The @code{checkbox} Widget | 986 @subsection The @code{checkbox} Widget |
913 | 987 @findex checkbox@r{ widget} |
914 The widget has two possible states, `selected' and `unselected', which | 988 |
915 corresponds to a @code{t} or @code{nil} value. | 989 This widget has two possible states, @samp{selected} and |
990 @samp{unselected}, which corresponds to a @code{t} or @code{nil} value. | |
916 | 991 |
917 Syntax: | 992 Syntax: |
918 | 993 |
919 @example | 994 @example |
920 TYPE ::= (checkbox [KEYWORD ARGUMENT]...) | 995 TYPE ::= (checkbox [KEYWORD ARGUMENT]...) |
921 @end example | 996 @end example |
922 | 997 |
923 @node checklist, editable-list, checkbox, Basic Types | 998 @node checklist, editable-list, checkbox, Basic Types |
924 @comment node-name, next, previous, up | 999 @comment node-name, next, previous, up |
925 @subsection The @code{checklist} Widget | 1000 @subsection The @code{checklist} Widget |
1001 @findex checklist@r{ widget} | |
926 | 1002 |
927 Syntax: | 1003 Syntax: |
928 | 1004 |
929 @example | 1005 @example |
930 TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... ) | 1006 TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... ) |
931 @end example | 1007 @end example |
932 | 1008 |
933 The @var{type} arguments represents each checklist item. The widget's | 1009 The @var{type} arguments represent each checklist item. The widget's |
934 value will be a list containing the values of all ticked @var{type} | 1010 value will be a list containing the values of all checked @var{type} |
935 arguments. The checklist widget will match a list whose elements all | 1011 arguments. The checklist widget will match a list whose elements all |
936 match at least one of the specified @var{type} arguments. | 1012 match at least one of the specified @var{type} arguments. |
937 | 1013 |
938 The following extra properties are recognized. | 1014 The following extra properties are recognized: |
939 | 1015 |
940 @table @code | 1016 @table @code |
1017 @vindex entry-format@r{ keyword} | |
941 @item :entry-format | 1018 @item :entry-format |
942 This string will be inserted for each entry in the list. | 1019 This string will be inserted for each entry in the list. |
943 The following @samp{%} escapes are available: | 1020 The following @samp{%} escapes are available: |
944 @table @samp | 1021 @table @samp |
945 @item %v | 1022 @item %v |
948 Replace with the checkbox. | 1025 Replace with the checkbox. |
949 @item %% | 1026 @item %% |
950 Insert a literal @samp{%}. | 1027 Insert a literal @samp{%}. |
951 @end table | 1028 @end table |
952 | 1029 |
1030 @vindex greedy@r{ keyword} | |
953 @item :greedy | 1031 @item :greedy |
954 Usually a checklist will only match if the items are in the exact | 1032 Usually a checklist will only match if the items are in the exact |
955 sequence given in the specification. By setting @code{:greedy} to | 1033 sequence given in the specification. By setting @code{:greedy} to |
956 non-nil, it will allow the items to come in any sequence. However, if | 1034 non-nil, it will allow the items to come in any sequence. However, if |
957 you extract the value they will be in the sequence given in the | 1035 you extract the value they will be in the sequence given in the |
958 checklist. I.e. the original sequence is forgotten. | 1036 checklist. I.e. the original sequence is forgotten. |
959 | 1037 |
1038 @vindex button-args@r{ keyword} | |
960 @item button-args | 1039 @item button-args |
961 A list of keywords to pass to the checkboxes. Useful for setting | 1040 A list of keywords to pass to the checkboxes. Useful for setting |
962 e.g. the @samp{:help-echo} for each checkbox. | 1041 e.g. the @samp{:help-echo} for each checkbox. |
963 | 1042 |
1043 @vindex buttons@r{ keyword} | |
964 @item :buttons | 1044 @item :buttons |
965 The widgets representing the checkboxes. | 1045 The widgets representing the checkboxes. |
966 | 1046 |
1047 @vindex children@r{ keyword} | |
967 @item :children | 1048 @item :children |
968 The widgets representing each type. | 1049 The widgets representing each type. |
969 | 1050 |
1051 @vindex args@r{ keyword} | |
970 @item :args | 1052 @item :args |
971 The list of types. | 1053 The list of types. |
972 @end table | 1054 @end table |
973 | 1055 |
974 @node editable-list, group, checklist, Basic Types | 1056 @node editable-list, group, checklist, Basic Types |
975 @comment node-name, next, previous, up | 1057 @comment node-name, next, previous, up |
976 @subsection The @code{editable-list} Widget | 1058 @subsection The @code{editable-list} Widget |
1059 @findex editable-list@r{ widget} | |
977 | 1060 |
978 Syntax: | 1061 Syntax: |
979 | 1062 |
980 @example | 1063 @example |
981 TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE) | 1064 TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE) |
982 @end example | 1065 @end example |
983 | 1066 |
984 The value is a list, where each member represents one widget of type | 1067 The value is a list, where each member represents one widget of type |
985 @var{type}. | 1068 @var{type}. |
986 | 1069 |
987 The following extra properties are recognized. | 1070 The following extra properties are recognized: |
988 | 1071 |
989 @table @code | 1072 @table @code |
1073 @vindex entry-format@r{ keyword} | |
990 @item :entry-format | 1074 @item :entry-format |
991 This string will be inserted for each entry in the list. | 1075 This string will be inserted for each entry in the list. |
992 The following @samp{%} escapes are available: | 1076 The following @samp{%} escapes are available: |
993 @table @samp | 1077 @table @samp |
994 @item %v | 1078 @item %v |
1000 Insert the @b{[DEL]} button. | 1084 Insert the @b{[DEL]} button. |
1001 @item %% | 1085 @item %% |
1002 Insert a literal @samp{%}. | 1086 Insert a literal @samp{%}. |
1003 @end table | 1087 @end table |
1004 | 1088 |
1089 @vindex insert-button-args@r{ keyword} | |
1005 @item :insert-button-args | 1090 @item :insert-button-args |
1006 A list of keyword arguments to pass to the insert buttons. | 1091 A list of keyword arguments to pass to the insert buttons. |
1007 | 1092 |
1093 @vindex delete-button-args@r{ keyword} | |
1008 @item :delete-button-args | 1094 @item :delete-button-args |
1009 A list of keyword arguments to pass to the delete buttons. | 1095 A list of keyword arguments to pass to the delete buttons. |
1010 | 1096 |
1097 @vindex append-button-args@r{ keyword} | |
1011 @item :append-button-args | 1098 @item :append-button-args |
1012 A list of keyword arguments to pass to the trailing insert button. | 1099 A list of keyword arguments to pass to the trailing insert button. |
1013 | 1100 |
1014 | 1101 @vindex buttons@r{ keyword} |
1015 @item :buttons | 1102 @item :buttons |
1016 The widgets representing the insert and delete buttons. | 1103 The widgets representing the insert and delete buttons. |
1017 | 1104 |
1105 @vindex children@r{ keyword} | |
1018 @item :children | 1106 @item :children |
1019 The widgets representing the elements of the list. | 1107 The widgets representing the elements of the list. |
1020 | 1108 |
1109 @vindex args@r{ keyword} | |
1021 @item :args | 1110 @item :args |
1022 List whose car is the type of the list elements. | 1111 List whose @code{car} is the type of the list elements. |
1023 | |
1024 @end table | 1112 @end table |
1025 | 1113 |
1026 @node group, , editable-list, Basic Types | 1114 @node group, , editable-list, Basic Types |
1027 @comment node-name, next, previous, up | 1115 @comment node-name, next, previous, up |
1028 @subsection The @code{group} Widget | 1116 @subsection The @code{group} Widget |
1029 | 1117 @findex group@r{ widget} |
1030 This widget simply group other widget together. | 1118 |
1119 This widget simply group other widgets together. | |
1031 | 1120 |
1032 Syntax: | 1121 Syntax: |
1033 | 1122 |
1034 @example | 1123 @example |
1035 TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...) | 1124 TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...) |
1038 The value is a list, with one member for each @var{type}. | 1127 The value is a list, with one member for each @var{type}. |
1039 | 1128 |
1040 @node Sexp Types, Widget Properties, Basic Types, Top | 1129 @node Sexp Types, Widget Properties, Basic Types, Top |
1041 @comment | 1130 @comment |
1042 @section Sexp Types | 1131 @section Sexp Types |
1043 | 1132 @cindex sexp types |
1044 A number of widgets for editing s-expressions (lisp types) are also | 1133 |
1045 available. These basically fall in the following categories. | 1134 A number of widgets for editing @dfn{s-expressions} (lisp types), sexp |
1135 for short, are also available. These basically fall in several | |
1136 categories described in this section. | |
1046 | 1137 |
1047 @menu | 1138 @menu |
1048 * constants:: | 1139 * constants:: |
1049 * generic:: | 1140 * generic:: |
1050 * atoms:: | 1141 * atoms:: |
1051 * composite:: | 1142 * composite:: |
1052 @end menu | 1143 @end menu |
1053 | 1144 |
1054 @node constants, generic, Sexp Types, Sexp Types | 1145 @node constants, generic, Sexp Types, Sexp Types |
1055 @comment node-name, next, previous, up | 1146 @comment node-name, next, previous, up |
1056 @subsection The Constant Widgets. | 1147 @subsection The Constant Widgets |
1148 @cindex constant widgets | |
1057 | 1149 |
1058 The @code{const} widget can contain any lisp expression, but the user is | 1150 The @code{const} widget can contain any lisp expression, but the user is |
1059 prohibited from editing edit it, which is mainly useful as a component | 1151 prohibited from editing it, which is mainly useful as a component of one |
1060 of one of the composite widgets. | 1152 of the composite widgets. |
1061 | 1153 |
1062 The syntax for the @code{const} widget is | 1154 The syntax for the @code{const} widget is: |
1063 | 1155 |
1064 @example | 1156 @example |
1065 TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ]) | 1157 TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ]) |
1066 @end example | 1158 @end example |
1067 | 1159 |
1087 An immutable symbol that is bound as a function. | 1179 An immutable symbol that is bound as a function. |
1088 @end deffn | 1180 @end deffn |
1089 | 1181 |
1090 @node generic, atoms, constants, Sexp Types | 1182 @node generic, atoms, constants, Sexp Types |
1091 @comment node-name, next, previous, up | 1183 @comment node-name, next, previous, up |
1092 @subsection Generic Sexp Widget. | 1184 @subsection Generic Sexp Widget |
1185 @cindex generic sexp widget | |
1093 | 1186 |
1094 The @code{sexp} widget can contain any lisp expression, and allows the | 1187 The @code{sexp} widget can contain any lisp expression, and allows the |
1095 user to edit it inline in the buffer. | 1188 user to edit it inline in the buffer. |
1096 | 1189 |
1097 The syntax for the @code{sexp} widget is | 1190 The syntax for the @code{sexp} widget is: |
1098 | 1191 |
1099 @example | 1192 @example |
1100 TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ]) | 1193 TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ]) |
1101 @end example | 1194 @end example |
1102 | 1195 |
1103 @deffn Widget sexp | 1196 @deffn Widget sexp |
1104 This will allow you to edit any valid s-expression in an editable buffer | 1197 This will allow you to edit any valid s-expression in an editable buffer |
1105 field. | 1198 field. |
1106 | 1199 |
1107 The @code{sexp} widget takes the same keyword arguments as the | 1200 The @code{sexp} widget takes the same keyword arguments as the |
1108 @code{editable-field} widget. | 1201 @code{editable-field} widget. @xref{editable-field}. |
1109 @end deffn | 1202 @end deffn |
1110 | 1203 |
1111 @node atoms, composite, generic, Sexp Types | 1204 @node atoms, composite, generic, Sexp Types |
1112 @comment node-name, next, previous, up | 1205 @comment node-name, next, previous, up |
1113 @subsection Atomic Sexp Widgets. | 1206 @subsection Atomic Sexp Widgets |
1114 | 1207 @cindex atomic sexp widget |
1115 The atoms are s-expressions that does not consist of other | 1208 |
1116 s-expressions. A string is an atom, while a list is a composite type. | 1209 The atoms are s-expressions that do not consist of other s-expressions. |
1117 You can edit the value of an atom with the following widgets. | 1210 For example, a string, a file name, or a symbol are atoms, while a list |
1118 | 1211 is a composite type. You can edit the value of an atom with the |
1119 The syntax for all the atoms are | 1212 following widgets. |
1213 | |
1214 The syntax for all the atoms are: | |
1120 | 1215 |
1121 @example | 1216 @example |
1122 TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ]) | 1217 TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ]) |
1123 @end example | 1218 @end example |
1124 | 1219 |
1125 The @var{value}, if present, is used to initialize the @code{:value} | 1220 The @var{value}, if present, is used to initialize the @code{:value} |
1126 property and must be an expression of the same type as the widget. | 1221 property and must be an expression of the same type as the widget. |
1127 I.e. the string widget can only be initialized with a string. | 1222 That is, the string widget can only be initialized with a string. |
1128 | 1223 |
1129 All the atom widgets take the same keyword arguments as the | 1224 All the atom widgets take the same keyword arguments as the |
1130 @code{editable-field} widget. | 1225 @code{editable-field} widget. @xref{editable-field}. |
1131 | 1226 |
1132 @deffn Widget string | 1227 @deffn Widget string |
1133 Allows you to edit a string in an editable field. | 1228 Allows you to edit a string in an editable field. |
1134 @end deffn | 1229 @end deffn |
1135 | 1230 |
1146 the tag button, you can edit the file name in the mini-buffer with | 1241 the tag button, you can edit the file name in the mini-buffer with |
1147 completion. | 1242 completion. |
1148 | 1243 |
1149 Keywords: | 1244 Keywords: |
1150 @table @code | 1245 @table @code |
1246 @vindex must-match@r{ keyword} | |
1151 @item :must-match | 1247 @item :must-match |
1152 If this is set to non-nil, only existing file names will be allowed in | 1248 If this is set to non-nil, only existing file names will be allowed in |
1153 the minibuffer. | 1249 the minibuffer. |
1154 @end table | 1250 @end table |
1155 @end deffn | 1251 @end deffn |
1185 @end deffn | 1281 @end deffn |
1186 | 1282 |
1187 | 1283 |
1188 @node composite, , atoms, Sexp Types | 1284 @node composite, , atoms, Sexp Types |
1189 @comment node-name, next, previous, up | 1285 @comment node-name, next, previous, up |
1190 @subsection Composite Sexp Widgets. | 1286 @subsection Composite Sexp Widgets |
1191 | 1287 @cindex composite sexp widgets |
1192 The syntax for the composite are | 1288 |
1289 The syntax for the composite widget is: | |
1193 | 1290 |
1194 @example | 1291 @example |
1195 TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...) | 1292 TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...) |
1196 @end example | 1293 @end example |
1197 | 1294 |
1198 Where each @var{component} must be a widget type. Each component widget | 1295 @noindent |
1199 will be displayed in the buffer, and be editable to the user. | 1296 where each @var{component} must be a widget type. Each component widget |
1297 will be displayed in the buffer, and will be editable by the user. | |
1200 | 1298 |
1201 @deffn Widget cons | 1299 @deffn Widget cons |
1202 The value of a @code{cons} widget is a cons-cell where the car is the | 1300 The value of a @code{cons} widget is a cons-cell where the @code{car} is |
1203 value of the first component and the cdr is the value of the second | 1301 the value of the first component and the @code{cdr} is the value of the |
1204 component. There must be exactly two components. | 1302 second component. There must be exactly two components. |
1205 @end deffn | 1303 @end deffn |
1206 | 1304 |
1207 @deffn Widget list | 1305 @deffn Widget list |
1208 The value of a @code{list} widget is a list containing the value of | 1306 The value of a @code{list} widget is a list containing the value of |
1209 each of its component. | 1307 each of its component. |
1214 each of its component. | 1312 each of its component. |
1215 @end deffn | 1313 @end deffn |
1216 | 1314 |
1217 The above suffice for specifying fixed size lists and vectors. To get | 1315 The above suffice for specifying fixed size lists and vectors. To get |
1218 variable length lists and vectors, you can use a @code{choice}, | 1316 variable length lists and vectors, you can use a @code{choice}, |
1219 @code{set} or @code{repeat} widgets together with the @code{:inline} | 1317 @code{set}, or @code{repeat} widgets together with the @code{:inline} |
1220 keywords. If any component of a composite widget has the @code{:inline} | 1318 keywords. If any component of a composite widget has the @code{:inline} |
1221 keyword set, its value must be a list which will then be spliced into | 1319 keyword set, its value must be a list which will then be spliced into |
1222 the composite. For example, to specify a list whose first element must | 1320 the composite. For example, to specify a list whose first element must |
1223 be a file name, and whose remaining arguments should either by the | 1321 be a file name, and whose remaining arguments should either by the |
1224 symbol @code{t} or two files, you can use the following widget | 1322 symbol @code{t} or two files, you can use the following widget |
1231 :value ("foo" "bar") | 1329 :value ("foo" "bar") |
1232 string string))) | 1330 string string))) |
1233 @end example | 1331 @end example |
1234 | 1332 |
1235 The value of a widget of this type will either have the form | 1333 The value of a widget of this type will either have the form |
1236 @samp{(file t)} or @code{(file string string)}. | 1334 @code{(file t)} or @code{(file string string)}. |
1237 | 1335 |
1238 This concept of inline is probably hard to understand. It was certainly | 1336 This concept of inline is probably hard to understand. It was certainly |
1239 hard to implement so instead of confusing you more by trying to explain | 1337 hard to implement, so instead of confusing you more by trying to explain |
1240 it here, I'll just suggest you meditate over it for a while. | 1338 it here, I'll just suggest you meditate over it for a while. |
1241 | 1339 |
1242 @deffn Widget choice | 1340 @deffn Widget choice |
1243 Allows you to edit a sexp which may have one of a fixed set of types. | 1341 Allows you to edit a sexp which may have one of a fixed set of types. |
1244 It is currently implemented with the @code{choice-menu} basic widget, | 1342 It is currently implemented with the @code{choice-menu} basic widget, |
1245 and has a similar syntax. | 1343 and has a similar syntax. |
1246 @end deffn | 1344 @end deffn |
1247 | 1345 |
1248 @deffn Widget set | 1346 @deffn Widget set |
1249 Allows you to specify a type which must be a list whose elements all | 1347 Allows you to specify a type which must be a list whose elements all |
1250 belong to given set. The elements of the list is not significant. This | 1348 belong to given set. The elements of the list are not significant. |
1251 is implemented on top of the @code{checklist} basic widget, and has a | 1349 This is implemented on top of the @code{checklist} basic widget, and has |
1252 similar syntax. | 1350 a similar syntax. |
1253 @end deffn | 1351 @end deffn |
1254 | 1352 |
1255 @deffn Widget repeat | 1353 @deffn Widget repeat |
1256 Allows you to specify a variable length list whose members are all of | 1354 Allows you to specify a variable length list whose members are all of |
1257 the same type. Implemented on top of the `editable-list' basic widget, | 1355 the same type. Implemented on top of the @code{editable-list} basic |
1258 and has a similar syntax. | 1356 widget, and has a similar syntax. |
1259 @end deffn | 1357 @end deffn |
1260 | 1358 |
1261 @node Widget Properties, Defining New Widgets, Sexp Types, Top | 1359 @node Widget Properties, Defining New Widgets, Sexp Types, Top |
1262 @comment node-name, next, previous, up | 1360 @comment node-name, next, previous, up |
1263 @section Properties | 1361 @section Properties |
1362 @cindex properties of widgets | |
1363 @cindex widget properties | |
1264 | 1364 |
1265 You can examine or set the value of a widget by using the widget object | 1365 You can examine or set the value of a widget by using the widget object |
1266 that was returned by @code{widget-create}. | 1366 that was returned by @code{widget-create}. |
1267 | 1367 |
1268 @defun widget-value widget | 1368 @defun widget-value widget |
1307 | 1407 |
1308 @defun widget-type widget | 1408 @defun widget-type widget |
1309 Return the name of @var{widget}, a symbol. | 1409 Return the name of @var{widget}, a symbol. |
1310 @end defun | 1410 @end defun |
1311 | 1411 |
1412 @cindex active widget | |
1413 @cindex inactive widget | |
1414 @cindex activate a widget | |
1415 @cindex deactivate a widget | |
1312 Widgets can be in two states: active, which means they are modifiable by | 1416 Widgets can be in two states: active, which means they are modifiable by |
1313 the user, or inactive, which means they cannot be modified by the user. | 1417 the user, or inactive, which means they cannot be modified by the user. |
1314 You can query or set the state with the following code: | 1418 You can query or set the state with the following code: |
1315 | 1419 |
1316 @lisp | 1420 @lisp |
1347 | 1451 |
1348 | 1452 |
1349 @node Defining New Widgets, Widget Browser, Widget Properties, Top | 1453 @node Defining New Widgets, Widget Browser, Widget Properties, Top |
1350 @comment node-name, next, previous, up | 1454 @comment node-name, next, previous, up |
1351 @section Defining New Widgets | 1455 @section Defining New Widgets |
1352 | 1456 @cindex new widgets |
1353 You can define specialized widgets with @code{define-widget}. It allows | 1457 @cindex defining new widgets |
1458 | |
1459 You can define specialized widgets with @code{widget-define}. It allows | |
1354 you to create a shorthand for more complex widgets, including specifying | 1460 you to create a shorthand for more complex widgets, including specifying |
1355 component widgets and new default values for the keyword | 1461 component widgets and new default values for the keyword |
1356 arguments. | 1462 arguments. |
1357 | 1463 |
1358 @defun widget-define name class doc &rest args | 1464 @defun widget-define name class doc &rest args |
1382 | 1488 |
1383 Using @code{widget-define} just stores the definition of the widget type | 1489 Using @code{widget-define} just stores the definition of the widget type |
1384 in the @code{widget-type} property of @var{name}, which is what | 1490 in the @code{widget-type} property of @var{name}, which is what |
1385 @code{widget-create} uses. | 1491 @code{widget-create} uses. |
1386 | 1492 |
1387 If you just want to specify defaults for keywords with no complex | 1493 If you only want to specify defaults for keywords with no complex |
1388 conversions, you can use @code{identity} as your conversion function. | 1494 conversions, you can use @code{identity} as your conversion function. |
1389 | 1495 |
1390 The following additional keyword arguments are useful when defining new | 1496 The following additional keyword arguments are useful when defining new |
1391 widgets: | 1497 widgets: |
1392 @table @code | 1498 @table @code |
1499 @vindex convert-widget@r{ keyword} | |
1393 @item :convert-widget | 1500 @item :convert-widget |
1394 Function to convert a widget type before creating a widget of that | 1501 Function to convert a widget type before creating a widget of that |
1395 type. It takes a widget type as an argument, and returns the converted | 1502 type. It takes a widget type as an argument, and returns the converted |
1396 widget type. When a widget is created, this function is called for the | 1503 widget type. When a widget is created, this function is called for the |
1397 widget type and all the widget's parent types, most derived first. | 1504 widget type and all the widget's parent types, most derived first. |
1404 | 1511 |
1405 @defun widget-value-convert-widget widget | 1512 @defun widget-value-convert-widget widget |
1406 Initialize @code{:value} from @code{:args} in @var{widget}. | 1513 Initialize @code{:value} from @code{:args} in @var{widget}. |
1407 @end defun | 1514 @end defun |
1408 | 1515 |
1516 @vindex value-to-internal@r{ keyword} | |
1409 @item :value-to-internal | 1517 @item :value-to-internal |
1410 Function to convert the value to the internal format. The function | 1518 Function to convert the value to the internal format. The function |
1411 takes two arguments, a widget and an external value, and returns the | 1519 takes two arguments, a widget and an external value, and returns the |
1412 internal value. The function is called on the present @code{:value} | 1520 internal value. The function is called on the present @code{:value} |
1413 when the widget is created, and on any value set later with | 1521 when the widget is created, and on any value set later with |
1414 @code{widget-value-set}. | 1522 @code{widget-value-set}. |
1415 | 1523 |
1524 @vindex value-to-external@r{ keyword} | |
1416 @item :value-to-external | 1525 @item :value-to-external |
1417 Function to convert the value to the external format. The function | 1526 Function to convert the value to the external format. The function |
1418 takes two arguments, a widget and an internal value, and returns the | 1527 takes two arguments, a widget and an internal value, and returns the |
1419 internal value. The function is called on the present @code{:value} | 1528 external value. The function is called on the present @code{:value} |
1420 when the widget is created, and on any value set later with | 1529 when the widget is created, and on any value set later with |
1421 @code{widget-value-set}. | 1530 @code{widget-value-set}. |
1422 | 1531 |
1532 @vindex create@r{ keyword} | |
1423 @item :create | 1533 @item :create |
1424 Function to create a widget from scratch. The function takes one | 1534 Function to create a widget from scratch. The function takes one |
1425 argument, a widget type, and creates a widget of that type, inserts it | 1535 argument, a widget type, and creates a widget of that type, inserts it |
1426 in the buffer, and returns a widget object. | 1536 in the buffer, and returns a widget object. |
1427 | 1537 |
1538 @vindex delete@r{ keyword} | |
1428 @item :delete | 1539 @item :delete |
1429 Function to delete a widget. The function takes one argument, a widget, | 1540 Function to delete a widget. The function takes one argument, a widget, |
1430 and should remove all traces of the widget from the buffer. | 1541 and should remove all traces of the widget from the buffer. |
1431 | 1542 |
1543 @vindex value-create@r{ keyword} | |
1432 @item :value-create | 1544 @item :value-create |
1433 Function to expand the @samp{%v} escape in the format string. It will | 1545 Function to expand the @samp{%v} escape in the format string. It will |
1434 be called with the widget as its argument and should insert a | 1546 be called with the widget as its argument and should insert a |
1435 representation of the widget's value in the buffer. | 1547 representation of the widget's value in the buffer. |
1436 | 1548 |
1549 @vindex value-delete@r{ keyword} | |
1437 @item :value-delete | 1550 @item :value-delete |
1438 Should remove the representation of the widget's value from the buffer. | 1551 Should remove the representation of the widget's value from the buffer. |
1439 It will be called with the widget as its argument. It doesn't have to | 1552 It will be called with the widget as its argument. It doesn't have to |
1440 remove the text, but it should release markers and delete nested widgets | 1553 remove the text, but it should release markers and delete nested widgets |
1441 if such have been used. | 1554 if such have been used. |
1444 | 1557 |
1445 @defun widget-children-value-delete widget | 1558 @defun widget-children-value-delete widget |
1446 Delete all @code{:children} and @code{:buttons} in @var{widget}. | 1559 Delete all @code{:children} and @code{:buttons} in @var{widget}. |
1447 @end defun | 1560 @end defun |
1448 | 1561 |
1562 @vindex value-get@r{ keyword} | |
1449 @item :value-get | 1563 @item :value-get |
1450 Function to extract the value of a widget, as it is displayed in the | 1564 Function to extract the value of a widget, as it is displayed in the |
1451 buffer. | 1565 buffer. |
1452 | 1566 |
1453 The following predefined function can be used here: | 1567 The following predefined function can be used here: |
1454 | 1568 |
1455 @defun widget-value-value-get widget | 1569 @defun widget-value-value-get widget |
1456 Return the @code{:value} property of @var{widget}. | 1570 Return the @code{:value} property of @var{widget}. |
1457 @end defun | 1571 @end defun |
1458 | 1572 |
1573 @vindex format-handler@r{ keyword} | |
1459 @item :format-handler | 1574 @item :format-handler |
1460 Function to handle unknown @samp{%} escapes in the format string. It | 1575 Function to handle unknown @samp{%} escapes in the format string. It |
1461 will be called with the widget and the escape character as arguments. | 1576 will be called with the widget and the character that follows the |
1462 You can set this to allow your widget to handle non-standard escapes. | 1577 @samp{%} as arguments. You can set this to allow your widget to handle |
1463 | 1578 non-standard escapes. |
1579 | |
1580 @findex widget-default-format-handler | |
1464 You should end up calling @code{widget-default-format-handler} to handle | 1581 You should end up calling @code{widget-default-format-handler} to handle |
1465 unknown escape sequences, which will handle the @samp{%h} and any future | 1582 unknown escape sequences, which will handle the @samp{%h} and any future |
1466 escape sequences, as well as give an error for unknown escapes. | 1583 escape sequences, as well as give an error for unknown escapes. |
1467 | 1584 |
1585 @vindex action@r{ keyword} | |
1468 @item :action | 1586 @item :action |
1469 Function to handle user initiated events. By default, @code{:notify} | 1587 Function to handle user initiated events. By default, @code{:notify} |
1470 the parent. | 1588 the parent. |
1471 | 1589 |
1472 The following predefined function can be used here: | 1590 The following predefined function can be used here: |
1474 @defun widget-parent-action widget &optional event | 1592 @defun widget-parent-action widget &optional event |
1475 Tell @code{:parent} of @var{widget} to handle the @code{:action}. | 1593 Tell @code{:parent} of @var{widget} to handle the @code{:action}. |
1476 Optional @var{event} is the event that triggered the action. | 1594 Optional @var{event} is the event that triggered the action. |
1477 @end defun | 1595 @end defun |
1478 | 1596 |
1597 @vindex prompt-value@r{ keyword} | |
1479 @item :prompt-value | 1598 @item :prompt-value |
1480 Function to prompt for a value in the minibuffer. The function should | 1599 Function to prompt for a value in the minibuffer. The function should |
1481 take four arguments, @var{widget}, @var{prompt}, @var{value}, and | 1600 take four arguments, @var{widget}, @var{prompt}, @var{value}, and |
1482 @var{unbound} and should return a value for widget entered by the user. | 1601 @var{unbound} and should return a value for widget entered by the user. |
1483 @var{prompt} is the prompt to use. @var{value} is the default value to | 1602 @var{prompt} is the prompt to use. @var{value} is the default value to |
1497 @end deffn | 1616 @end deffn |
1498 | 1617 |
1499 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top | 1618 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top |
1500 @comment node-name, next, previous, up | 1619 @comment node-name, next, previous, up |
1501 @section Widget Browser | 1620 @section Widget Browser |
1621 @cindex widget browser | |
1502 | 1622 |
1503 There is a separate package to browse widgets. This is intended to help | 1623 There is a separate package to browse widgets. This is intended to help |
1504 programmers who want to examine the content of a widget. The browser | 1624 programmers who want to examine the content of a widget. The browser |
1505 shows the value of each keyword, but uses links for certain keywords | 1625 shows the value of each keyword, but uses links for certain keywords |
1506 such as `:parent', which avoids printing cyclic structures. | 1626 such as @samp{:parent}, which avoids printing cyclic structures. |
1507 | 1627 |
1508 @deffn Command widget-browse WIDGET | 1628 @deffn Command widget-browse WIDGET |
1509 Create a widget browser for WIDGET. | 1629 Create a widget browser for WIDGET. |
1510 When called interactively, prompt for WIDGET. | 1630 When called interactively, prompt for WIDGET. |
1511 @end deffn | 1631 @end deffn |
1521 @end deffn | 1641 @end deffn |
1522 | 1642 |
1523 @node Widget Minor Mode, Utilities, Widget Browser, Top | 1643 @node Widget Minor Mode, Utilities, Widget Browser, Top |
1524 @comment node-name, next, previous, up | 1644 @comment node-name, next, previous, up |
1525 @section Widget Minor Mode | 1645 @section Widget Minor Mode |
1646 @cindex widget minor mode | |
1526 | 1647 |
1527 There is a minor mode for manipulating widgets in major modes that | 1648 There is a minor mode for manipulating widgets in major modes that |
1528 doesn't provide any support for widgets themselves. This is mostly | 1649 don't provide any support for widgets themselves. This is mostly |
1529 intended to be useful for programmers doing experiments. | 1650 intended to be useful for programmers doing experiments. |
1530 | 1651 |
1531 @deffn Command widget-minor-mode | 1652 @deffn Command widget-minor-mode |
1532 Toggle minor mode for traversing widgets. | 1653 Toggle minor mode for traversing widgets. |
1533 With arg, turn widget mode on if and only if arg is positive. | 1654 With arg, turn widget mode on if and only if arg is positive. |
1538 @end defvar | 1659 @end defvar |
1539 | 1660 |
1540 @node Utilities, Widget Wishlist, Widget Minor Mode, Top | 1661 @node Utilities, Widget Wishlist, Widget Minor Mode, Top |
1541 @comment node-name, next, previous, up | 1662 @comment node-name, next, previous, up |
1542 @section Utilities. | 1663 @section Utilities. |
1664 @cindex utility functions for widgets | |
1543 | 1665 |
1544 @defun widget-prompt-value widget prompt [ value unbound ] | 1666 @defun widget-prompt-value widget prompt [ value unbound ] |
1545 Prompt for a value matching @var{widget}, using @var{prompt}. | 1667 Prompt for a value matching @var{widget}, using @var{prompt}. |
1546 The current value is assumed to be @var{value}, unless @var{unbound} is | 1668 The current value is assumed to be @var{value}, unless @var{unbound} is |
1547 non-nil.@refill | 1669 non-nil.@refill |
1548 @end defun | 1670 @end defun |
1549 | 1671 |
1550 @defun widget-get-sibling widget | 1672 @defun widget-get-sibling widget |
1551 Get the item @var{widget} is assumed to toggle. | 1673 Get the item which @var{widget} is assumed to toggle. |
1552 This is only meaningful for radio buttons or checkboxes in a list. | 1674 This is only meaningful for radio buttons or checkboxes in a list. |
1553 @end defun | 1675 @end defun |
1554 | 1676 |
1555 @node Widget Wishlist, , Utilities, Top | 1677 @node Widget Wishlist, Index, Utilities, Top |
1556 @comment node-name, next, previous, up | 1678 @comment node-name, next, previous, up |
1557 @section Wishlist | 1679 @section Wishlist |
1680 @cindex todo | |
1558 | 1681 |
1559 @itemize @bullet | 1682 @itemize @bullet |
1560 @item | 1683 @item |
1561 It should be possible to add or remove items from a list with @kbd{C-k} | 1684 It should be possible to add or remove items from a list with @kbd{C-k} |
1562 and @kbd{C-o} (suggested by @sc{rms}). | 1685 and @kbd{C-o} (suggested by @sc{rms}). |
1563 | 1686 |
1564 @item | 1687 @item |
1565 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single | 1688 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single |
1566 dash (@samp{-}). The dash should be a button that, when invoked, ask | 1689 dash (@samp{-}). The dash should be a button that, when invoked, asks |
1567 whether you want to add or delete an item (@sc{rms} wanted to git rid of | 1690 whether you want to add or delete an item (@sc{rms} wanted to git rid of |
1568 the ugly buttons, the dash is my idea). | 1691 the ugly buttons, the dash is my idea). |
1569 | 1692 |
1570 @item | 1693 @item |
1571 The @code{menu-choice} tag should be prettier, something like the abbreviated | 1694 The @code{menu-choice} tag should be prettier, something like the abbreviated |
1605 | 1728 |
1606 @item | 1729 @item |
1607 @kbd{C-h} in @code{widget-prompt-value} should give type specific help. | 1730 @kbd{C-h} in @code{widget-prompt-value} should give type specific help. |
1608 | 1731 |
1609 @item | 1732 @item |
1610 A mailto widget. | 1733 Add a @code{mailto} widget. |
1611 | |
1612 @end itemize | 1734 @end itemize |
1735 | |
1736 @node Index, , Widget Wishlist, Top | |
1737 @comment node-name, next, previous, up | |
1738 @unnumbered Index | |
1739 | |
1740 This is an alphabetical listing of all concepts, functions, commands, | |
1741 variables, and widgets described in this manual. | |
1742 @printindex cp | |
1613 | 1743 |
1614 @setchapternewpage odd | 1744 @setchapternewpage odd |
1615 @contents | 1745 @contents |
1616 @bye | 1746 @bye |