\input texinfo.tex
-@c $Id: widget.texi,v 1.2 1996/10/30 19:27:41 steve Exp $
+@c $Id: widget.texi,v 1.4 1997/02/16 21:58:10 steve Exp $
@c %**start of header
@setfilename widget
@comment node-name, next, previous, up
@top The Emacs Widget Library
-Version: 0.995
+Version: 1.34
@menu
* Introduction::
The editing text fields are highlighted with the
@code{widget-field-face} face, making them easy to find.
-@defopt widget-field-face
+@deffn Face widget-field-face
Face used for other editing fields.
-@end defopt
+@end deffn
@subsection Buttons
To make them easier to locate, buttons are emphasized in the buffer.
-@defopt widget-button-face
+@deffn Face widget-button-face
Face used for buttons.
-@end defopt
+@end deffn
@defopt widget-mouse-face
Face used for buttons when the mouse pointer is above it.
@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}.
@code{editable-list} widget).
@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::
-* push-button::
-* editable-field::
+* url-link::
+* info-link::
+* push-button::
+* editable-field::
* text::
-* menu-choice::
-* radio-button-choice::
+* menu-choice::
+* radio-button-choice::
* item::
* choice-item::
* toggle::
* checkbox::
* checklist::
-* editable-list::
+* editable-list::
@end menu
-@node link, push-button, Basic Types, Basic Types
+@node link, url-link, Basic Types, Basic Types
@comment node-name, next, previous, up
@subsection The @code{link} Widget
property. The value should be a string, which will be inserted in the
buffer.
-@node push-button, editable-field, link, Basic Types
+@node url-link, info-link, link, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{url-link} Widget
+
+Syntax:
+
+@example
+TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
+@end example
+
+When this link is activated, the @sc{www} browser specified by
+@code{browse-url-browser-function} will be called with @var{url}.
+
+@node info-link, push-button, url-link, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{info-link} Widget
+
+Syntax:
+
+@example
+TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
+@end example
+
+When this link is activated, the build-in info browser is started on
+@var{address}.
+
+@node push-button, editable-field, info-link, Basic Types
@comment node-name, next, previous, up
@subsection The @code{push-button} Widget
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
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
@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.
+
+@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
+Add object and class hierarchies to the browser.
+
@end itemize
@contents
projects / gnus / blobdiff