From: Per Abrahamsen <abraham@dina.kvl.dk>
Cc: emacs-devel@gnu.org
Subject: Re: Creating recursive customization types / widgets
Date: Wed, 03 Dec 2003 16:26:30 +0100 [thread overview]
Message-ID: <rjhe0hapnd.fsf@sheridan.dina.kvl.dk> (raw)
In-Reply-To: <E1AROtw-00013j-KM@fencepost.gnu.org> (Richard Stallman's message of "Tue, 02 Dec 2003 23:46:12 -0500")
Here is documentation patch describing the use of the new widget. Is
it ok to commit that, and the lazy widget code itself, to CVS?
2003-12-03 Per Abrahamsen <abraham@dina.kvl.dk>
* customize.texi (Defining New Types): Document use of the
`lazy' widget.
*** customize.texi.~1.36.~ 2003-11-30 14:59:10.000000000 +0100
--- customize.texi 2003-12-03 16:18:56.000000000 +0100
***************
*** 1,6 ****
@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
--- 1,6 ----
@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
***************
*** 373,378 ****
--- 373,379 ----
* Composite Types::
* Splicing into Lists::
* Type Keywords::
+ * Defining New Types::
@end menu
All customization types are implemented as widgets; see @ref{Top, ,
***************
*** 1056,1061 ****
--- 1057,1123 ----
@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.
+
@ignore
arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
@end ignore
next prev parent reply other threads:[~2003-12-03 15:26 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-11-29 16:38 Creating recursive customization types / widgets Per Abrahamsen
2003-11-29 18:34 ` Per Abrahamsen
2003-11-30 20:05 ` Stefan Monnier
2003-12-01 11:36 ` Per Abrahamsen
2003-12-01 16:35 ` Thien-Thi Nguyen
2003-12-02 12:37 ` tapsellferrier.co.uk Host name lookup failure Robert J. Chassell
2003-12-01 17:08 ` Creating recursive customization types / widgets Per Abrahamsen
2003-12-02 0:31 ` Juri Linkov
2003-12-02 10:19 ` Per Abrahamsen
2003-12-02 12:46 ` David Kastrup
2003-12-02 13:34 ` Per Abrahamsen
2003-12-02 10:40 ` Per Abrahamsen
2003-12-01 13:36 ` Per Abrahamsen
2003-12-01 16:10 ` Ted Zlatanov
2003-12-01 19:24 ` Per Abrahamsen
2003-12-01 1:45 ` Richard Stallman
2003-12-01 13:27 ` Per Abrahamsen
2003-12-02 4:17 ` Richard Stallman
2003-12-02 10:31 ` Per Abrahamsen
2003-12-03 4:46 ` Richard Stallman
2003-12-03 12:30 ` Per Abrahamsen
2003-12-03 15:26 ` Per Abrahamsen [this message]
2003-12-03 19:05 ` Kevin Rodgers
2003-12-02 11:24 ` David Kastrup
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=rjhe0hapnd.fsf@sheridan.dina.kvl.dk \
--to=abraham@dina.kvl.dk \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).