@c %**end of header
@copying
-Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2002, 2003 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
meaning. The user is not supposed to change or delete any of the text
between the fields. Examples of forms in Emacs are the @file{forms}
package (of course), the customize buffers, the mail and news compose
-modes, and the @sc{html} form support in the @file{w3} browser.
+modes, and the @acronym{HTML} form support in the @file{w3} browser.
@cindex widget library, why use it
The advantages for a programmer of using the @code{widget} package to
For example, capitalizing all text from the middle of one field to the
middle of another field is prohibited.
-Editing text fields are created by the @code{editable-field} widget.
+Editable text fields are created by the @code{editable-field} widget.
+
+An editable field must be surrounded by static text on both sides, that
+is, text that does not change in the lifetime of the widget. If the
+field extends to the end of the line, the terminating line-feed character
+will count as the necessary static text on that end, but you will have
+to provide the static text before the field yourself. The
+@code{:format} keyword is useful for generating the static text; for
+instance, if you give it a value of @code{"Name: %v"}, the "Name: " part
+will count as the static text.
The editing text fields are highlighted with the
@code{widget-field-face} face, making them easy to find.
Specifies how to display a message whenever you move to the widget with
either @code{widget-forward} or @code{widget-backward} or move the mouse
over it (using the standard @code{help-echo} mechanism). The argument
-is either a string to display or a function of one argument, the widget,
-which should return a string to display.
+is either a string to display, a function of one argument, the widget,
+which should return a string to display, or a form that evaluates to
+such a string.
@vindex indent@r{ keyword}
@item :indent
@end example
@findex browse-url-browser-function@r{, and @code{url-link} widget}
-When this link is invoked, the @sc{www} browser specified by
+When this link is invoked, the @acronym{WWW} browser specified by
@code{browse-url-browser-function} will be called with @var{url}.
@node info-link, push-button, url-link, Basic Types
Function to delete a widget. The function takes one argument, a widget,
and should remove all traces of the widget from the buffer.
+The default value is:
+
+@defun widget-default-delete widget
+Remove @var{widget} from the buffer.
+Delete all @code{:children} and @code{:buttons} in @var{widget}.
+@end defun
+
+In most cases you should not change this value, but instead use
+@code{:value-delete} to make any additional cleanup.
+
@vindex value-create@r{ keyword}
@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
representation of the widget's value in the buffer.
+Nested widgets should be listed in @code{:children} or @code{:buttons}
+to make sure they are automatically deleted.
+
@vindex value-delete@r{ keyword}
@item :value-delete
Should remove the representation of the widget's 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.
-
-The following predefined function can be used here:
-
-@defun widget-children-value-delete widget
-Delete all @code{:children} and @code{:buttons} in @var{widget}.
-@end defun
+if these are not listed in @code{:children} or @code{:buttons}.
@vindex value-get@r{ keyword}
@item :value-get
@setchapternewpage odd
@contents
@bye
+
+@ignore
+ arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
+@end ignore
HCoop / bpt / emacs.git / blobdiff