-This is ../info/widget.info, produced by makeinfo version 3.12s from
+This is ../info/widget.info, produced by makeinfo version 4.0 from
widget.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-* Widgets: (widget). The Emacs Widget Library.
+* Widgets: (widget). The Emacs Widget Library.
END-INFO-DIR-ENTRY
\1f
The advantages for a programmer of using the `widget' package to
implement forms are:
- 1. More complex field than just editable text are supported.
+ 1. More complex fields than just editable text are supported.
2. You can give the user immediate feedback if he enters invalid data
in a text field, and sometimes prevent entering invalid data.
(make-local-variable 'widget-example-repeat)
(widget-insert "Here is some documentation.\n\nName: ")
(widget-create 'editable-field
- :size 13
- "My Name")
+ :size 13
+ "My Name")
(widget-create 'menu-choice
- :tag "Choose"
- :value "This"
- :help-echo "Choose me, please!"
- :notify (lambda (widget &rest ignore)
- (message "%s is a good choice!"
- (widget-value widget)))
- '(item :tag "This option" :value "This")
- '(choice-item "That option")
- '(editable-field :menu-tag "No option" "Thus option"))
+ :tag "Choose"
+ :value "This"
+ :help-echo "Choose me, please!"
+ :notify (lambda (widget &rest ignore)
+ (message "%s is a good choice!"
+ (widget-value widget)))
+ '(item :tag "This option" :value "This")
+ '(choice-item "That option")
+ '(editable-field :menu-tag "No option" "Thus option"))
(widget-insert "Address: ")
(widget-create 'editable-field
- "Some Place\nIn some City\nSome country.")
+ "Some Place\nIn some City\nSome country.")
(widget-insert "\nSee also ")
(widget-create 'link
- :notify (lambda (&rest ignore)
- (widget-value-set widget-example-repeat
- '("En" "To" "Tre"))
- (widget-setup))
- "other work")
+ :notify (lambda (&rest ignore)
+ (widget-value-set widget-example-repeat
+ '("En" "To" "Tre"))
+ (widget-setup))
+ "other work")
(widget-insert " for more information.\n\nNumbers: count to three below\n")
(setq widget-example-repeat
- (widget-create 'editable-list
- :entry-format "%i %d %v"
- :notify (lambda (widget &rest ignore)
- (let ((old (widget-get widget
- ':example-length))
- (new (length (widget-value widget))))
- (unless (eq old new)
- (widget-put widget ':example-length new)
- (message "You can count to %d." new))))
- :value '("One" "Eh, two?" "Five!")
- '(editable-field :value "three")))
+ (widget-create 'editable-list
+ :entry-format "%i %d %v"
+ :notify (lambda (widget &rest ignore)
+ (let ((old (widget-get widget
+ ':example-length))
+ (new (length (widget-value widget))))
+ (unless (eq old new)
+ (widget-put widget ':example-length new)
+ (message "You can count to %d." new))))
+ :value '("One" "Eh, two?" "Five!")
+ '(editable-field :value "three")))
(widget-insert "\n\nSelect multiple:\n\n")
(widget-create 'checkbox t)
(widget-insert " This\n")
(widget-create 'checkbox nil)
(widget-insert " That\n")
(widget-create 'checkbox
- :notify (lambda (&rest ignore) (message "Tickle"))
- t)
+ :notify (lambda (&rest ignore) (message "Tickle"))
+ t)
(widget-insert " Thus\n\nSelect one:\n\n")
(widget-create 'radio-button-choice
- :value "One"
- :notify (lambda (widget &rest ignore)
- (message "You selected %s"
- (widget-value widget)))
- '(item "One") '(item "Another One.") '(item "A Final One."))
+ :value "One"
+ :notify (lambda (widget &rest ignore)
+ (message "You selected %s"
+ (widget-value widget)))
+ '(item "One") '(item "Another One.") '(item "A Final One."))
(widget-insert "\n")
(widget-create 'push-button
- :notify (lambda (&rest ignore)
- (if (= (length (widget-value widget-example-repeat))
- 3)
- (message "Congratulation!")
- (error "Three was the count!")))
- "Apply Form")
+ :notify (lambda (&rest ignore)
+ (if (= (length (widget-value widget-example-repeat))
+ 3)
+ (message "Congratulation!")
+ (error "Three was the count!")))
+ "Apply Form")
(widget-insert " ")
(widget-create 'push-button
- :notify (lambda (&rest ignore)
- (widget-example))
- "Reset Form")
+ :notify (lambda (&rest ignore)
+ (widget-example))
+ "Reset Form")
(widget-insert "\n")
(use-local-map widget-keymap)
(widget-setup))
NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
| NAME
- Where, NAME is a widget name, KEYWORD is the name of a property,
+ where NAME is a widget name, KEYWORD is the name of a property,
ARGUMENT is the value of the property, and ARGS are interpreted in a
widget specific way.
`%{'
`%}'
- The text inside will be displayed with the face specified by
+ The text inside will be displayed in the face specified by
`:sample-face'.
`%v'
- This will be replaces with the buffer representation of the
- widgets value. What this is depends on the widget type.
+ This will be replaced with the buffer representation of the
+ widget's value. What this is depends on the widget type.
`%d'
Insert the string specified by `:doc' here.
The value of the symbol is expanded according to this table.
`:doc'
- The string inserted by the `%d' escape in the format string.
+ The string inserted by the `%d' or `%h' escape in the format
+ string.
`:tag'
The string inserted by the `%t' escape in the format string.
specified value.
`:validate'
- A function which takes a widget as an argument, and return nil if
- the widgets current value is valid for the widget. Otherwise, it
+ A function which takes a widget as an argument, and returns nil if
+ the widget's current value is valid for the widget. Otherwise it
should return the widget containing the invalid data, and set that
- widgets `:error' property to a string explaining the error.
+ widget's `:error' property to a string explaining the error.
The following predefined function can be used:
The following extra properties are recognized.
`:size'
- The width of the editable field.
- By default the field will reach to the end of the line.
+ The minimum width of the editable field.
+ By default the field will reach to the end of the line. If the
+ content is too large, the displayed representation will expand to
+ contain it. The content is not truncated to size.
`:value-face'
Face used for highlighting the editable field. Default is
`:keymap'
Keymap used in the editable field. The default value is
`widget-field-keymap', which allows you to use all the normal
- editing commands, even if the buffers major mode suppress some of
+ editing commands, even if the buffer's major mode suppress some of
them. Pressing return invokes the function specified by `:action'.
\1f
TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
- The TYPE arguments represents each possible choice. The widgets
-value of will be the value of the chosen TYPE argument. This widget
-will match any value that matches at least one of the specified TYPE
-arguments.
+ The TYPE argument represents each possible choice. The widget's
+value will be that of the chosen TYPE argument. This widget will match
+any value matching at least one of the specified TYPE arguments.
`:void'
Widget type used as a fallback when the value does not match any
TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
- The TYPE arguments represents each possible choice. The widgets
-value of will be the value of the chosen TYPE argument. This widget
-will match any value that matches at least one of the specified TYPE
-arguments.
+ The TYPE argument represents each possible choice. The widget's
+value will be that of the chosen TYPE argument. This widget will match
+any value matching at least one of the specified TYPE arguments.
The following extra properties are recognized.
TYPE ::= (toggle [KEYWORD ARGUMENT]...)
- The widget has two possible states, `on' and `off', which
-corresponds to a `t' or `nil' value.
+ The widget has two possible states, `on' and `off', which correspond
+to a `t' or `nil' value respectively.
The following extra properties are recognized.
TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
- The TYPE arguments represents each checklist item. The widgets
-value of will be a list containing the value of each ticked TYPE
-argument. The checklist widget will match a list whose elements all
-matches at least one of the specified TYPE arguments.
+ The TYPE arguments represents each checklist item. The widget's
+value will be a list containing the values of all ticked TYPE
+arguments. The checklist widget will match a list whose elements all
+match at least one of the specified TYPE arguments.
The following extra properties are recognized.
Insert a literal `%'.
`:greedy'
- Usually, a checklist will only match if the items are in the exact
+ Usually a checklist will only match if the items are in the exact
sequence given in the specification. By setting `:greedy' to
- non-nil, it will allow the items to come in any sequence.
- However, if you extract the value they will be in the sequence
- given in the checklist. I.e. the original sequence is forgotten.
+ non-nil, it will allow the items to appear in any sequence.
+ However, if you extract the values they will be in the sequence
+ given in the checklist. I.e. the original sequence is forgotten.
`button-args'
A list of keywords to pass to the checkboxes. Useful for setting
t)' or `(file string string)'.
This concept of inline is probably hard to understand. It was
-certainly hard to implement so instead of confuse you more by trying to
-explain it here, I'll just suggest you meditate over it for a while.
+certainly hard to implement so instead of confusing you more by trying
+to explain it here, I'll just suggest you meditate over it for a while.
- Widget: choice
- Allows you to edit a sexp which may have one of fixed set of
+ Allows you to edit a sexp which may have one of a fixed set of
types. It is currently implemented with the `choice-menu' basic
widget, and has a similar syntax.
;; Make WIDGET active.
(widget-apply WIDGET :activate)
- A widget is inactive if itself, or any of its ancestors (found by
+ A widget is inactive if itself or any of its ancestors (found by
following the `:parent' link) have been deactivated. To make sure a
-widget is really active, you must therefore activate both itself, and
+widget is really active, you must therefore activate both itself and
all its ancestors.
(while widget
(setq widget (widget-get widget :parent)))
You can check if a widget has been made inactive by examining the
-value of `:inactive' keyword. If this is non-nil, the widget itself has
-been deactivated. This is different from using the `:active' keyword,
-in that the later tell you if the widget *or* any of its ancestors have
-been deactivated. Do not attempt to set the `:inactive' keyword
-directly. Use the `:activate' `:deactivated' keywords instead.
+value of the `:inactive' keyword. If this is non-nil, the widget itself
+has been deactivated. This is different from using the `:active'
+keyword, in that the latter tells you if the widget *or* any of its
+ancestors have been deactivated. Do not attempt to set the `:inactive'
+keyword directly. Use the `:activate' `:deactivate' keywords instead.
\1f
File: widget.info, Node: Defining New Widgets, Next: Widget Browser, Prev: Widget Properties, Up: Top
====================
You can define specialized widgets with `define-widget'. It allows
-you to create a shorthand for more complex widgets, including specifying
-component widgets and default new default values for the keyword
+you to create a shorthand for more complex widgets. This includes
+specifying component widgets and new default values for the keyword
arguments.
- Function: widget-define name class doc &rest args
The third argument DOC is a documentation string for the widget.
- After the new widget has been defined, the following two calls will
+ After the new widget has been defined the following two calls will
create identical widgets:
* (widget-create NAME)
* (apply widget-create CLASS ARGS)
- Using `widget-define' does just store the definition of the widget
-type in the `widget-type' property of NAME, which is what
-`widget-create' uses.
+ Using `widget-define' just stores the definition of the widget type
+in the `widget-type' property of NAME, which is what `widget-create'
+uses.
If you just want to specify defaults for keywords with no complex
conversions, you can use `identity' as your conversion function.
Function to convert a widget type before creating a widget of that
type. It takes a widget type as an argument, and returns the
converted widget type. When a widget is created, this function is
- called for the widget type and all the widgets parent types, most
+ called for the widget type and all the widget's parent types, most
derived first.
The following predefined functions can be used here:
`:value-to-internal'
Function to convert the value to the internal format. The function
- takes two arguments, a widget and an external value, and returns
+ takes two arguments, a widget and an external value. It returns
the internal value. The function is called on the present `:value'
when the widget is created, and on any value set later with
`widget-value-set'.
`:create'
Function to create a widget from scratch. The function takes one
- argument, a widget type, and create a widget of that type, insert
- it in the buffer, and return a widget object.
+ argument, a widget type, and creates a widget of that type,
+ inserts it in the buffer, and returns a widget object.
`:delete'
Function to delete a widget. The function takes one argument, a
`:value-create'
Function to expand the `%v' escape in the format string. It will
- be called with the widget as its argument. Should insert a
- representation of the widgets value in the buffer.
+ be called with the widget as its argument and should insert a
+ representation of the widget's value in the buffer.
`:value-delete'
- Should remove the representation of the widgets value from the
+ Should remove the representation of the widget's value from the
buffer. It will be called with the widget as its argument. It
doesn't have to remove the text, but it should release markers and
- delete nested widgets if such has been used.
+ delete nested widgets if such have been used.
The following predefined function can be used here:
non-standard escapes.
You should end up calling `widget-default-format-handler' to handle
- unknown escape sequences, which will handle the `%h' and any future
- escape sequences, as well as give an error for unknown escapes.
+ unknown escape sequences. It will handle the `%h' and any future
+ escape sequences as well as give an error for unknown escapes.
`:action'
Function to handle user initiated events. By default, `:notify'
should take four arguments, WIDGET, PROMPT, VALUE, and UNBOUND and
should return a value for widget entered by the user. PROMPT is
the prompt to use. VALUE is the default value to use, unless
- UNBOUND is non-nil in which case there are no default value. The
+ UNBOUND is non-nil. In this case there is no default value. The
function should read the value using the method most natural for
- this widget, and does not have to check that it matches.
+ this widget and does not have to check whether it matches.
If you want to define a new widget from scratch, use the `default'
widget as its base.
\1f
Tag Table:
-Node: Top\7f203
-Node: Introduction\7f583
-Node: User Interface\7f4066
-Node: Programming Example\7f8961
-Node: Setting Up the Buffer\7f12278
-Node: Basic Types\7f13995
-Node: link\7f20040
-Node: url-link\7f20554
-Node: info-link\7f20866
-Node: push-button\7f21157
-Node: editable-field\7f21730
-Node: text\7f23069
-Node: menu-choice\7f23367
-Node: radio-button-choice\7f24232
-Node: item\7f25811
-Node: choice-item\7f26199
-Node: toggle\7f26697
-Node: checkbox\7f27422
-Node: checklist\7f27728
-Node: editable-list\7f29172
-Node: group\7f30354
-Node: Sexp Types\7f30641
-Node: constants\7f30954
-Node: generic\7f32033
-Node: atoms\7f32566
-Node: composite\7f34513
-Node: Widget Properties\7f36979
-Node: Defining New Widgets\7f40042
-Node: Widget Browser\7f45342
-Node: Widget Minor Mode\7f46200
-Node: Utilities\7f46757
-Node: Widget Wishlist\7f47238
+Node: Top\7f211
+Node: Introduction\7f591
+Node: User Interface\7f4075
+Node: Programming Example\7f8970
+Node: Setting Up the Buffer\7f13120
+Node: Basic Types\7f14837
+Node: link\7f20895
+Node: url-link\7f21409
+Node: info-link\7f21721
+Node: push-button\7f22012
+Node: editable-field\7f22585
+Node: text\7f24068
+Node: menu-choice\7f24366
+Node: radio-button-choice\7f25219
+Node: item\7f26786
+Node: choice-item\7f27174
+Node: toggle\7f27672
+Node: checkbox\7f28409
+Node: checklist\7f28715
+Node: editable-list\7f30159
+Node: group\7f31341
+Node: Sexp Types\7f31628
+Node: constants\7f31941
+Node: generic\7f33020
+Node: atoms\7f33553
+Node: composite\7f35500
+Node: Widget Properties\7f37970
+Node: Defining New Widgets\7f41035
+Node: Widget Browser\7f46335
+Node: Widget Minor Mode\7f47193
+Node: Utilities\7f47750
+Node: Widget Wishlist\7f48231
\1f
End Tag Table
projects / chise / xemacs-chise.git- / blobdiff