xemacs-beta: man/widget.texi comparison

comparison man/widget.texi @ 412:697ef44129c6 r21-2-14

Import from CVS: tag r21-2-14

author	cvs
date	Mon, 13 Aug 2007 11:20:41 +0200
parents	74fd4e045ea6
children	95016f13131a

comparison

equal deleted inserted replaced

-:12e008d41344
+:697ef44129c6
 \input texinfo.tex
 @c %**start of header
-@setfilename ../info/widget.info
+@setfilename ../info/widget
 @settitle The Emacs Widget Library
 @iftex
 @afourpaper
 @headings double
 @end iftex
 @c %**end of header
 @ifinfo
 @dircategory XEmacs Editor
 @direntry
-* Widgets: (widget).            The Emacs Widget Library.
+* Widgets: (widget).		The Emacs Widget Library.
 @end direntry
 @end ifinfo
 @node Top, Introduction, (dir), (dir)
 @comment  node-name,  next,  previous,  up
 (switch-to-buffer (get-buffer-create "*Widget Example*"))
 (kill-all-local-variables)
 (make-local-variable 'widget-example-repeat)
 (widget-insert "Here is some documentation.\n\nName: ")
 (widget-create 'editable-field
-:size 13
+		 :size 13
-"My Name")
+		 "My Name")
 (widget-create 'menu-choice
-:tag "Choose"
+		 :tag "Choose"
-:value "This"
+		 :value "This"
-:help-echo "Choose me, please!"
+		 :help-echo "Choose me, please!"
-:notify (lambda (widget &rest ignore)
+		 :notify (lambda (widget &rest ignore)
-(message "%s is a good choice!"
+			   (message "%s is a good choice!"
-(widget-value widget)))
+				    (widget-value widget)))
-'(item :tag "This option" :value "This")
+		 '(item :tag "This option" :value "This")
-'(choice-item "That option")
+		 '(choice-item "That option")
-'(editable-field :menu-tag "No option" "Thus 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)
+		 :notify (lambda (&rest ignore)
-(widget-value-set widget-example-repeat
+			   (widget-value-set widget-example-repeat
-'("En" "To" "Tre"))
+					     '("En" "To" "Tre"))
-(widget-setup))
+			   (widget-setup))
-"other work")
+		 "other work")
 (widget-insert " for more information.\n\nNumbers: count to three below\n")
 (setq widget-example-repeat
-(widget-create 'editable-list
+	(widget-create 'editable-list
-:entry-format "%i %d %v"
+		       :entry-format "%i %d %v"
-:notify (lambda (widget &rest ignore)
+		       :notify (lambda (widget &rest ignore)
-(let ((old (widget-get widget
+				 (let ((old (widget-get widget
-':example-length))
+							':example-length))
-(new (length (widget-value widget))))
+				       (new (length (widget-value widget))))
-(unless (eq old new)
+				   (unless (eq old new)
-(widget-put widget ':example-length new)
+				     (widget-put widget ':example-length new)
-(message "You can count to %d." new))))
+				     (message "You can count to %d." new))))
-:value '("One" "Eh, two?" "Five!")
+		       :value '("One" "Eh, two?" "Five!")
-'(editable-field :value "three")))
+		       '(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"))
+		 :notify (lambda (&rest ignore) (message "Tickle"))
-t)
+		 t)
 (widget-insert " Thus\n\nSelect one:\n\n")
 (widget-create 'radio-button-choice
-:value "One"
+		 :value "One"
-:notify (lambda (widget &rest ignore)
+		 :notify (lambda (widget &rest ignore)
-(message "You selected %s"
+			   (message "You selected %s"
-(widget-value widget)))
+				    (widget-value widget)))
-'(item "One") '(item "Another One.") '(item "A Final One."))
+		 '(item "One") '(item "Another One.") '(item "A Final One."))
 (widget-insert "\n")
 (widget-create 'push-button
-:notify (lambda (&rest ignore)
+		 :notify (lambda (&rest ignore)
-(if (= (length (widget-value widget-example-repeat))
+			   (if (= (length (widget-value widget-example-repeat))
-3)
+				  3)
-(message "Congratulation!")
+			       (message "Congratulation!")
-(error "Three was the count!")))
+			     (error "Three was the count!")))
-"Apply Form")
+		 "Apply Form")
 (widget-insert " ")
 (widget-create 'push-button
-:notify (lambda (&rest ignore)
+		 :notify (lambda (&rest ignore)
-(widget-example))
+			   (widget-example))
-"Reset Form")
+		 "Reset Form")
 (widget-insert "\n")
 (use-local-map widget-keymap)
 (widget-setup))
 @end lisp
 String to suffix buttons.
 @end defopt
 @item %@{
 @itemx %@}
-The text inside will be displayed in the face specified by
+The text inside will be displayed with the face specified by
 @code{:sample-face}.
 @item %v
-This will be replaced with the buffer representation of the widget's
+This will be replaces with the buffer representation of the widgets
 value.  What this is depends on the widget type.
 @item %d
 Insert the string specified by @code{:doc} here.
 Should be a function called with two arguments, the widget and a value,
 and returning non-nil if the widget can represent the specified value.
 @item :validate
 A function which takes a widget as an argument, and return nil if the
-widget's current value is valid for the widget.  Otherwise it should
+widgets current value is valid for the widget.  Otherwise, it should
-return the widget containing the invalid data, and set that widget's
+return the widget containing the invalid data, and set that widgets
 @code{:error} property to a string explaining the error.
 The following predefined function can be used:
 @defun widget-children-validate widget
 @example
 TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
 @end example
-The @var{type} argument represents each possible choice.  The widget's
+The @var{type} arguments represents each possible choice.  The widgets
-value will be that of the chosen @var{type} argument.  This widget will
+value of will be the value of the chosen @var{type} argument.  This
-match any value matching at least one of the specified @var{type}
+widget will match any value that matches at least one of the specified
-arguments.
+@var{type} arguments.
 @table @code
 @item :void
 Widget type used as a fallback when the value does not match any of the
 specified @var{type} arguments.
 @example
 TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]...  TYPE ... )
 @end example
-The @var{type} argument represents each possible choice.  The widget's
+The @var{type} arguments represents each possible choice.  The widgets
-value will be that of the chosen @var{type} argument.  This widget will
+value of will be the value of the chosen @var{type} argument.  This
-match any value matching at least one of the specified @var{type}
+widget will match any value that matches at least one of the specified
-arguments.
+@var{type} arguments.
 The following extra properties are recognized.
 @table @code
 @item :entry-format
 @example
 TYPE ::= (toggle [KEYWORD ARGUMENT]...)
 @end example
-The widget has two possible states, `on' and `off', which correspond to
+The widget has two possible states, `on' and `off', which corresponds to
-a @code{t} or @code{nil} value respectively.
+a @code{t} or @code{nil} value.
 The following extra properties are recognized.
 @table @code
 @item :on
 @example
 TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
 @end example
-The @var{type} arguments represents each checklist item.  The widget's
+The @var{type} arguments represents each checklist item.  The widgets
-value will be a list containing the values of all ticked @var{type}
+value of will be a list containing the value of each ticked @var{type}
-arguments.  The checklist widget will match a list whose elements all
+argument.  The checklist widget will match a list whose elements all
-match at least one of the specified @var{type} arguments.
+matches at least one of the specified @var{type} arguments.
 The following extra properties are recognized.
 @table @code
 @item :entry-format
 @item %%
 Insert a literal @samp{%}.
 @end table
 @item :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 @code{:greedy} to
-non-nil, it will allow the items to appear in any sequence.  However, if
+non-nil, it will allow the items to come in any sequence.  However, if
-you extract the values they will be in the sequence given in the
+you extract the value they will be in the sequence given in the
-checklist.  I.e. the original sequence is forgotten.
+checklist. I.e. the original sequence is forgotten.
 @item button-args
 A list of keywords to pass to the checkboxes.  Useful for setting
 e.g. the @samp{:help-echo} for each checkbox.
 The value of a widget of this type will either have the form
 @samp{(file t)} or @code{(file string string)}.
 This concept of inline is probably hard to understand.  It was certainly
-hard to implement so instead of confusing you more by trying to explain
+hard to implement so instead of confuse you more by trying to explain it
-it here, I'll just suggest you meditate over it for a while.
+here, I'll just suggest you meditate over it for a while.
 @deffn Widget choice
-Allows you to edit a sexp which may have one of a fixed set of types.
+Allows you to edit a sexp which may have one of fixed set of types.  It
-It is currently implemented with the @code{choice-menu} basic widget,
+is currently implemented with the @code{choice-menu} basic widget, and
-and has a similar syntax.
+has a similar syntax.
 @end deffn
 @deffn Widget set
 Allows you to specify a type which must be a list whose elements all
 belong to given set.  The elements of the list is not significant.  This
 ;; Make @var{widget} active.
 (widget-apply @var{widget} :activate)
 @end lisp
-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 @code{:parent} link) have been deactivated.  To make sure
-a widget is really active, you must therefore activate both itself and
+a widget is really active, you must therefore activate both itself, and
 all its ancestors.
 @lisp
 (while widget
 (widget-apply widget :activate)
 (setq widget (widget-get widget :parent)))
 @end lisp
 You can check if a widget has been made inactive by examining the value
-of the @code{:inactive} keyword.  If this is non-nil, the widget itself
+of @code{:inactive} keyword.  If this is non-nil, the widget itself has
-has been deactivated.  This is different from using the @code{:active}
+been deactivated.  This is different from using the @code{:active}
-keyword, in that the latter tells you if the widget @strong{or} any of
+keyword, in that the later tell you if the widget @strong{or} any of its
-its ancestors have been deactivated.  Do not attempt to set the
+ancestors have been deactivated.   Do not attempt to set the
 @code{:inactive} keyword directly.  Use the @code{:activate}
-@code{:deactivate} keywords instead.
+@code{:deactivated} keywords instead.
 @node Defining New Widgets, Widget Browser, Widget Properties, Top
 @comment  node-name,  next,  previous,  up
 @section Defining New Widgets
 You can define specialized widgets with @code{define-widget}.  It allows
-you to create a shorthand for more complex widgets.  This includes
+you to create a shorthand for more complex widgets, including specifying
-specifying component widgets and new default values for the keyword
+component widgets and default new default values for the keyword
 arguments.
 @defun widget-define name class doc &rest args
 Define a new widget type named @var{name} from @code{class}.
 @var{name} and class should both be symbols, @code{class} should be one
 of the existing widget types.
 The third argument @var{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:
 @itemize @bullet
 @item
 @lisp
 @end lisp
 @end itemize
 @end defun
-Using @code{widget-define} just stores the definition of the widget type
+Using @code{widget-define} does just store the definition of the widget
-in the @code{widget-type} property of @var{name}, which is what
+type in the @code{widget-type} property of @var{name}, which is what
 @code{widget-create} uses.
 If you just want to specify defaults for keywords with no complex
 conversions, you can use @code{identity} as your conversion function.
 @table @code
 @item :convert-widget
 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 widget's parent types, most derived first.
+widget type and all the widgets parent types, most derived first.
 The following predefined functions can be used here:
 @defun widget-types-convert-widget widget
 Convert @code{:args} as widget types in @var{widget}.
 Initialize @code{:value} from @code{:args} in @var{widget}.
 @end defun
 @item :value-to-internal
 Function to convert the value to the internal format.  The function
-takes two arguments, a widget and an external value.  It returns the
+takes two arguments, a widget and an external value, and returns the
 internal value.  The function is called on the present @code{:value}
 when the widget is created, and on any value set later with
 @code{widget-value-set}.
 @item :value-to-external
 when the widget is created, and on any value set later with
 @code{widget-value-set}.
 @item :create
 Function to create a widget from scratch.  The function takes one
-argument, a widget type, and creates a widget of that type, inserts it
+argument, a widget type, and create a widget of that type, insert it in
-in the buffer, and returns a widget object.
+the buffer, and return a widget object.
 @item :delete
 Function to delete a widget.  The function takes one argument, a widget,
 and should remove all traces of the widget from the buffer.
 @item :value-create
 Function to expand the @samp{%v} escape in the format string.  It will
-be called with the widget as its argument and should insert a
+be called with the widget as its argument.  Should
-representation of the widget's value in the buffer.
+insert a representation of the widgets value in the buffer.
 @item :value-delete
-Should remove the representation of the widget's value from the buffer.
+Should remove the representation of the widgets 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 have been used.
+if such has been used.
 The following predefined function can be used here:
 @defun widget-children-value-delete widget
 Delete all @code{:children} and @code{:buttons} in @var{widget}.
 Function to handle unknown @samp{%} escapes in the format string.  It
 will be called with the widget and the escape character as arguments.
 You can set this to allow your widget to handle non-standard escapes.
 You should end up calling @code{widget-default-format-handler} to handle
-unknown escape sequences.  It will handle the @samp{%h} and any future
+unknown escape sequences, which will handle the @samp{%h} and any future
-escape sequences as well as give an error for unknown escapes.
+escape sequences, as well as give an error for unknown escapes.
 @item :action
 Function to handle user initiated events.  By default, @code{:notify}
 the parent.
 @item :prompt-value
 Function to prompt for a value in the minibuffer.  The function should
 take four arguments, @var{widget}, @var{prompt}, @var{value}, and
 @var{unbound} and should return a value for widget entered by the user.
 @var{prompt} is the prompt to use.  @var{value} is the default value to
-use, unless @var{unbound} is non-nil.  In this case there is no default
+use, unless @var{unbound} is non-nil in which case there are no default
 value.  The function should read the value using the method most natural
-for this widget and does not have to check whether it matches.
+for this widget, and does not have to check that it matches.
 @end table
 If you want to define a new widget from scratch, use the @code{default}
 widget as its base.

Mercurial > hg > xemacs-beta

comparison man/widget.texi @ 412:697ef44129c6 r21-2-14