/[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.25 by rms, Mon Mar 25 00:43:10 2002 UTC revision 1.25.2.1 by miles, Fri Apr 4 06:20:41 2003 UTC
# Line 1  Line 1 
1  @c -*-texinfo-*-  @c -*-texinfo-*-
2  @c This is part of the GNU Emacs Lisp Reference Manual.  @c This is part of the GNU Emacs Lisp Reference Manual.
3  @c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.  @c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
4  @c See the file elisp.texi for copying conditions.  @c See the file elisp.texi for copying conditions.
5  @setfilename ../info/customize  @setfilename ../info/customize
6  @node Customization, Loading, Macros, Top  @node Customization, Loading, Macros, Top
# Line 13  definitions---as well as face definition Line 13  definitions---as well as face definition
13    
14  @menu  @menu
15  * Common Keywords::  * Common Keywords::
16  * Group Definitions::              * Group Definitions::
17  * Variable Definitions::          * Variable Definitions::
18  * Customization Types::  * Customization Types::
19  @end menu  @end menu
20    
# Line 242  as a Lisp variable).  The default for @v Line 242  as a Lisp variable).  The default for @v
242  @item :get @var{getfunction}  @item :get @var{getfunction}
243  Specify @var{getfunction} as the way to extract the value of this  Specify @var{getfunction} as the way to extract the value of this
244  option.  The function @var{getfunction} should take one argument, a  option.  The function @var{getfunction} should take one argument, a
245  symbol, and should return the ``current value'' for that symbol (which  symbol, and should return whatever customize should use as the
246  need not be the symbol's Lisp value).  The default is  ``current value'' for that symbol (which need not be the symbol's Lisp
247  @code{default-value}.  value).  The default is @code{default-value}.
248    
249    You have to really understand the workings of Custom to use
250    @code{:get} correctly.  It is meant for values that are treated in
251    Custom as variables but are not actually stored in Lisp variables.  It
252    is almost surely a mistake to specify @code{getfunction} for a value
253    that really is stored in a Lisp variable.
254    
255  @item :initialize @var{function}  @item :initialize @var{function}
256  @var{function} should be a function used to initialize the variable when  @var{function} should be a function used to initialize the variable when
# Line 255  this way: Line 261  this way:
261  @table @code  @table @code
262  @item custom-initialize-set  @item custom-initialize-set
263  Use the variable's @code{:set} function to initialize the variable, but  Use the variable's @code{:set} function to initialize the variable, but
264  do not reinitialize it if it is already non-void.  This is the default  do not reinitialize it if it is already non-void.
 @code{:initialize} function.  
265    
266  @item custom-initialize-default  @item custom-initialize-default
267  Like @code{custom-initialize-set}, but use the function  Like @code{custom-initialize-set}, but use the function
# Line 267  defining the variable will not call the Line 272  defining the variable will not call the
272  customizing the variable will do so.  customizing the variable will do so.
273    
274  @item custom-initialize-reset  @item custom-initialize-reset
275  Always use the @code{:set} function to initialize the variable.  If the  Always use the @code{:set} function to initialize the variable.  If
276  variable is already non-void, reset it by calling the @code{:set}  the variable is already non-void, reset it by calling the @code{:set}
277  function using the current value (returned by the @code{:get} method).  function using the current value (returned by the @code{:get} method).
278    This is the default @code{:initialize} function.
279    
280  @item custom-initialize-changed  @item custom-initialize-changed
281  Use the @code{:set} function to initialize the variable, if it is  Use the @code{:set} function to initialize the variable, if it is
# Line 338  which values are legitimate and (2) how Line 344  which values are legitimate and (2) how
344  customization buffer for editing.  customization buffer for editing.
345    
346    You specify the customization type in @code{defcustom} with the    You specify the customization type in @code{defcustom} with the
347  @code{:type} keyword.  The argument of @code{:type} is evaluated; since  @code{:type} keyword.  The argument of @code{:type} is evaluated, but
348  types that vary at run time are rarely useful, normally you use a quoted  only once when the @code{defcustom} is executed, so it isn't useful
349  constant.  For example:  for the value to vary.  Normally we use a quoted constant.  For
350    example:
351    
352  @example  @example
353  (defcustom diff-command "diff"  (defcustom diff-command "diff"
# Line 387  The value must be an integer, and is rep Line 394  The value must be an integer, and is rep
394  in the customization buffer.  in the customization buffer.
395    
396  @item number  @item number
397  The value must be a number, and is represented textually in the  The value must be a number (floating point or integer), and is
398  customization buffer.  represented textually in the customization buffer.
399    
400    @item float
401    The value must be a floating point number, and is represented
402    textually in the customization buffer.
403    
404  @item string  @item string
405  The value must be a string, and the customization buffer shows just the  The value must be a string, and the customization buffer shows just the
# Line 491  example, Line 502  example,
502  @end smallexample  @end smallexample
503    
504  @noindent  @noindent
505  instead of  instead of
506    
507  @smallexample  @smallexample
508  (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))  (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
# Line 516  Similarily, you can have alists with mor Line 527  Similarily, you can have alists with mor
527  key, using variations of this trick:  key, using variations of this trick:
528    
529  @smallexample  @smallexample
530  (defcustom person-data '(("brian"  50 t)  (defcustom person-data '(("brian"  50 t)
531                           ("dorith" 55 nil)                           ("dorith" 55 nil)
532                           ("ken"    52 t))                           ("ken"    52 t))
533    "Alist of basic info about people.    "Alist of basic info about people.
534  Each element has the form (NAME AGE MALE-FLAG)."  Each element has the form (NAME AGE MALE-FLAG)."
535    :type '(alist :value-type (group age boolean)))    :type '(alist :value-type (group age boolean)))
536    
537  (defcustom pets '(("brian")  (defcustom pets '(("brian")
538                    ("dorith" "dog" "guppy")                    ("dorith" "dog" "guppy")
539                    ("ken" "cat"))                    ("ken" "cat"))
540    "Alist of people's pets.    "Alist of people's pets.
# Line 578  The value must be a valid color name, an Line 589  The value must be a valid color name, an
589    
590  @node Composite Types  @node Composite Types
591  @subsection Composite Types  @subsection Composite Types
592    @cindex arguments (of composite type)
593    
594    When none of the simple types is appropriate, you can use composite    When none of the simple types is appropriate, you can use composite
595  types, which build new types from other types.  Here are several ways of  types, which build new types from other types or from specified data.
596  doing that:  The specified types or data are called the @dfn{arguments} of the
597    composite type.  The composite type normally looks like this:
 @table @code  
 @item (restricted-sexp :match-alternatives @var{criteria})  
 The value may be any Lisp object that satisfies one of @var{criteria}.  
 @var{criteria} should be a list, and each element should be  
 one of these possibilities:  
   
 @itemize @bullet  
 @item  
 A predicate---that is, a function of one argument that has no side  
 effects, and returns either @code{nil} or non-@code{nil} according to  
 the argument.  Using a predicate in the list says that objects for which  
 the predicate returns non-@code{nil} are acceptable.  
   
 @item  
 A quoted constant---that is, @code{'@var{object}}.  This sort of element  
 in the list says that @var{object} itself is an acceptable value.  
 @end itemize  
   
 For example,  
598    
599  @example  @example
600  (restricted-sexp :match-alternatives  (@var{constructor} @var{arguments}@dots{})
                  (integerp 't 'nil))  
601  @end example  @end example
602    
603  @noindent  @noindent
604  allows integers, @code{t} and @code{nil} as legitimate values.  but you can also add keyword-value pairs before the arguments, like
605    this:
606    
607  The customization buffer shows all legitimate values using their read  @example
608  syntax, and the user edits them textually.  (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
609    @end example
610    
611      Here is a table of constructors and how to use them to write
612    composite types:
613    
614    @table @code
615  @item (cons @var{car-type} @var{cdr-type})  @item (cons @var{car-type} @var{cdr-type})
616  The value must be a cons cell, its @sc{car} must fit @var{car-type}, and  The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
617  its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string  its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
# Line 667  In any alternative for which @code{nil} Line 665  In any alternative for which @code{nil}
665  a @code{const}, you should specify a valid default for that alternative  a @code{const}, you should specify a valid default for that alternative
666  using the @code{:value} keyword.  @xref{Type Keywords}.  using the @code{:value} keyword.  @xref{Type Keywords}.
667    
668    If some values are covered by more than one of the alternatives,
669    customize will choose the first alternative that the value fits.  This
670    means you should always list the most specific types first, and the
671    most general last.  Here's an example of proper usage:
672    
673    @example
674    (choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
675    @end example
676    
677    @noindent
678    This way, the special value @code{nil} is not treated like other
679    symbols, and symbols are not treated like other Lisp expressions.
680    
681  @item (radio @var{element-types}@dots{})  @item (radio @var{element-types}@dots{})
682  This is similar to @code{choice}, except that the choices are displayed  This is similar to @code{choice}, except that the choices are displayed
683  using `radio buttons' rather than a menu.  This has the advantage of  using `radio buttons' rather than a menu.  This has the advantage of
# Line 761  The value must be a list and each elemen Line 772  The value must be a list and each elemen
772  @var{element-type}.  This appears in the customization buffer as a  @var{element-type}.  This appears in the customization buffer as a
773  list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding  list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
774  more elements or removing elements.  more elements or removing elements.
775    
776    @item (restricted-sexp :match-alternatives @var{criteria})
777    This is the most general composite type construct.  The value may be
778    any Lisp object that satisfies one of @var{criteria}.  @var{criteria}
779    should be a list, and each element should be one of these
780    possibilities:
781    
782    @itemize @bullet
783    @item
784    A predicate---that is, a function of one argument that has no side
785    effects, and returns either @code{nil} or non-@code{nil} according to
786    the argument.  Using a predicate in the list says that objects for which
787    the predicate returns non-@code{nil} are acceptable.
788    
789    @item
790    A quoted constant---that is, @code{'@var{object}}.  This sort of element
791    in the list says that @var{object} itself is an acceptable value.
792    @end itemize
793    
794    For example,
795    
796    @example
797    (restricted-sexp :match-alternatives
798                     (integerp 't 'nil))
799    @end example
800    
801    @noindent
802    allows integers, @code{t} and @code{nil} as legitimate values.
803    
804    The customization buffer shows all legitimate values using their read
805    syntax, and the user edits them textually.
806    @end table
807    
808      Here is a table of the keywords you can use in keyword-value pairs
809    in a composite type:
810    
811    @table @code
812    @item :tag @var{tag}
813    Use @var{tag} as the name of this alternative, for user communication
814    purposes.  This is useful for a type that appears inside of a
815    @code{choice}.
816    
817    @item :match-alternatives @var{criteria}
818    Use @var{criteria} to match possible values.  This is used only in
819    @code{restricted-sexp}.
820    
821    @item :args @var{argumentlist}
822    Use the elements of @var{argumentlist} as the arguments of the type
823    construct.  For instance, @code{(const :args (foo))} is equivalent to
824    @code{(const foo)}.  You rarely need to write @code{:args} explicitly,
825    because normally the arguments are recognized automatically as
826    whatever follows the last keyword-value pair.
827  @end table  @end table
828    
829  @node Splicing into Lists  @node Splicing into Lists
# Line 782  matches a list with three elements, thos Line 845  matches a list with three elements, thos
845  overall sequence.  This is analogous to using @samp{,@@} in the backquote  overall sequence.  This is analogous to using @samp{,@@} in the backquote
846  construct.  construct.
847    
848    For example, to specify a list whose first element must be @code{t}    For example, to specify a list whose first element must be @code{baz}
849  and whose remaining arguments should be zero or more of @code{foo} and  and whose remaining arguments should be zero or more of @code{foo} and
850  @code{bar}, use this customization type:  @code{bar}, use this customization type:
851    
852  @example  @example
853  (list (const t) (set :inline t foo bar))  (list (const baz) (set :inline t (const foo) (const bar)))
854  @end example  @end example
855    
856  @noindent  @noindent
857  This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}  This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
858  and @code{(t foo bar)}.  and @code{(baz foo bar)}.
859    
860    When the element-type is a @code{choice}, you use @code{:inline} not    When the element-type is a @code{choice}, you use @code{:inline} not
861  in the @code{choice} itself, but in (some of) the alternatives of the  in the @code{choice} itself, but in (some of) the alternatives of the
# Line 867  Substitute the tag here.  You specify th Line 930  Substitute the tag here.  You specify th
930  keyword.  keyword.
931    
932  @item %%  @item %%
933  Display a literal @samp{%}.  Display a literal @samp{%}.
934  @end table  @end table
935    
936  @item :action @var{action}  @item :action @var{action}
# Line 970  implemented. Line 1033  implemented.
1033  @item  @item
1034  Widgets with tabbing order @code{-1} are ignored.  Widgets with tabbing order @code{-1} are ignored.
1035    
1036  @item  @item
1037  (Unimplemented) When on a widget with tabbing order @var{n}, go to the  (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1038  next widget in the buffer with tabbing order @var{n+1} or @code{nil},  next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1039  whichever comes first.  whichever comes first.

Legend:
Removed from v.1.25  
changed lines
  Added in v.1.25.2.1

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