From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Per Abrahamsen Newsgroups: gmane.emacs.devel Subject: Re: Creating recursive customization types / widgets Date: Wed, 03 Dec 2003 16:26:30 +0100 Organization: The Church of Emacs Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1070465566 9522 80.91.224.253 (3 Dec 2003 15:32:46 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 3 Dec 2003 15:32:46 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed Dec 03 16:32:43 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1ARYza-0001gF-00 for ; Wed, 03 Dec 2003 16:32:42 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1ARYza-00017S-00 for ; Wed, 03 Dec 2003 16:32:42 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1ARZwn-00059X-PV for emacs-devel@quimby.gnus.org; Wed, 03 Dec 2003 11:33:53 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1ARZv5-0004h4-C0 for emacs-devel@gnu.org; Wed, 03 Dec 2003 11:32:07 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1ARZuZ-0004db-0r for emacs-devel@gnu.org; Wed, 03 Dec 2003 11:32:05 -0500 Original-Received: from [130.225.40.227] (helo=sheridan.dina.kvl.dk) by monty-python.gnu.org with esmtp (Exim 4.24) id 1ARZr3-0003sD-Lw; Wed, 03 Dec 2003 11:27:57 -0500 Original-Received: by sheridan.dina.kvl.dk (Postfix, from userid 304) id 155A313CFC; Wed, 3 Dec 2003 16:26:30 +0100 (CET) Original-To: rms@gnu.org X-Face: +kRV2]2q}lixHkE{U)mY#+6]{AH=yN~S9@IFiOa@X6?GM|8MBp/ In-Reply-To: (Richard Stallman's message of "Tue, 02 Dec 2003 23:46:12 -0500") User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3 (gnu/linux) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:18322 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:18322 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 * 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