Mercurial > hg > xemacs-beta

comparison man/widget.texi @ 155:43dd3413c7c7 r20-3b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-3b4
author cvs
date Mon, 13 Aug 2007 09:39:39 +0200
parents 25f70ba0133c
children 6b37e6ddd302
comparison
equal deleted inserted replaced
154:94141801dd7e 155:43dd3413c7c7
11 11
12 @node Top, Introduction, (dir), (dir) 12 @node Top, Introduction, (dir), (dir)
13 @comment node-name, next, previous, up 13 @comment node-name, next, previous, up
14 @top The Emacs Widget Library 14 @top The Emacs Widget Library
15 15
16 Version: 1.98 16 Version: 1.9907
17 17
18 @menu 18 @menu
19 * Introduction:: 19 * Introduction::
20 * User Interface:: 20 * User Interface::
21 * Programming Example:: 21 * Programming Example::
62 visible in the buffer. 62 visible in the buffer.
63 @item item 63 @item item
64 A simple constant widget intended to be used in the @code{menu-choice} and 64 A simple constant widget intended to be used in the @code{menu-choice} and
65 @code{radio-button-choice} widgets. 65 @code{radio-button-choice} widgets.
66 @item choice-item 66 @item choice-item
67 An button item only intended for use in choices. When activated, the user 67 An button item only intended for use in choices. When invoked, the user
68 will be asked to select another option from the choice widget. 68 will be asked to select another option from the choice widget.
69 @item toggle 69 @item toggle
70 A simple @samp{on}/@samp{off} switch. 70 A simple @samp{on}/@samp{off} switch.
71 @item checkbox 71 @item checkbox
72 A checkbox (@samp{[ ]}/@samp{[X]}). 72 A checkbox (@samp{[ ]}/@samp{[X]}).
189 @end deffn 189 @end deffn
190 190
191 @subsection Buttons 191 @subsection Buttons
192 192
193 Some portions of the buffer have an associated @dfn{action}, which can 193 Some portions of the buffer have an associated @dfn{action}, which can
194 be @dfn{activated} by a standard key or mouse command. These portions 194 be @dfn{invoked} by a standard key or mouse command. These portions
195 are called @dfn{buttons}. The default commands for activating a button 195 are called @dfn{buttons}. The default commands for activating a button
196 are: 196 are:
197 197
198 @table @kbd 198 @table @kbd
199 @item @key{RET} 199 @item @key{RET}
200 @deffn Command widget-button-press @var{pos} &optional @var{event} 200 @deffn Command widget-button-press @var{pos} &optional @var{event}
201 Activate the button at @var{pos}, defaulting to point. 201 Invoke the button at @var{pos}, defaulting to point.
202 If point is not located on a button, activate the binding in 202 If point is not located on a button, invoke the binding in
203 @code{widget-global-map} (by default the global map). 203 @code{widget-global-map} (by default the global map).
204 @end deffn 204 @end deffn
205 205
206 @item mouse-2 206 @item mouse-2
207 @deffn Command widget-button-click @var{event} 207 @deffn Command widget-button-click @var{event}
208 Activate the button at the location of the mouse pointer. If the mouse 208 Invoke the button at the location of the mouse pointer. If the mouse
209 pointer is located in an editable text field, activate the binding in 209 pointer is located in an editable text field, invoke the binding in
210 @code{widget-global-map} (by default the global map). 210 @code{widget-global-map} (by default the global map).
211 @end deffn 211 @end deffn
212 @end table 212 @end table
213 213
214 There are several different kind of buttons, all of which are present in 214 There are several different kind of buttons, all of which are present in
215 the example: 215 the example:
216 216
217 @table @emph 217 @table @emph
218 @item The Option Field Tags. 218 @item The Option Field Tags.
219 When you activate one of these buttons, you will be asked to choose 219 When you invoke one of these buttons, you will be asked to choose
220 between a number of different options. This is how you edit an option 220 between a number of different options. This is how you edit an option
221 field. Option fields are created by the @code{menu-choice} widget. In 221 field. Option fields are created by the @code{menu-choice} widget. In
222 the example, @samp{@b{Choose}} is an option field tag. 222 the example, @samp{@b{Choose}} is an option field tag.
223 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons. 223 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons.
224 Activating these will insert or delete elements from a editable list. 224 Activating these will insert or delete elements from a editable list.
231 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons. 231 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons.
232 Activating one of these will convert it to the other. This is useful 232 Activating one of these will convert it to the other. This is useful
233 for implementing multiple-choice fields. You can create it wit 233 for implementing multiple-choice fields. You can create it wit
234 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons. 234 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons.
235 Only one radio button in a @code{radio-button-choice} widget can be 235 Only one radio button in a @code{radio-button-choice} widget can be
236 selected at any time. When you activate one of the unselected radio 236 selected at any time. When you invoke one of the unselected radio
237 buttons, it will be selected and the previous selected radio button will 237 buttons, it will be selected and the previous selected radio button will
238 become unselected. 238 become unselected.
239 @item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons. 239 @item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons.
240 These are explicit buttons made with the @code{push-button} widget. The main 240 These are explicit buttons made with the @code{push-button} widget. The main
241 difference from the @code{link} widget is that the buttons are will be 241 difference from the @code{link} widget is that the buttons are will be
658 658
659 @example 659 @example
660 TYPE ::= (url-link [KEYWORD ARGUMENT]... URL) 660 TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
661 @end example 661 @end example
662 662
663 When this link is activated, the @sc{www} browser specified by 663 When this link is invoked, the @sc{www} browser specified by
664 @code{browse-url-browser-function} will be called with @var{url}. 664 @code{browse-url-browser-function} will be called with @var{url}.
665 665
666 @node info-link, push-button, url-link, Basic Types 666 @node info-link, push-button, url-link, Basic Types
667 @comment node-name, next, previous, up 667 @comment node-name, next, previous, up
668 @subsection The @code{info-link} Widget 668 @subsection The @code{info-link} Widget
671 671
672 @example 672 @example
673 TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS) 673 TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
674 @end example 674 @end example
675 675
676 When this link is activated, the build-in info browser is started on 676 When this link is invoked, the build-in info browser is started on
677 @var{address}. 677 @var{address}.
678 678
679 @node push-button, editable-field, info-link, Basic Types 679 @node push-button, editable-field, info-link, Basic Types
680 @comment node-name, next, previous, up 680 @comment node-name, next, previous, up
681 @subsection The @code{push-button} Widget 681 @subsection The @code{push-button} Widget
737 737
738 @item :keymap 738 @item :keymap
739 Keymap used in the editable field. The default value is 739 Keymap used in the editable field. The default value is
740 @code{widget-field-keymap}, which allows you to use all the normal 740 @code{widget-field-keymap}, which allows you to use all the normal
741 editing commands, even if the buffers major mode supress some of them. 741 editing commands, even if the buffers major mode supress some of them.
742 Pressing return activates the function specified by @code{:activate}. 742 Pressing return invokes the function specified by @code{:action}.
743
744 @item :hide-front-space
745 @itemx :hide-rear-space
746 In order to keep track of the editable field, emacs places an invisible
747 space character in front of the field, and for fixed sized fields also
748 in the rear end of the field. For fields that extent to the end of the
749 line, the terminating linefeed serves that purpose instead.
750
751 Emacs will try to make the spaces intangible when it is safe to do so.
752 Intangible means that the cursor motion commands will skip over the
753 character as if it didn't exist. This is safe to do when the text
754 preceding or following the widget cannot possible change during the
755 lifetime of the @code{editable-field} widget. The preferred way to tell
756 Emacs this, is to add text to the @code{:format} property around the
757 value. For example @code{:format "Tag: %v "}.
758
759 You can overwrite the internal safety check by setting the
760 @code{:hide-front-space} or @code{:hide-rear-space} properties to
761 non-nil. This is not recommended. For example, @emph{all} text that
762 belongs to a widget (i.e. is created from its @code{:format} string) will
763 change whenever the widget changes its value.
764
765 @end table 743 @end table
766 744
767 @node text, menu-choice, editable-field, Basic Types 745 @node text, menu-choice, editable-field, Basic Types
768 @comment node-name, next, previous, up 746 @comment node-name, next, previous, up
769 @subsection The @code{text} Widget 747 @subsection The @code{text} Widget
1158 @deffn Widget character 1136 @deffn Widget character
1159 Allows you to enter a character in an editable field. 1137 Allows you to enter a character in an editable field.
1160 @end deffn 1138 @end deffn
1161 1139
1162 @deffn Widget file 1140 @deffn Widget file
1163 Allows you to edit a file name in an editable field. You you activate 1141 Allows you to edit a file name in an editable field. If you invoke
1164 the tag button, you can edit the file name in the mini-buffer with 1142 the tag button, you can edit the file name in the mini-buffer with
1165 completion. 1143 completion.
1166 1144
1167 Keywords: 1145 Keywords:
1168 @table @code 1146 @table @code
1579 It should be possible to add or remove items from a list with @kbd{C-k} 1557 It should be possible to add or remove items from a list with @kbd{C-k}
1580 and @kbd{C-o} (suggested by @sc{rms}). 1558 and @kbd{C-o} (suggested by @sc{rms}).
1581 1559
1582 @item 1560 @item
1583 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single 1561 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
1584 dash (@samp{-}). The dash should be a button that, when activated, ask 1562 dash (@samp{-}). The dash should be a button that, when invoked, ask
1585 whether you want to add or delete an item (@sc{rms} wanted to git rid of 1563 whether you want to add or delete an item (@sc{rms} wanted to git rid of
1586 the ugly buttons, the dash is my idea). 1564 the ugly buttons, the dash is my idea).
1587 1565
1588 @item 1566 @item
1589 The @code{menu-choice} tag should be prettier, something like the abbreviated 1567 The @code{menu-choice} tag should be prettier, something like the abbreviated
1622 See @code{TeX-printer-list} for an explanation. 1600 See @code{TeX-printer-list} for an explanation.
1623 1601
1624 @item 1602 @item
1625 @kbd{C-h} in @code{widget-prompt-value} should give type specific help. 1603 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
1626 1604
1605 @item
1606 A mailto widget.
1607
1627 @end itemize 1608 @end itemize
1628 1609
1629 @contents 1610 @contents
1630 @bye 1611 @bye