comparison lispref/customize.texi @ 53319:36b31fc002f2

2003-12-12 Jesper Harder <[e-mail]> * cus-edit.el (custom-add-parent-links): Define "many". 2003-12-08 Per Abrahamsen <[e-mail]> * wid-edit.el (widget-child-value-get, widget-child-value-inline) (widget-child-validate, widget-type-value-create) (widget-type-default-get, widget-type-match): New functions. (lazy): New widget. (menu-choice, checklist, radio-button-choice, editable-list) (group, documentation-string): Removed redundant (per 2003-10-25 change) calls to `widget-children-value-delete'. (widget-choice-value-get, widget-choice-value-inline): Removed functions. (menu-choice): Updated widget.

53318:d7e333de59f9

@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 See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@chapter Writing Customization Definitions

@menu
* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::
@end menu

All customization types are implemented as widgets; see @ref{Top, ,
Introduction, widget, The Emacs Widget Library}, for details.

arguments, which will be used when creating the @code{radio-button} or
@code{checkbox} associated with this item.
@end ignore
@end table

@ignore
   arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
@end ignore

53319:36b31fc002f2

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@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
@chapter Writing Customization Definitions

@menu
* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::
* Defining New Types::
@end menu

All customization types are implemented as widgets; see @ref{Top, ,
Introduction, widget, The Emacs Widget Library}, for details.

arguments, which will be used when creating the @code{radio-button} or
@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