/[emacs]/emacs/lispref/customize.texi
ViewVC logotype

Diff of /emacs/lispref/customize.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.39 by rms, Thu Jun 24 20:17:34 2004 UTC revision 1.40 by rms, Thu Nov 25 03:09:43 2004 UTC
# Line 300  those other variables already have their Line 300  those other variables already have their
300  operation of a certain feature.  Assuming that the package is coded to  operation of a certain feature.  Assuming that the package is coded to
301  check the value of the option, you still need to arrange for the package  check the value of the option, you still need to arrange for the package
302  to be loaded.  You can do that with @code{:require}.  @xref{Common  to be loaded.  You can do that with @code{:require}.  @xref{Common
303  Keywords}.  Here is an example, from the library @file{paren.el}:  Keywords}.  Here is an example, from the library @file{tooltip.el}:
304    
305  @example  @example
306  (defcustom show-paren-mode nil  (defcustom tooltip-mode nil
307    "Toggle Show Paren mode..."    "Non-nil if Tooltip mode is enabled..."
308    :set (lambda (symbol value)    :set (lambda (symbol value)
309           (show-paren-mode (or value 0)))           (tooltip-mode (or value 0)))
310    :initialize 'custom-initialize-default    :initialize 'custom-initialize-default
311    :type 'boolean    :type 'boolean
312    :group 'paren-showing    :require 'tooltip
313    :require 'paren)    :group 'tooltip)
314  @end example  @end example
315    
316  If a customization item has a type such as @code{hook} or @code{alist},  If a customization item has a type such as @code{hook} or @code{alist},
# Line 529  value. Line 529  value.
529  The @code{group} widget is used here instead of @code{list} only because  The @code{group} widget is used here instead of @code{list} only because
530  the formatting is better suited for the purpose.  the formatting is better suited for the purpose.
531    
532  Similarily, you can have alists with more values associated with each  Similarly, you can have alists with more values associated with each
533  key, using variations of this trick:  key, using variations of this trick:
534    
535  @smallexample  @smallexample
# Line 538  key, using variations of this trick: Line 538  key, using variations of this trick:
538                           ("ken"    52 t))                           ("ken"    52 t))
539    "Alist of basic info about people.    "Alist of basic info about people.
540  Each element has the form (NAME AGE MALE-FLAG)."  Each element has the form (NAME AGE MALE-FLAG)."
541    :type '(alist :value-type (group age boolean)))    :type '(alist :value-type (group integer boolean)))
542    
543  (defcustom pets '(("brian")  (defcustom pets '(("brian")
544                    ("dorith" "dog" "guppy")                    ("dorith" "dog" "guppy")
# Line 665  verbatim, you might write the customizat Line 665  verbatim, you might write the customizat
665  @end example  @end example
666    
667  @noindent  @noindent
668  so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.  so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
669    
670  In any alternative for which @code{nil} is not a valid value, other than  In any alternative for which @code{nil} is not a valid value, other than
671  a @code{const}, you should specify a valid default for that alternative  a @code{const}, you should specify a valid default for that alternative
# Line 824  purposes.  This is useful for a type tha Line 824  purposes.  This is useful for a type tha
824  Use @var{criteria} to match possible values.  This is used only in  Use @var{criteria} to match possible values.  This is used only in
825  @code{restricted-sexp}.  @code{restricted-sexp}.
826    
827  @item :args @var{argumentlist}  @item :args @var{argument-list}
828  Use the elements of @var{argumentlist} as the arguments of the type  Use the elements of @var{argument-list} as the arguments of the type
829  construct.  For instance, @code{(const :args (foo))} is equivalent to  construct.  For instance, @code{(const :args (foo))} is equivalent to
830  @code{(const foo)}.  You rarely need to write @code{:args} explicitly,  @code{(const foo)}.  You rarely need to write @code{:args} explicitly,
831  because normally the arguments are recognized automatically as  because normally the arguments are recognized automatically as
# Line 1066  arguments, which will be used when creat Line 1066  arguments, which will be used when creat
1066  @subsection Defining New Types  @subsection Defining New Types
1067    
1068  In the previous sections we have described how to construct elaborate  In the previous sections we have described how to construct elaborate
1069  type specifications for @code{defcustom}.  In some cases you may want to  type specifications for @code{defcustom}.  In some cases you may want
1070  give such a type specification a name.  The obvious case is when you are  to give such a type specification a name.  The obvious case is when
1071  using the same type for many user options, rather than repeat the  you are using the same type for many user options: rather than repeat
1072  specification for each option, you can give the type specification a  the specification for each option, you can give the type specification
1073  name once, and use that name each @code{defcustom}.  The other case is  a name, and use that name each @code{defcustom}.  The other case is
1074  when a user option accept a recursive datastructure.  To make it  when a user option's value is a recursive data structure.  To make it
1075  possible for a datatype to refer to itself, it needs to have a name.  possible for a datatype to refer to itself, it needs to have a name.
1076    
1077  Since custom types are implemented as widgets, the way to define a new  Since custom types are implemented as widgets, the way to define a new
# Line 1097  types by a simple example. Line 1097  types by a simple example.
1097    :type 'binary-tree-of-string)    :type 'binary-tree-of-string)
1098  @end example  @end example
1099    
1100  The function to define a new widget is name @code{define-widget}.  The  The function to define a new widget is called @code{define-widget}.  The
1101  first argument is the symbol we want to make a new widget type.  The  first argument is the symbol we want to make a new widget type.  The
1102  second argument is a symbol representing an existing widget, the new  second argument is a symbol representing an existing widget, the new
1103  widget is going to be defined in terms of difference from the existing  widget is going to be defined in terms of difference from the existing
1104  widget.  For the purpose of defining new customization types, the  widget.  For the purpose of defining new customization types, the
1105  @code{lazy} widget is perfect, because it accept a @code{:type} keyword  @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1106  argument with the same syntax as the keyword argument to  argument with the same syntax as the keyword argument to
1107  @code{defcustom} with the same name.  The third argument is a  @code{defcustom} with the same name.  The third argument is a
1108  documentation string for the new widget.  You will be able to see that  documentation string for the new widget.  You will be able to see that
1109  string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string  string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
1110  @key{ret}} command.  @key{ret}} command.
1111    
1112  After these mandatory arguments follows the keyword arguments.  The most  After these mandatory arguments follow the keyword arguments.  The most
1113  important is @code{:type}, which describes the datatype we want to match  important is @code{:type}, which describes the data type we want to match
1114  with this widget.  Here a @code{binary-tree-of-string} is described as  with this widget.  Here a @code{binary-tree-of-string} is described as
1115  being either a string, or a cons-cell whose car and cdr are themselves  being either a string, or a cons-cell whose car and cdr are themselves
1116  both @code{binary-tree-of-string}.  Note the reference to the widget  both @code{binary-tree-of-string}.  Note the reference to the widget
1117  type we are currently in the process of defining.  The @code{:tag}  type we are currently in the process of defining.  The @code{:tag}
1118  attribute is a string to name the widget in the user interface, and the  attribute is a string to name the widget in the user interface, and the
1119  @code{:offset} argument are there to ensure that child nodes are  @code{:offset} argument is there to ensure that child nodes are
1120  indented four spaces relatively to the parent node, making the tree  indented four spaces relative to the parent node, making the tree
1121  structure apparent in the customization buffer.  structure apparent in the customization buffer.
1122    
1123  The @code{defcustom} shows how the new widget can be used as an ordinary  The @code{defcustom} shows how the new widget can be used as an ordinary
1124  customization type.  customization type.
1125    
1126  If you wonder about the name @code{lazy}, know that the other composite  The reason for the name @code{lazy} is that the other composite
1127  widgets convert their inferior widgets to internal form when the widget  widgets convert their inferior widgets to internal form when the
1128  is instantiated in a buffer.  This conversion is recursive, so the  widget is instantiated in a buffer.  This conversion is recursive, so
1129  inferior widgets will convert @emph{their} inferior widgets.  If the  the inferior widgets will convert @emph{their} inferior widgets.  If
1130  datastructure is itself recursive, this conversion will go on forever,  the data structure is itself recursive, this conversion is an infinite
1131  or at least until Emacs run out of stack space.  The @code{lazy} widget  recursion.  The @code{lazy} widget prevents the recursion: it convert
1132  stop this recursion, it will only convert its @code{:type} argument when  its @code{:type} argument only when needed.
 needed.  
1133    
1134  @ignore  @ignore
1135     arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2     arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2

Legend:
Removed from v.1.39  
changed lines
  Added in v.1.40

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26