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