@ifinfo
@dircategory XEmacs Editor
@direntry
-* Widgets: (widget). The Emacs Widget Library.
+* Widgets: (widget). The Emacs Widget Library.
@end direntry
@end ifinfo
* Widget Minor Mode::
* Utilities::
* Widget Wishlist::
+* Widget Internals::
@end menu
@node Introduction, User Interface, Top, Top
A simple constant widget intended to be used in the @code{menu-choice} and
@code{radio-button-choice} widgets.
@item choice-item
-An 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
will be asked to select another option from the choice widget.
@item toggle
A simple @samp{on}/@samp{off} switch.
@enumerate
@item
-More complex field than just editable text are supported.
+More complex fields than just editable text are supported.
@item
You can give the user immediate feedback if he enters invalid data in a
text field, and sometimes prevent entering invalid data.
@table @file
@item widget.el
This will declare the user variables, define the function
-@code{widget-define}, and autoload the function @code{widget-create}.
+@code{define-widget}, and autoload the function @code{widget-create}.
@item wid-edit.el
Everything else is here, there is no reason to load it explicitly, as
it will be autoloaded when needed.
@comment node-name, next, previous, up
@section User Interface
-A form consist of read only text for documentation and some fields,
-where each the fields contain two parts, as tag and a value. The tags
-are used to identify the fields, so the documentation can refer to the
-foo field, meaning the field tagged with @samp{Foo}. Here is an example
-form:
+A form consists of read only text for documentation and some fields,
+where each of the fields contains two parts, a tag and a value. The
+tags are used to identify the fields, so the documentation can refer to
+the foo field, meaning the field tagged with @samp{Foo}. Here is an
+example form:
@example
Here is some documentation.
field. Option fields are created by the @code{menu-choice} widget. In
the example, @samp{@b{Choose}} is an option field tag.
@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons.
-Activating these will insert or delete elements from a editable list.
+Activating these will insert or delete elements from an editable list.
The list is created by the @code{editable-list} widget.
@item Embedded Buttons.
The @samp{@b{_other work_}} is an example of an embedded
(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
@end example
-Where, @var{name} is a widget name, @var{keyword} is the name of a
+where @var{name} is a widget name, @var{keyword} is the name of a
property, @var{argument} is the value of the property, and @var{args}
are interpreted in a widget specific way.
@end table
@item :doc
-The string inserted by the @samp{%d} escape in the format
+The string inserted by the @samp{%d} or @samp{%h} escape in the format
string.
@item :tag
The function is called with two or three arguments. The first argument
is the widget itself, the second argument is the widget that was
changed, and the third argument is the event leading to the change, if
-any.
+any. In editable fields, this includes all insertions, deletions,
+@emph{etc}. To watch only for ``final'' actions, redefine the
+@code{:action} callback.
@item :menu-tag
Tag used in the menu when the widget is used as an option in a
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
+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 widget's
@code{:error} property to a string explaining the error.
@item :parent
The parent of a nested widget (e.g. a @code{menu-choice} item or an
-element of a @code{editable-list} widget).
+element of an @code{editable-list} widget).
@item :sibling-args
This keyword is only used for members of a @code{radio-button-choice} or
@table @code
@item :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.
@item :value-face
Face used for highlighting the editable field. Default is
@item :keymap
Keymap used in the editable field. The default value is
@code{widget-field-keymap}, which allows you to use all the normal
-editing commands, even if the buffers major mode suppress some of them.
+editing commands, even if the buffer's major mode suppress some of them.
Pressing return invokes the function specified by @code{:action}.
@end table
@comment node-name, next, previous, up
@subsection The @code{group} Widget
-This widget simply group other widget together.
+This widget simply groups other widgets together.
Syntax:
@subsection The Constant Widgets.
The @code{const} widget can contain any lisp expression, but the user is
-prohibited from editing edit it, which is mainly useful as a component
-of one of the composite widgets.
+prohibited from editing it, which is mainly useful as a component of one
+of the composite widgets.
The syntax for the @code{const} widget is
specifying component widgets and new default values for the keyword
arguments.
-@defun widget-define name class doc &rest args
+@defun define-widget 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
@end defun
-Using @code{widget-define} just stores the definition of the widget type
+Using @code{define-widget} just stores the definition of the widget 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.
+conversions, you can use @code{identity} as your @code{:convert-widget}
+function.
The following additional keyword arguments are useful when defining new
widgets:
@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.
+Method to convert type-specific components of a widget type before
+instantiating a widget of that type. Not normally called from user
+code, it is invoked by @code{widget-convert}. Typical operations
+include converting types of child widgets to widget instances and
+converting values from external format (@emph{i.e.}, as expected by the
+calling code) to internal format (which is often different for the
+convenience of widget manipulation). It takes a widget type as an
+argument, and returns the converted widget type. When a widget is
+created, the value of this property is called for the widget type, then
+for all the widget's parent types, most derived first. (The property is
+reevaluated for each parent type.)
The following predefined functions can be used here:
@defun widget-types-convert-widget widget
-Convert @code{:args} as widget types in @var{widget}.
+Convert each member of @code{:args} in @var{widget} from a widget type
+to a widget.
@end defun
@defun widget-value-convert-widget widget
-Initialize @code{:value} from @code{:args} in @var{widget}.
+Initialize @code{:value} from @code{(car :args)} in @var{widget}, and
+reset @code{:args}.
@end defun
+@item :copy
+A method to implement deep copying of the type. Any member of the
+widget which might be changed in place (rather than replaced) should be
+copied by this method. (@code{widget-copy} uses @code{copy-sequence} to
+ensure that the top-level list is a copy.) This particularly applies to
+child widgets.
+
@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
@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
-in the buffer, and returns a widget object.
+argument, a widget, and inserts it in the buffer. Not normally called
+from user code. Instead, call @code{widget-create} or related
+functions, which take a type argument, (usually) convert it to a widget,
+call the @code{:create} function to insert it in the buffer, and then
+return the (possibly converted) widget.
+
+The default, @code{widget-default-create}, is invariably appropriate.
+(None of the standard widgets specify @code{:create}.)
@item :delete
Function to delete a widget. The function takes one argument, a widget,
@item :action
Function to handle user initiated events. By default, @code{:notify}
-the parent.
+the parent. Actions normally do not include mere edits, but refer to
+things like invoking buttons or hitting enter in an editable field. To
+watch for any change, redefine the @code{:notify} callback.
The following predefined function can be used here:
default'' in this text.
@end deffn
+In implementing complex hierarchical widgets (@emph{e.g.}, using the
+@samp{group} widget), the following functions may be useful.
+The syntax for the @var{type} arguments to these functions is described
+in @ref{Basic Types}.
+
+@defun widget-create-child-and-convert parent type &rest args
+As a child of @var{parent}, create a widget with type @var{type} and
+value @var{value}. @var{type} is copied, and the @code{:widget-contvert}
+method is applied to the optional keyword arguments from @var{args}.
+@end defun
+
+@defun widget-create-child parent type
+As a child of @var{parent}, create a widget with type @var{type}.
+@var{type} is copied, but no conversion method is applied.
+@end defun
+
+@defun widget-create-child-value parent type value
+As a child of @var{parent}, create a widget with type @var{type} and
+value @var{value}. @var{type} is copied, but no conversion method is
+applied.
+@end defun
+
+@defun widget-convert type &rest args
+Convert @var{type} to a widget without inserting it in the buffer.
+The optional @var{args} are additional keyword arguments.
+
+The widget's @code{:args} property is set from the longest tail of
+@var{args} whose @samp{cdr} is not a keyword, or if that is null, from
+the longest tail of @var{type}'s @code{:args} property whose cdr is not
+a keyword. Keyword arguments from @var{args} are set, and the
+@code{:value} property (if any) is converted from external to internal
+format.
+@end defun
+
+@code{widget-convert} is typically not called from user code; rather it
+is called implicitly through the @samp{widget-create*} functions.
+
@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
@comment node-name, next, previous, up
@section Widget Browser
This is only meaningful for radio buttons or checkboxes in a list.
@end defun
-@node Widget Wishlist, , Utilities, Top
+@node Widget Wishlist, Widget Internals, Utilities, Top
@comment node-name, next, previous, up
@section Wishlist
the field, not the end of the field itself.
@item
-Use and overlay instead of markers to delimit the widget. Create
+Use an overlay instead of markers to delimit the widget. Create
accessors for the end points.
@item
@end itemize
+@node Widget Internals, , Widget Wishlist, Top
+@section Internals
+
+This (very brief!) section provides a few notes on the internal
+structure and implementation of Emacs widgets. Avoid relying on this
+information. (We intend to improve it, but this will take some time.)
+To the extent that it actually describes APIs, the information will be
+moved to appropriate sections of the manual in due course.
+
+@subsection The @dfn{Widget} and @dfn{Type} Structures
+
+Widgets and types are currently both implemented as lists.
+
+A symbol may be defined as a @dfn{type name} using @code{define-widget}.
+@xref{Defining New Widgets}. A @dfn{type} is a list whose car is a
+previously defined type name, nil, or (recursively) a type. The car is
+the @dfn{class} or parent type of the type, and properties which are not
+specified in the new type will be inherited from ancestors. Probably
+the only type without a class should be the @code{default} type. The
+cdr of a type is a plist whose keys are widget property keywords.
+
+A type or type name may also be referred to as an @dfn{unconverted
+widget}.
+
+A @dfn{converted widget} or @dfn{widget instance} is a list whose car is
+a type name or a type, and whose cdr is a property list. Furthermore,
+all children of the converted widget must be converted. Finally, in the
+process of appropriate parts of the list structure are copied to ensure
+that changes in values of one instance do not affect another's.
+
@contents
@bye
projects / chise / xemacs-chise.git.1 / blobdiff