3 |
@c %**start of header |
@c %**start of header |
4 |
@setfilename ../info/widget |
@setfilename ../info/widget |
5 |
@settitle The Emacs Widget Library |
@settitle The Emacs Widget Library |
6 |
@ifnottex |
@syncodeindex fn cp |
7 |
Copyright @copyright{} 2000 Free Software Foundation, Inc. |
@syncodeindex vr cp |
8 |
|
@syncodeindex ky cp |
9 |
|
@afourpaper |
10 |
|
@c %**end of header |
11 |
|
|
12 |
|
@copying |
13 |
|
Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc. |
14 |
|
|
15 |
|
@quotation |
16 |
Permission is granted to copy, distribute and/or modify this document |
Permission is granted to copy, distribute and/or modify this document |
17 |
under the terms of the GNU Free Documentation License, Version 1.1 or |
under the terms of the GNU Free Documentation License, Version 1.1 or |
18 |
any later version published by the Free Software Foundation; with the |
any later version published by the Free Software Foundation; with the |
30 |
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
31 |
this GNU Manual, like GNU software. Copies published by the Free |
this GNU Manual, like GNU software. Copies published by the Free |
32 |
Software Foundation raise funds for GNU development.'' |
Software Foundation raise funds for GNU development.'' |
33 |
@end ifnottex |
@end quotation |
34 |
|
@end copying |
|
@iftex |
|
|
@afourpaper |
|
|
@headings double |
|
|
@end iftex |
|
|
@c %**end of header |
|
|
|
|
|
@syncodeindex fn cp |
|
|
@syncodeindex vr cp |
|
|
@syncodeindex ky cp |
|
35 |
|
|
36 |
@dircategory Emacs |
@dircategory Emacs |
37 |
@direntry |
@direntry |
44 |
@top The Emacs Widget Library |
@top The Emacs Widget Library |
45 |
|
|
46 |
@menu |
@menu |
47 |
* Introduction:: |
* Introduction:: |
48 |
* User Interface:: |
* User Interface:: |
49 |
* Programming Example:: |
* Programming Example:: |
50 |
* Setting Up the Buffer:: |
* Setting Up the Buffer:: |
51 |
* Basic Types:: |
* Basic Types:: |
52 |
* Sexp Types:: |
* Sexp Types:: |
53 |
* Widget Properties:: |
* Widget Properties:: |
54 |
* Defining New Widgets:: |
* Defining New Widgets:: |
55 |
* Widget Browser:: |
* Widget Browser:: |
56 |
* Widget Minor Mode:: |
* Widget Minor Mode:: |
57 |
* Utilities:: |
* Utilities:: |
58 |
* Widget Wishlist:: |
* Widget Wishlist:: |
59 |
* Index:: |
* Index:: |
60 |
@end menu |
@end menu |
61 |
|
|
78 |
@item link |
@item link |
79 |
Areas of text with an associated action. Intended for hypertext links |
Areas of text with an associated action. Intended for hypertext links |
80 |
embedded in text. |
embedded in text. |
81 |
@item push-button |
@item push-button |
82 |
Like link, but intended for stand-alone buttons. |
Like link, but intended for stand-alone buttons. |
83 |
@item editable-field |
@item editable-field |
84 |
An editable text field. It can be either variable or fixed length. |
An editable text field. It can be either variable or fixed length. |
92 |
visible in the buffer. |
visible in the buffer. |
93 |
@item item |
@item item |
94 |
A simple constant widget intended to be used in the @code{menu-choice} and |
A simple constant widget intended to be used in the @code{menu-choice} and |
95 |
@code{radio-button-choice} widgets. |
@code{radio-button-choice} widgets. |
96 |
@item choice-item |
@item choice-item |
97 |
A button item only intended for use in choices. When invoked, the user |
A button item only intended for use in choices. When invoked, the user |
98 |
will be asked to select another option from the choice widget. |
will be asked to select another option from the choice widget. |
99 |
@item toggle |
@item toggle |
100 |
A simple @samp{on}/@samp{off} switch. |
A simple @samp{on}/@samp{off} switch. |
101 |
@item checkbox |
@item checkbox |
102 |
A checkbox (@samp{[ ]}/@samp{[X]}). |
A checkbox (@samp{[ ]}/@samp{[X]}). |
103 |
@item editable-list |
@item editable-list |
104 |
Create an editable list. The user can insert or delete items in the |
Create an editable list. The user can insert or delete items in the |
105 |
list. Each list item is itself a widget. |
list. Each list item is itself a widget. |
112 |
meaning. The user is not supposed to change or delete any of the text |
meaning. The user is not supposed to change or delete any of the text |
113 |
between the fields. Examples of forms in Emacs are the @file{forms} |
between the fields. Examples of forms in Emacs are the @file{forms} |
114 |
package (of course), the customize buffers, the mail and news compose |
package (of course), the customize buffers, the mail and news compose |
115 |
modes, and the @sc{html} form support in the @file{w3} browser. |
modes, and the @sc{html} form support in the @file{w3} browser. |
116 |
|
|
117 |
@cindex widget library, why use it |
@cindex widget library, why use it |
118 |
The advantages for a programmer of using the @code{widget} package to |
The advantages for a programmer of using the @code{widget} package to |
120 |
|
|
121 |
@enumerate |
@enumerate |
122 |
@item |
@item |
123 |
More complex fields than just editable text are supported. |
More complex fields than just editable text are supported. |
124 |
@item |
@item |
125 |
You can give the users immediate feedback if they enter invalid data in a |
You can give the users immediate feedback if they enter invalid data in a |
126 |
text field, and sometimes prevent entering invalid data. |
text field, and sometimes prevent entering invalid data. |
127 |
@item |
@item |
128 |
You can have fixed sized fields, thus allowing multiple fields to be |
You can have fixed sized fields, thus allowing multiple fields to be |
129 |
lined up in columns. |
lined up in columns. |
130 |
@item |
@item |
131 |
It is simple to query or set the value of a field. |
It is simple to query or set the value of a field. |
132 |
@item |
@item |
133 |
Editing happens in the buffer, not in the mini-buffer. |
Editing happens in the buffer, not in the mini-buffer. |
134 |
@item |
@item |
135 |
Packages using the library get a uniform look, making them easier for |
Packages using the library get a uniform look, making them easier for |
136 |
the user to learn. |
the user to learn. |
137 |
@item |
@item |
138 |
As support for embedded graphics improve, the widget library will be |
As support for embedded graphics improve, the widget library will be |
139 |
extended to use the GUI features. This means that your code using the |
extended to use the GUI features. This means that your code using the |
140 |
widget library will also use the new graphic features automatically. |
widget library will also use the new graphic features automatically. |
147 |
@table @file |
@table @file |
148 |
@item widget.el |
@item widget.el |
149 |
This will declare the user variables, define the function |
This will declare the user variables, define the function |
150 |
@code{define-widget}, and autoload the function @code{widget-create}. |
@code{define-widget}, and autoload the function @code{widget-create}. |
151 |
@item wid-edit.el |
@item wid-edit.el |
152 |
Everything else is here, there is no reason to load it explicitly, as |
Everything else is here, there is no reason to load it explicitly, as |
153 |
it will be autoloaded when needed. |
it will be autoloaded when needed. |
177 |
@b{[INS]} @b{[DEL]} @i{One} |
@b{[INS]} @b{[DEL]} @i{One} |
178 |
@b{[INS]} @b{[DEL]} @i{Eh, two?} |
@b{[INS]} @b{[DEL]} @i{Eh, two?} |
179 |
@b{[INS]} @b{[DEL]} @i{Five!} |
@b{[INS]} @b{[DEL]} @i{Five!} |
180 |
@b{[INS]} |
@b{[INS]} |
181 |
|
|
182 |
Select multiple: |
Select multiple: |
183 |
|
|
258 |
the example, @samp{@b{Choose}} is an option field tag. |
the example, @samp{@b{Choose}} is an option field tag. |
259 |
@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons |
@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons |
260 |
Activating these will insert or delete elements from an editable list. |
Activating these will insert or delete elements from an editable list. |
261 |
The list is created by the @code{editable-list} widget. |
The list is created by the @code{editable-list} widget. |
262 |
@cindex embedded buttons |
@cindex embedded buttons |
263 |
@item Embedded Buttons |
@item Embedded Buttons |
264 |
The @samp{@b{_other work_}} is an example of an embedded |
The @samp{@b{_other work_}} is an example of an embedded |
280 |
displayed as GUI buttons when possible. |
displayed as GUI buttons when possible. |
281 |
@end table |
@end table |
282 |
|
|
283 |
To make them easier to locate, buttons are emphasized in the buffer. |
To make them easier to locate, buttons are emphasized in the buffer. |
284 |
|
|
285 |
@deffn Face widget-button-face |
@deffn Face widget-button-face |
286 |
Face used for buttons. |
Face used for buttons. |
352 |
(widget-insert "\nSee also ") |
(widget-insert "\nSee also ") |
353 |
(widget-create 'link |
(widget-create 'link |
354 |
:notify (lambda (&rest ignore) |
:notify (lambda (&rest ignore) |
355 |
(widget-value-set widget-example-repeat |
(widget-value-set widget-example-repeat |
356 |
'("En" "To" "Tre")) |
'("En" "To" "Tre")) |
357 |
(widget-setup)) |
(widget-setup)) |
358 |
"other work") |
"other work") |
359 |
(widget-insert |
(widget-insert |
360 |
" for more information.\n\nNumbers: count to three below\n") |
" for more information.\n\nNumbers: count to three below\n") |
361 |
(setq widget-example-repeat |
(setq widget-example-repeat |
362 |
(widget-create 'editable-list |
(widget-create 'editable-list |
387 |
'(item "One") '(item "Another One.") '(item "A Final One.")) |
'(item "One") '(item "Another One.") '(item "A Final One.")) |
388 |
(widget-insert "\n") |
(widget-insert "\n") |
389 |
(widget-create 'push-button |
(widget-create 'push-button |
390 |
:notify (lambda (&rest ignore) |
:notify (lambda (&rest ignore) |
391 |
(if (= (length (widget-value widget-example-repeat)) |
(if (= (length (widget-value widget-example-repeat)) |
392 |
3) |
3) |
393 |
(message "Congratulation!") |
(message "Congratulation!") |
425 |
Delete @var{widget} and remove it from the buffer. |
Delete @var{widget} and remove it from the buffer. |
426 |
@end defun |
@end defun |
427 |
|
|
428 |
@defun widget-setup |
@defun widget-setup |
429 |
Set up a buffer to support widgets. |
Set up a buffer to support widgets. |
430 |
|
|
431 |
This should be called after creating all the widgets and before allowing |
This should be called after creating all the widgets and before allowing |
432 |
the user to edit them. |
the user to edit them. |
436 |
If you want to insert text outside the widgets in the form, the |
If you want to insert text outside the widgets in the form, the |
437 |
recommended way to do that is with @code{widget-insert}. |
recommended way to do that is with @code{widget-insert}. |
438 |
|
|
439 |
@defun widget-insert |
@defun widget-insert |
440 |
Insert the arguments, either strings or characters, at point. |
Insert the arguments, either strings or characters, at point. |
441 |
The inserted text will be read-only. |
The inserted text will be read-only. |
442 |
@end defun |
@end defun |
492 |
The text inside will be marked as a button. |
The text inside will be marked as a button. |
493 |
|
|
494 |
By default, the text will be shown in @code{widget-button-face}, and |
By default, the text will be shown in @code{widget-button-face}, and |
495 |
surrounded by brackets. |
surrounded by brackets. |
496 |
|
|
497 |
@defopt widget-button-prefix |
@defopt widget-button-prefix |
498 |
String to prefix buttons. |
String to prefix buttons. |
505 |
@item %@{ |
@item %@{ |
506 |
@itemx %@} |
@itemx %@} |
507 |
The text inside will be displayed with the face specified by |
The text inside will be displayed with the face specified by |
508 |
@code{:sample-face}. |
@code{:sample-face}. |
509 |
|
|
510 |
@item %v |
@item %v |
511 |
This will be replaced with the buffer representation of the widget's |
This will be replaced with the buffer representation of the widget's |
528 |
representation of the value if there is no tag. |
representation of the value if there is no tag. |
529 |
|
|
530 |
@item %% |
@item %% |
531 |
Insert a literal @samp{%}. |
Insert a literal @samp{%}. |
532 |
@end table |
@end table |
533 |
|
|
534 |
@vindex button-face@r{ keyword} |
@vindex button-face@r{ keyword} |
556 |
@vindex doc@r{ keyword} |
@vindex doc@r{ keyword} |
557 |
@item :doc |
@item :doc |
558 |
The string inserted by the @samp{%d} escape in the format |
The string inserted by the @samp{%d} escape in the format |
559 |
string. |
string. |
560 |
|
|
561 |
@vindex tag@r{ keyword} |
@vindex tag@r{ keyword} |
562 |
@item :tag |
@item :tag |
563 |
The string inserted by the @samp{%t} escape in the format |
The string inserted by the @samp{%t} escape in the format |
564 |
string. |
string. |
565 |
|
|
566 |
@vindex tag-glyph@r{ keyword} |
@vindex tag-glyph@r{ keyword} |
567 |
@item :tag-glyph |
@item :tag-glyph |
597 |
The function is called with two or three arguments. The first argument |
The function is called with two or three arguments. The first argument |
598 |
is the widget itself, the second argument is the widget that was |
is the widget itself, the second argument is the widget that was |
599 |
changed, and the third argument is the event leading to the change, if |
changed, and the third argument is the event leading to the change, if |
600 |
any. |
any. |
601 |
|
|
602 |
@vindex menu-tag@r{ keyword} |
@vindex menu-tag@r{ keyword} |
603 |
@item :menu-tag |
@item :menu-tag |
614 |
@vindex match@r{ keyword} |
@vindex match@r{ keyword} |
615 |
@item :match |
@item :match |
616 |
Should be a function called with two arguments, the widget and a value, |
Should be a function called with two arguments, the widget and a value, |
617 |
and returning non-nil if the widget can represent the specified value. |
and returning non-@code{nil} if the widget can represent the specified value. |
618 |
|
|
619 |
@vindex validate@r{ keyword} |
@vindex validate@r{ keyword} |
620 |
@item :validate |
@item :validate |
639 |
@item |
@item |
640 |
Widgets with tabbing order @code{-1} are ignored. |
Widgets with tabbing order @code{-1} are ignored. |
641 |
|
|
642 |
@item |
@item |
643 |
(Unimplemented) When on a widget with tabbing order @var{n}, go to the |
(Unimplemented) When on a widget with tabbing order @var{n}, go to the |
644 |
next widget in the buffer with tabbing order @var{n+1} or @code{nil}, |
next widget in the buffer with tabbing order @var{n+1} or @code{nil}, |
645 |
whichever comes first. |
whichever comes first. |
664 |
@end table |
@end table |
665 |
|
|
666 |
@deffn {User Option} widget-glyph-directory |
@deffn {User Option} widget-glyph-directory |
667 |
Directory where glyphs are found. |
Directory where glyphs are found. |
668 |
Widget will look here for a file with the same name as specified for the |
Widget will look here for a file with the same name as specified for the |
669 |
image, with either a @file{.xpm} (if supported) or @file{.xbm} extension. |
image, with either a @file{.xpm} (if supported) or @file{.xbm} extension. |
670 |
@end deffn |
@end deffn |
675 |
|
|
676 |
|
|
677 |
@menu |
@menu |
678 |
* link:: |
* link:: |
679 |
* url-link:: |
* url-link:: |
680 |
* info-link:: |
* info-link:: |
681 |
* push-button:: |
* push-button:: |
682 |
* editable-field:: |
* editable-field:: |
683 |
* text:: |
* text:: |
684 |
* menu-choice:: |
* menu-choice:: |
685 |
* radio-button-choice:: |
* radio-button-choice:: |
686 |
* item:: |
* item:: |
687 |
* choice-item:: |
* choice-item:: |
688 |
* toggle:: |
* toggle:: |
689 |
* checkbox:: |
* checkbox:: |
690 |
* checklist:: |
* checklist:: |
691 |
* editable-list:: |
* editable-list:: |
692 |
* group:: |
* group:: |
693 |
@end menu |
@end menu |
694 |
|
|
695 |
@node link, url-link, Basic Types, Basic Types |
@node link, url-link, Basic Types, Basic Types |
705 |
|
|
706 |
The @var{value}, if present, is used to initialize the @code{:value} |
The @var{value}, if present, is used to initialize the @code{:value} |
707 |
property. The value should be a string, which will be inserted in the |
property. The value should be a string, which will be inserted in the |
708 |
buffer. |
buffer. |
709 |
|
|
710 |
By default the link will be shown in brackets. |
By default the link will be shown in brackets. |
711 |
|
|
730 |
|
|
731 |
@findex browse-url-browser-function@r{, and @code{url-link} widget} |
@findex browse-url-browser-function@r{, and @code{url-link} widget} |
732 |
When this link is invoked, the @sc{www} browser specified by |
When this link is invoked, the @sc{www} browser specified by |
733 |
@code{browse-url-browser-function} will be called with @var{url}. |
@code{browse-url-browser-function} will be called with @var{url}. |
734 |
|
|
735 |
@node info-link, push-button, url-link, Basic Types |
@node info-link, push-button, url-link, Basic Types |
736 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
744 |
@end example |
@end example |
745 |
|
|
746 |
When this link is invoked, the built-in Info reader is started on |
When this link is invoked, the built-in Info reader is started on |
747 |
@var{address}. |
@var{address}. |
748 |
|
|
749 |
@node push-button, editable-field, info-link, Basic Types |
@node push-button, editable-field, info-link, Basic Types |
750 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
759 |
|
|
760 |
The @var{value}, if present, is used to initialize the @code{:value} |
The @var{value}, if present, is used to initialize the @code{:value} |
761 |
property. The value should be a string, which will be inserted in the |
property. The value should be a string, which will be inserted in the |
762 |
buffer. |
buffer. |
763 |
|
|
764 |
By default the tag will be shown in brackets. |
By default the tag will be shown in brackets. |
765 |
|
|
797 |
@vindex value-face@r{ keyword} |
@vindex value-face@r{ keyword} |
798 |
@item :value-face |
@item :value-face |
799 |
Face used for highlighting the editable field. Default is |
Face used for highlighting the editable field. Default is |
800 |
@code{widget-field-face}, see @ref{User Interface}. |
@code{widget-field-face}, see @ref{User Interface}. |
801 |
|
|
802 |
@vindex secret@r{ keyword} |
@vindex secret@r{ keyword} |
803 |
@item :secret |
@item :secret |
849 |
|
|
850 |
@table @code |
@table @code |
851 |
@vindex void@r{ keyword} |
@vindex void@r{ keyword} |
852 |
@item :void |
@item :void |
853 |
Widget type used as a fallback when the value does not match any of the |
Widget type used as a fallback when the value does not match any of the |
854 |
specified @var{type} arguments. |
specified @var{type} arguments. |
855 |
|
|
868 |
The current chosen type. |
The current chosen type. |
869 |
|
|
870 |
@vindex args@r{ keyword} |
@vindex args@r{ keyword} |
871 |
@item :args |
@item :args |
872 |
The list of types. |
The list of types. |
873 |
@end table |
@end table |
874 |
|
|
875 |
@node radio-button-choice, item, menu-choice, Basic Types |
@node radio-button-choice, item, menu-choice, Basic Types |
901 |
@item %b |
@item %b |
902 |
Replace with the radio button. |
Replace with the radio button. |
903 |
@item %% |
@item %% |
904 |
Insert a literal @samp{%}. |
Insert a literal @samp{%}. |
905 |
@end table |
@end table |
906 |
|
|
907 |
@vindex button-args@r{ keyword} |
@vindex button-args@r{ keyword} |
922 |
The current chosen type |
The current chosen type |
923 |
|
|
924 |
@vindex args@r{ keyword} |
@vindex args@r{ keyword} |
925 |
@item :args |
@item :args |
926 |
The list of types. |
The list of types. |
927 |
@end table |
@end table |
928 |
|
|
929 |
You can add extra radio button items to a @code{radio-button-choice} |
You can add extra radio button items to a @code{radio-button-choice} |
930 |
widget after it has been created with the function |
widget after it has been created with the function |
931 |
@code{widget-radio-add-item}. |
@code{widget-radio-add-item}. |
932 |
|
|
933 |
@defun widget-radio-add-item widget type |
@defun widget-radio-add-item widget type |
934 |
Add to @code{radio-button-choice} widget @var{widget} a new radio button |
Add to @code{radio-button-choice} widget @var{widget} a new radio button |
969 |
property. The value should be a string, which will be inserted in the |
property. The value should be a string, which will be inserted in the |
970 |
buffer as a button. Activating the button of a @code{choice-item} is |
buffer as a button. Activating the button of a @code{choice-item} is |
971 |
equivalent to activating the parent widget. This widget will only match |
equivalent to activating the parent widget. This widget will only match |
972 |
the specified value. |
the specified value. |
973 |
|
|
974 |
@node toggle, checkbox, choice-item, Basic Types |
@node toggle, checkbox, choice-item, Basic Types |
975 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
991 |
@item :on |
@item :on |
992 |
A string representing the @samp{on} state. By default the string |
A string representing the @samp{on} state. By default the string |
993 |
@samp{on}. |
@samp{on}. |
994 |
@item :off |
@item :off |
995 |
A string representing the @samp{off} state. By default the string |
A string representing the @samp{off} state. By default the string |
996 |
@samp{off}. |
@samp{off}. |
997 |
@vindex on-glyph@r{ keyword} |
@vindex on-glyph@r{ keyword} |
1047 |
@item %b |
@item %b |
1048 |
Replace with the checkbox. |
Replace with the checkbox. |
1049 |
@item %% |
@item %% |
1050 |
Insert a literal @samp{%}. |
Insert a literal @samp{%}. |
1051 |
@end table |
@end table |
1052 |
|
|
1053 |
@vindex greedy@r{ keyword} |
@vindex greedy@r{ keyword} |
1072 |
The widgets representing each type. |
The widgets representing each type. |
1073 |
|
|
1074 |
@vindex args@r{ keyword} |
@vindex args@r{ keyword} |
1075 |
@item :args |
@item :args |
1076 |
The list of types. |
The list of types. |
1077 |
@end table |
@end table |
1078 |
|
|
1079 |
@node editable-list, group, checklist, Basic Types |
@node editable-list, group, checklist, Basic Types |
1088 |
@end example |
@end example |
1089 |
|
|
1090 |
The value is a list, where each member represents one widget of type |
The value is a list, where each member represents one widget of type |
1091 |
@var{type}. |
@var{type}. |
1092 |
|
|
1093 |
The following extra properties are recognized: |
The following extra properties are recognized: |
1094 |
|
|
1106 |
@item %d |
@item %d |
1107 |
Insert the @b{[DEL]} button. |
Insert the @b{[DEL]} button. |
1108 |
@item %% |
@item %% |
1109 |
Insert a literal @samp{%}. |
Insert a literal @samp{%}. |
1110 |
@end table |
@end table |
1111 |
|
|
1112 |
@vindex insert-button-args@r{ keyword} |
@vindex insert-button-args@r{ keyword} |
1147 |
TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...) |
TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...) |
1148 |
@end example |
@end example |
1149 |
|
|
1150 |
The value is a list, with one member for each @var{type}. |
The value is a list, with one member for each @var{type}. |
1151 |
|
|
1152 |
@node Sexp Types, Widget Properties, Basic Types, Top |
@node Sexp Types, Widget Properties, Basic Types, Top |
1153 |
@comment |
@comment |
1159 |
categories described in this section. |
categories described in this section. |
1160 |
|
|
1161 |
@menu |
@menu |
1162 |
* constants:: |
* constants:: |
1163 |
* generic:: |
* generic:: |
1164 |
* atoms:: |
* atoms:: |
1165 |
* composite:: |
* composite:: |
1166 |
@end menu |
@end menu |
1167 |
|
|
1168 |
@node constants, generic, Sexp Types, Sexp Types |
@node constants, generic, Sexp Types, Sexp Types |
1185 |
|
|
1186 |
@deffn Widget const |
@deffn Widget const |
1187 |
This will display any valid s-expression in an immutable part of the |
This will display any valid s-expression in an immutable part of the |
1188 |
buffer. |
buffer. |
1189 |
@end deffn |
@end deffn |
1190 |
|
|
1191 |
There are two variations of the @code{const} widget, namely |
There are two variations of the @code{const} widget, namely |
1218 |
|
|
1219 |
@deffn Widget sexp |
@deffn Widget sexp |
1220 |
This will allow you to edit any valid s-expression in an editable buffer |
This will allow you to edit any valid s-expression in an editable buffer |
1221 |
field. |
field. |
1222 |
|
|
1223 |
The @code{sexp} widget takes the same keyword arguments as the |
The @code{sexp} widget takes the same keyword arguments as the |
1224 |
@code{editable-field} widget. @xref{editable-field}. |
@code{editable-field} widget. @xref{editable-field}. |
1262 |
@deffn Widget file |
@deffn Widget file |
1263 |
Allows you to edit a file name in an editable field. If you invoke |
Allows you to edit a file name in an editable field. If you invoke |
1264 |
the tag button, you can edit the file name in the mini-buffer with |
the tag button, you can edit the file name in the mini-buffer with |
1265 |
completion. |
completion. |
1266 |
|
|
1267 |
Keywords: |
Keywords: |
1268 |
@table @code |
@table @code |
1353 |
string string))) |
string string))) |
1354 |
@end example |
@end example |
1355 |
|
|
1356 |
The value of a widget of this type will either have the form |
The value of a widget of this type will either have the form |
1357 |
@code{(file t)} or @code{(file string string)}. |
@code{(file t)} or @code{(file string string)}. |
1358 |
|
|
1359 |
This concept of inline is probably hard to understand. It was certainly |
This concept of inline is probably hard to understand. It was certainly |
1403 |
widget again. It is enough to call @code{widget-setup} once if you |
widget again. It is enough to call @code{widget-setup} once if you |
1404 |
modify multiple widgets. This is currently only necessary if the widget |
modify multiple widgets. This is currently only necessary if the widget |
1405 |
contains an editing field, but may be necessary for other widgets in the |
contains an editing field, but may be necessary for other widgets in the |
1406 |
future. |
future. |
1407 |
|
|
1408 |
If your application needs to associate some information with the widget |
If your application needs to associate some information with the widget |
1409 |
objects, for example a reference to the item being edited, it can be |
objects, for example a reference to the item being edited, it can be |
1426 |
@end defun |
@end defun |
1427 |
|
|
1428 |
Occasionally it can be useful to know which kind of widget you have, |
Occasionally it can be useful to know which kind of widget you have, |
1429 |
i.e.@: the name of the widget type you gave when the widget was created. |
i.e.@: the name of the widget type you gave when the widget was created. |
1430 |
|
|
1431 |
@defun widget-type widget |
@defun widget-type widget |
1432 |
Return the name of @var{widget}, a symbol. |
Return the name of @var{widget}, a symbol. |
1459 |
all its ancestors. |
all its ancestors. |
1460 |
|
|
1461 |
@lisp |
@lisp |
1462 |
(while widget |
(while widget |
1463 |
(widget-apply widget :activate) |
(widget-apply widget :activate) |
1464 |
(setq widget (widget-get widget :parent))) |
(setq widget (widget-get widget :parent))) |
1465 |
@end lisp |
@end lisp |
1482 |
You can define specialized widgets with @code{define-widget}. It allows |
You can define specialized widgets with @code{define-widget}. It allows |
1483 |
you to create a shorthand for more complex widgets, including specifying |
you to create a shorthand for more complex widgets, including specifying |
1484 |
component widgets and new default values for the keyword |
component widgets and new default values for the keyword |
1485 |
arguments. |
arguments. |
1486 |
|
|
1487 |
@defun define-widget name class doc &rest args |
@defun define-widget name class doc &rest args |
1488 |
Define a new widget type named @var{name} from @code{class}. |
Define a new widget type named @var{name} from @code{class}. |
1489 |
|
|
1490 |
@var{name} and class should both be symbols, @code{class} should be one |
@var{name} and class should both be symbols, @code{class} should be one |
1491 |
of the existing widget types. |
of the existing widget types. |
1492 |
|
|
1493 |
The third argument @var{DOC} is a documentation string for the widget. |
The third argument @var{DOC} is a documentation string for the widget. |
1494 |
|
|
1517 |
conversions, you can use @code{identity} as your conversion function. |
conversions, you can use @code{identity} as your conversion function. |
1518 |
|
|
1519 |
The following additional keyword arguments are useful when defining new |
The following additional keyword arguments are useful when defining new |
1520 |
widgets: |
widgets: |
1521 |
@table @code |
@table @code |
1522 |
@vindex convert-widget@r{ keyword} |
@vindex convert-widget@r{ keyword} |
1523 |
@item :convert-widget |
@item :convert-widget |
1524 |
Function to convert a widget type before creating a widget of that |
Function to convert a widget type before creating a widget of that |
1525 |
type. It takes a widget type as an argument, and returns the converted |
type. It takes a widget type as an argument, and returns the converted |
1526 |
widget type. When a widget is created, this function is called for the |
widget type. When a widget is created, this function is called for the |
1527 |
widget type and all the widget's parent types, most derived first. |
widget type and all the widget's parent types, most derived first. |
1528 |
|
|
1529 |
The following predefined functions can be used here: |
The following predefined functions can be used here: |
1530 |
|
|
1536 |
Initialize @code{:value} from @code{:args} in @var{widget}. |
Initialize @code{:value} from @code{:args} in @var{widget}. |
1537 |
@end defun |
@end defun |
1538 |
|
|
1539 |
|
@vindex copy@r{ keyword} |
1540 |
|
@item :copy |
1541 |
|
Function to deep copy a widget type. It takes a shallow copy of the |
1542 |
|
widget type as an argument (made by @code{copy-sequence}), and returns a |
1543 |
|
deep copy. The purpose of this is to avoid having different instances |
1544 |
|
of combined widgets share nested attributes. |
1545 |
|
|
1546 |
|
The following predefined functions can be used here: |
1547 |
|
|
1548 |
|
@defun widget-types-copy widget |
1549 |
|
Copy @code{:args} as widget types in @var{widget}. |
1550 |
|
@end defun |
1551 |
|
|
1552 |
@vindex value-to-internal@r{ keyword} |
@vindex value-to-internal@r{ keyword} |
1553 |
@item :value-to-internal |
@item :value-to-internal |
1554 |
Function to convert the value to the internal format. The function |
Function to convert the value to the internal format. The function |
1596 |
@end defun |
@end defun |
1597 |
|
|
1598 |
@vindex value-get@r{ keyword} |
@vindex value-get@r{ keyword} |
1599 |
@item :value-get |
@item :value-get |
1600 |
Function to extract the value of a widget, as it is displayed in the |
Function to extract the value of a widget, as it is displayed in the |
1601 |
buffer. |
buffer. |
1602 |
|
|
1603 |
The following predefined function can be used here: |
The following predefined function can be used here: |
1604 |
|
|
1621 |
@vindex action@r{ keyword} |
@vindex action@r{ keyword} |
1622 |
@item :action |
@item :action |
1623 |
Function to handle user initiated events. By default, @code{:notify} |
Function to handle user initiated events. By default, @code{:notify} |
1624 |
the parent. |
the parent. |
1625 |
|
|
1626 |
The following predefined function can be used here: |
The following predefined function can be used here: |
1627 |
|
|
1644 |
If you want to define a new widget from scratch, use the @code{default} |
If you want to define a new widget from scratch, use the @code{default} |
1645 |
widget as its base. |
widget as its base. |
1646 |
|
|
1647 |
@deffn Widget default |
@deffn Widget default |
1648 |
Widget used as a base for other widgets. |
Widget used as a base for other widgets. |
1649 |
|
|
1650 |
It provides most of the functionality that is referred to as ``by |
It provides most of the functionality that is referred to as ``by |
1651 |
default'' in this text. |
default'' in this text. |
1652 |
@end deffn |
@end deffn |
1653 |
|
|
1654 |
@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top |
@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top |
1661 |
shows the value of each keyword, but uses links for certain keywords |
shows the value of each keyword, but uses links for certain keywords |
1662 |
such as @samp{:parent}, which avoids printing cyclic structures. |
such as @samp{:parent}, which avoids printing cyclic structures. |
1663 |
|
|
1664 |
@deffn Command widget-browse WIDGET |
@deffn Command widget-browse @var{widget} |
1665 |
Create a widget browser for WIDGET. |
Create a widget browser for @var{widget}. |
1666 |
When called interactively, prompt for WIDGET. |
When called interactively, prompt for @var{widget}. |
1667 |
@end deffn |
@end deffn |
1668 |
|
|
1669 |
@deffn Command widget-browse-other-window WIDGET |
@deffn Command widget-browse-other-window @var{widget} |
1670 |
Create a widget browser for WIDGET and show it in another window. |
Create a widget browser for @var{widget} and show it in another window. |
1671 |
When called interactively, prompt for WIDGET. |
When called interactively, prompt for @var{widget}. |
1672 |
@end deffn |
@end deffn |
1673 |
|
|
1674 |
@deffn Command widget-browse-at POS |
@deffn Command widget-browse-at @var{pos} |
1675 |
Create a widget browser for the widget at POS. |
Create a widget browser for the widget at @var{pos}. |
1676 |
When called interactively, use the position of point. |
When called interactively, use the position of point. |
1677 |
@end deffn |
@end deffn |
1678 |
|
|
1683 |
|
|
1684 |
There is a minor mode for manipulating widgets in major modes that |
There is a minor mode for manipulating widgets in major modes that |
1685 |
don't provide any support for widgets themselves. This is mostly |
don't provide any support for widgets themselves. This is mostly |
1686 |
intended to be useful for programmers doing experiments. |
intended to be useful for programmers doing experiments. |
1687 |
|
|
1688 |
@deffn Command widget-minor-mode |
@deffn Command widget-minor-mode |
1689 |
Toggle minor mode for traversing widgets. |
Toggle minor mode for traversing widgets. |
1716 |
@cindex todo |
@cindex todo |
1717 |
|
|
1718 |
@itemize @bullet |
@itemize @bullet |
1719 |
@item |
@item |
1720 |
It should be possible to add or remove items from a list with @kbd{C-k} |
It should be possible to add or remove items from a list with @kbd{C-k} |
1721 |
and @kbd{C-o} (suggested by @sc{rms}). |
and @kbd{C-o} (suggested by @sc{rms}). |
1722 |
|
|
1723 |
@item |
@item |
1724 |
The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single |
The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single |
1725 |
dash (@samp{-}). The dash should be a button that, when invoked, asks |
dash (@samp{-}). The dash should be a button that, when invoked, asks |
1726 |
whether you want to add or delete an item (@sc{rms} wanted to git rid of |
whether you want to add or delete an item (@sc{rms} wanted to git rid of |
1738 |
|
|
1739 |
@item |
@item |
1740 |
Add commands to show overview of object and class hierarchies to the |
Add commands to show overview of object and class hierarchies to the |
1741 |
browser. |
browser. |
1742 |
|
|
1743 |
@item |
@item |
1744 |
Find a way to disable mouse highlight for inactive widgets. |
Find a way to disable mouse highlight for inactive widgets. |
1745 |
|
|
1746 |
@item |
@item |
1762 |
Find clean way to implement variable length list. |
Find clean way to implement variable length list. |
1763 |
See @code{TeX-printer-list} for an explanation. |
See @code{TeX-printer-list} for an explanation. |
1764 |
|
|
1765 |
@item |
@item |
1766 |
@kbd{C-h} in @code{widget-prompt-value} should give type specific help. |
@kbd{C-h} in @code{widget-prompt-value} should give type specific help. |
1767 |
|
|
1768 |
@item |
@item |
1769 |
Add a @code{mailto} widget. |
Add a @code{mailto} widget. |
1770 |
@end itemize |
@end itemize |
1771 |
|
|