@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
in the customization buffer with the Info node name.
@item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the @sc{url}.
+Link to a web page; @var{url} is a string which specifies the @acronym{URL}.
The link appears in the customization buffer as @var{url}.
@item (emacs-commentary-link @var{library})
* Composite Types::
* Splicing into Lists::
* Type Keywords::
+* Defining New Types::
@end menu
All customization types are implemented as widgets; see @ref{Top, ,
@item color
The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}. A sample is provided,
+@kbd{M-@key{TAB}}. A sample is provided.
@end table
@node Composite Types
@code{widget-backward}, it will display the string @var{motion-doc} in
the echo area. In addition, @var{motion-doc} is used as the mouse
@code{help-echo} string and may actually be a function or form evaluated
-to yield a help string as for @code{help-echo} text properties.
+to yield a help string. If it is a function, it is called with one
+argument, the widget.
@c @xref{Text help-echo}.
@item :match @var{function}
@code{checkbox} associated with this item.
@end ignore
@end table
+
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}. In some cases you may want to
+give such a type specification a name. The obvious case is when you are
+using the same type for many user options, rather than repeat the
+specification for each option, you can give the type specification a
+name once, and use that name each @code{defcustom}. The other case is
+when a user option accept a recursive datastructure. To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget. We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that. Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+ "A binary tree made of cons-cells and strings."
+ :offset 4
+ :tag "Node"
+ :type '(choice (string :tag "Leaf" :value "")
+ (cons :tag "Interior"
+ :value ("" . "")
+ binary-tree-of-string
+ binary-tree-of-string)))
+
+(defcustom foo-bar ""
+ "Sample variable holding a binary tree of strings."
+ :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is name @code{define-widget}. The
+first argument is the symbol we want to make a new widget type. The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget. For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accept a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name. The third argument is a
+documentation string for the new widget. You will be able to see that
+string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
+@key{ret}} command.
+
+After these mandatory arguments follows the keyword arguments. The most
+important is @code{:type}, which describes the datatype we want to match
+with this widget. Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}. Note the reference to the widget
+type we are currently in the process of defining. The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument are there to ensure that child nodes are
+indented four spaces relatively to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type.
+
+If you wonder about the name @code{lazy}, know that the other composite
+widgets convert their inferior widgets to internal form when the widget
+is instantiated in a buffer. This conversion is recursive, so the
+inferior widgets will convert @emph{their} inferior widgets. If the
+datastructure is itself recursive, this conversion will go on forever,
+or at least until Emacs run out of stack space. The @code{lazy} widget
+stop this recursion, it will only convert its @code{:type} argument when
+needed.
+
+@ignore
+ arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore