@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@top The Emacs Widget Library
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@top The Emacs Widget Library
A simple constant widget intended to be used in the @code{menu-choice} and
@code{radio-button-choice} widgets.
@item choice-item
A simple constant widget intended to be used in the @code{menu-choice} and
@code{radio-button-choice} widgets.
@item choice-item
@item
You can give the user immediate feedback if he enters invalid data in a
text field, and sometimes prevent entering invalid data.
@item
You can give the user immediate feedback if he enters invalid data in a
text field, and sometimes prevent entering invalid data.
@comment node-name, next, previous, up
@section User Interface
@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:
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.
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.
The list is created by the @code{editable-list} widget.
@item Embedded Buttons.
The @samp{@b{_other work_}} is an example of an embedded
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
(make-local-variable 'widget-example-repeat)
(widget-insert "Here is some documentation.\n\nName: ")
(widget-create 'editable-field
- :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 " for more information.\n\nNumbers: count to three below\n")
(setq widget-example-repeat
(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
(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
- :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."))
- :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")
property, @var{argument} is the value of the property, and @var{args}
are interpreted in a widget specific way.
property, @var{argument} is the value of the property, and @var{args}
are interpreted in a widget specific way.
-A function which takes a widget as an argument, and return nil if the
-widgets current value is valid for the widget. Otherwise, it should
-return the widget containing the invalid data, and set that widgets
+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.
The following predefined function can be used:
@code{:error} property to a string explaining the error.
The following predefined function can be used:
@var{address}.
@node push-button, editable-field, info-link, Basic Types
@var{address}.
@node push-button, editable-field, info-link, Basic Types
-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 :keymap
Keymap used in the editable field. The default value is
@code{widget-field-keymap}, which allows you to use all the normal
@item :keymap
Keymap used in the editable field. The default value is
@code{widget-field-keymap}, which allows you to use all the normal
-The @var{type} arguments represents each possible choice. The widgets
-value of will be the value of the chosen @var{type} argument. This
-widget will match any value that matches at least one of the specified
-@var{type} arguments.
+The @var{type} argument represents each possible choice. The widget's
+value will be that of the chosen @var{type} argument. This widget will
+match any value matching at least one of the specified @var{type}
+arguments.
-The @var{type} arguments represents each possible choice. The widgets
-value of will be the value of the chosen @var{type} argument. This
-widget will match any value that matches at least one of the specified
-@var{type} arguments.
+The @var{type} argument represents each possible choice. The widget's
+value will be that of the chosen @var{type} argument. This widget will
+match any value matching at least one of the specified @var{type}
+arguments.
-The widget has two possible states, `on' and `off', which corresponds to
-a @code{t} or @code{nil} value.
+The widget has two possible states, `on' and `off', which correspond to
+a @code{t} or @code{nil} value respectively.
-The @var{type} arguments represents each checklist item. The widgets
-value of will be a list containing the value of each ticked @var{type}
-argument. The checklist widget will match a list whose elements all
-matches at least one of the specified @var{type} arguments.
+The @var{type} arguments represents each checklist item. The widget's
+value will be a list containing the values of all ticked @var{type}
+arguments. The checklist widget will match a list whose elements all
+match at least one of the specified @var{type} arguments.
-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.
@comment node-name, next, previous, up
@subsection The @code{group} Widget
@comment node-name, next, previous, up
@subsection The @code{group} Widget
@subsection The Constant Widgets.
The @code{const} widget can contain any lisp expression, but the user is
@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.
@samp{(file t)} or @code{(file string string)}.
This concept of inline is probably hard to understand. It was certainly
@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 confuse you more by trying to explain it
-here, I'll just suggest you meditate over it for a while.
+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.
-Allows you to edit a sexp which may have one of fixed set of types. It
-is currently implemented with the @code{choice-menu} basic widget, and
-has a similar syntax.
+Allows you to edit a sexp which may have one of a fixed set of types.
+It is currently implemented with the @code{choice-menu} basic widget,
+and has a similar syntax.
-of @code{:inactive} keyword. If this is non-nil, the widget itself has
-been deactivated. This is different from using the @code{:active}
-keyword, in that the later tell you if the widget @strong{or} any of its
-ancestors have been deactivated. Do not attempt to set the
+of the @code{:inactive} keyword. If this is non-nil, the widget itself
+has been deactivated. This is different from using the @code{:active}
+keyword, in that the latter tells you if the widget @strong{or} any of
+its ancestors have been deactivated. Do not attempt to set the
@node Defining New Widgets, Widget Browser, Widget Properties, Top
@node Defining New Widgets, Widget Browser, Widget Properties, Top
@section Defining New Widgets
You can define specialized widgets with @code{define-widget}. It allows
@section Defining New Widgets
You can define specialized widgets with @code{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
-arguments.
+you to create a shorthand for more complex widgets. This includes
+specifying component widgets and 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}.
@defun widget-define name class doc &rest args
Define a new widget type named @var{name} from @code{class}.
-Using @code{widget-define} does just store the definition of the widget
-type in the @code{widget-type} property of @var{name}, which is what
+Using @code{widget-define} just stores the definition of the widget type
+in the @code{widget-type} property of @var{name}, which is what
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
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
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}.
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}.
-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.
-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.
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
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
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
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, which will handle the @samp{%h} and any future
-escape sequences, as well as give an error for unknown escapes.
+unknown escape sequences. It will handle the @samp{%h} and any future
+escape sequences as well as give an error for unknown escapes.
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
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