/[emacs]/emacs/man/widget.texi
ViewVC logotype

Diff of /emacs/man/widget.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.13.2.1

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26