\input texinfo.tex
-@c $Id: widget.texi,v 1.1 1997/01/25 22:46:31 steve Exp $
+@c $Id: widget.texi,v 1.87 1997/03/08 16:21:38 abraham Exp $
@c %**start of header
@setfilename widget
@comment node-name, next, previous, up
@top The Emacs Widget Library
-Version: 1.15
+Version: 1.59
@menu
* Introduction::
@item widget.el
This will declare the user variables, define the function
@code{widget-define}, and autoload the function @code{widget-create}.
-@item widget-edit.el
+@item wid-edit.el
Everything else is here, there is no reason to load it explicitly, as
it will be autoloaded when needed.
@end table
selected and the previous selected radio button will become unselected.
@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons.
These are explicit buttons made with the @code{push-button} widget. The main
-difference from the @code{link} widget is that the buttons are intended
-to be displayed more like buttons in a GUI, once Emacs grows powerful
+difference from the @code{link} widget is that the buttons are will be
+displayed as GUI buttons when possible.
enough.
@end table
(require 'widget)
(eval-when-compile
- (require 'widget-edit))
+ (require 'wid-edit))
(defvar widget-example-repeat)
There is a standard widget keymap which you might find useful.
@defvr Const widget-keymap
-A keymap with the global keymap as its parent.@br
+A keymap with the global keymap as its parent.@*
@key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
@code{widget-backward}, respectively. @kbd{@key{RET}} and @kbd{mouse-2}
are bound to @code{widget-button-press} and
@itemx %]
The text inside will be marked as a button.
+@item %@{
+@itemx %@}
+The text inside will be displayed with the face specified by
+@code{:sample-face}.
+
@item %v
This will be replaces with the buffer representation of the widgets
value. What this is depends on the widget type.
The string inserted by the @samp{%t} escape in the format
string.
+@item :tag-glyph
+Name of image to use instead of the string specified by `:tag' on
+Emacsen that supports it.
+
@item :help-echo
Message displayed whenever you move to the widget with either
@code{widget-forward} or @code{widget-backward}.
@item :parent
The parent of a nested widget (e.g. a @code{menu-choice} item or an element of a
@code{editable-list} widget).
+
+@item :sibling-args
+This keyword is only used for members of a @code{radio-button-choice} or
+@code{checklist}. The value should be a list of extra keyword
+arguments, which will be used when creating the @code{radio-button} or
+@code{checkbox} associated with this item.
+
@end table
+@deffn {User Option} widget-glyph-directory
+Directory where glyphs are found.
+Widget will look here for a file with the same name as specified for the
+image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension.
+@end deffn
+
+@deffn{User Option} widget-glyph-enable
+If non-nil, allow glyphs to appear on displayes where they are supported.
+@end deffn
+
+
@menu
* link::
* url-link::
@table @code
@item :size
-The width of the editable field.@br
+The width of the editable field.@*
By default the field will reach to the end of the line.
@item :value-face
Face used for highlighting the editable field. Default is
@code{widget-field-face}.
+@item :secret
+Character used to display the value. You can set this to e.g. @code{?*}
+if the field contains a password or other secret information. By
+default, the value is not secret.
+
+@item :valid-regexp
+By default the @code{:validate} function will match the content of the
+field with the value of this attribute. The default value is @code{""}
+which matches everything.
+
@item :keymap
-Keymap used in the editable field. @code{widget-keymap} will allow you
-to use normal editing commands, even if these has been suppressed in the
-current buffer.
+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 supress some of them.
+Pressing return activates the function specified by @code{:activate}.
@item :hide-front-space
@itemx :hide-rear-space
@subsection The @code{text} Widget
This is just like @code{editable-field}, but intended for multiline text
-fields.
+fields. The default @code{:keymap} is @code{widget-text-keymap}, which
+does not rebind the return key.
@node menu-choice, radio-button-choice, text, Basic Types
@comment node-name, next, previous, up
Insert a literal @samp{%}.
@end table
+@item button-args
+A list of keywords to pass to the radio buttons. Useful for setting
+e.g. the @samp{:help-echo} for each button.
+
@item :buttons
The widgets representing the radio buttons.
String representing the `on' state. By default the string @samp{on}.
@item :off
String representing the `off' state. By default the string @samp{off}.
-@item :on-type
-Type representing the `on' state. By default an `item' widget displaying
-the string specified with the @code{:on} keyword.
-@item :off-type
-Type representing the `off' state. By default an `item' widget
-displaying the string specified with the @code{:off} keyword.
+@item :on-glyph
+Name of a glyph to be used instead of the `:on' text string, on emacsen
+that supports it.
+@item :off-glyph
+Name of a glyph to be used instead of the `:off' text string, on emacsen
+that supports it.
@end table
@node checkbox, checklist, toggle, Basic Types
Insert a literal @samp{%}.
@end table
+@item button-args
+A list of keywords to pass to the checkboxes. Useful for setting
+e.g. the @samp{:help-echo} for each checkbox.
+
@item :buttons
The widgets representing the checkboxes.
Insert a literal @samp{%}.
@end table
+@item :insert-button-args
+A list of keyword arguments to pass to the insert buttons.
+
+@item :delete-button-args
+A list of keyword arguments to pass to the delete buttons.
+
+@item :append-button-args
+A list of keyword arguments to pass to the trailing insert button.
+
+
@item :buttons
The widgets representing the insert and delete buttons.
@comment node-name, next, previous, up
@section Properties
-You can examine or set this value by using the widget object that was
-returned by @code{widget-create}.
+You can examine or set the value of a widget by using the widget object
+that was returned by @code{widget-create}.
@defun widget-value widget
Return the current value contained in @var{widget}.
Non-nil if @var{widget} has a value (even nil) for property @var{property}.
@end defun
+Occasionally it can be useful to know which kind of widget you have,
+i.e. the name of the widget type you gave when the widget was created.
+
+@defun widget-type widget
+Return the name of @var{widget}, a symbol.
+@end defun
+
@node Defining New Widgets, Widget Wishlist., Widget Properties, Top
@comment node-name, next, previous, up
@section Defining New Widgets
@itemize @bullet
@item
-In general, we need @strong{much} better support for keyboard
-operations.
-
-@itemize -
-@item
It should be possible to add or remove items from a list with @kbd{C-k}
and @kbd{C-o} (suggested by @sc{rms}).
-@item
-@kbd{C-k} should kill to end of field or end of line, whatever come
-first.
-
-@item
-Commands to move to the beginning/end of a field.
-
-@end itemize
-
@item
The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
dash (@samp{-}). The dash should be a button that, when activated, ask
the ugly buttons, the dash is my idea).
@item
-Use graphical versions of the widgets for emacsen that can do that.
-I.e. real radio buttons and checkmarks instead of their @sc{ascii}
-equivalents.
-
-@item
-There should be support for browsing the widget documentation.
-
-@item
-There should be a way to specify that @key{RET} in a field will call the
-@code{:activate} function. This should be used by widgets such as
-@code{file} and @code{symbol} prompt with completion.
+Widgets such as @code{file} and @code{symbol} should prompt with completion.
@item
The @code{menu-choice} tag should be prettier, something like the abbreviated
@item
The functions used in many widgets, like
@code{widget-item-convert-widget}, should not have names that are
-specific to the first widget where I used them.
+specific to the first widget where I happended to use them.
@item
Unchecked items in a @code{radio-button-choice} or @code{checklist}
when inserting the grayed out subwidget, and let the widget-specify
functions check that variable.
+@item
+Flag to make @code{widget-move} skip a specified button.
+
+@item
+Document `helper' functions for defining new widgets.
+
+@item
+Activate the item this is below the mouse when the button is
+released, not the item this is below the mouse when the button is
+pressed. Dired and grep gets this right. Give feedback if possible.
+
+@item
+Use @samp{@@deffn Widget} to document widgets.
+
+@item
+Document global keywords in one place.
+
+Document keywords particular to a specific widget in the widget
+definition.
+
+Document the `default' widget first.
+
+Split, when needed, keywords into those useful for normal
+customization, those primarily useful when deriving, and those who
+represent runtime information.
+
+@item
+Figure out terminology and @sc{api} for the class/type/object/super
+stuff.
+
+Perhaps the correct model is delegation?
+
+@item
+Document @code{widget-browse}.
+
+@item
+Make indentation work with glyphs and propertional fonts.
+
+@item
+Add object and class hierarchies to the browser.
+
@end itemize
@contents
projects / gnus / blobdiff