Mercurial > hg > xemacs-beta

comparison man/lispref/customize.texi @ 775:7d972c3de90a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2002-03-14 11:50:12 by stephent] New 21.5 Info docs, misc. <87r8mn8j4v.fsf@tleeps18.sk.tsukuba.ac.jp>
author stephent
date Thu, 14 Mar 2002 11:50:17 +0000
parents 576fb035e263
children 47c30044fc4e
comparison
equal deleted inserted replaced
774:703228f54913 775:7d972c3de90a
14 @menu 14 @menu
15 * Common Keywords:: 15 * Common Keywords::
16 * Group Definitions:: 16 * Group Definitions::
17 * Variable Definitions:: 17 * Variable Definitions::
18 * Customization Types:: 18 * Customization Types::
19 * Enabling Behavior::
19 @end menu 20 @end menu
20 21
21 @node Common Keywords 22 @node Common Keywords
22 @section Common Keywords for All Kinds of Items 23 @section Common Keywords for All Kinds of Items
23 24
285 @code{standard-value} to record the expression for the default value, 286 @code{standard-value} to record the expression for the default value,
286 and @code{saved-value} to record the value saved by the user with the 287 and @code{saved-value} to record the value saved by the user with the
287 customization buffer. The @code{saved-value} property is actually a 288 customization buffer. The @code{saved-value} property is actually a
288 list whose car is an expression which evaluates to the value. 289 list whose car is an expression which evaluates to the value.
289 290
290 @node Customization Types 291 @node Customization Types, Enabling Behavior, Variable Definitions, Customization
291 @section Customization Types 292 @section Customization Types
292 293
293 When you define a user option with @code{defcustom}, you must specify 294 When you define a user option with @code{defcustom}, you must specify
294 its @dfn{customization type}. That is a Lisp object which describes (1) 295 its @dfn{customization type}. That is a Lisp object which describes (1)
295 which values are legitimate and (2) how to display the value in the 296 which values are legitimate and (2) how to display the value in the
746 @code{checklist}. The value should be a list of extra keyword 747 @code{checklist}. The value should be a list of extra keyword
747 arguments, which will be used when creating the @code{radio-button} or 748 arguments, which will be used when creating the @code{radio-button} or
748 @code{checkbox} associated with this item. 749 @code{checkbox} associated with this item.
749 @end ignore 750 @end ignore
750 @end table 751 @end table
752
753
754 @node Enabling Behavior, , Customization Types, Customization
755 @subsection Enabling Behavior
756 @cindex behavior
757
758 @c #### Does this belong here?
759
760 Some functionality requires a fair amount of effort to enable globally
761 in a session. For example, someone who discovers filladapt and really
762 likes it must toggle it separately in each buffer. On the other hand,
763 after trying it for a while she might like to disable it everywhere,
764 having decided it doesn't work very well for her. Such a functionality
765 is called a @dfn{behavior}.
766
767 @code{define-behavior} allows the programmer to register functions to
768 enable or disable a package globally in a session. The user sees a
769 consistent interface through the @code{enable-behavior} and
770 @code{disable-behavior} functions. These functions were introduced in
771 XEmacs 21.5.6.
772
773 @defvar behavior-hash-table
774
775 Internal table of registered behaviors.
776 @end defvar
777
778 @defvar behavior-history
779
780 History of entered behaviors.
781 @end defvar
782
783 @defun define-behavior name doc-string [cl-keys ...]
784
785 Define a behavior named @var{name}.
786
787 @var{doc-string} must be specified. It is a description of what the
788 behavior does when it's enabled and how to further control it (typically
789 through custom variables). Accepted keywords are
790
791 @table @code
792 @item :title
793 A "pretty" version of the name, for use in menus. If omitted
794 a prettified name will be generated.
795
796 @item :require
797 A single symbol or a list of such symbols, which need to be
798 present at enable time, or will be loaded using @code{require}.
799
800 @item :enable
801 A function of no variables, which turns the behavior on.
802
803 @item :disable
804 A function of no variables, which turns the behavior off.
805 @end table
806
807 Behaviors are assumed to be global, and to take effect immediately; if
808 the underlying package is per-buffer, the enabler may have to scan all
809 existing buffers and frob them. When a behavior is disabled, it should
810 completely go away @strong{everywhere}, as if it were never invoked at
811 all.
812
813 The @code{:disable} keyword can be missing. This is bad practice. In
814 such a case, attempting to disable the behavior will signal an error
815 unless you use the @code{force} option.
816 @end defun
817
818 @defun read-behavior prompt [require-match [initial-contents [history [default]]]]
819
820 Return a behavior symbol from the minibuffer, prompting with string
821 @var{prompt}.
822
823 The optional arguments @var{require-match}, @var{initial-contents},
824 @var{history}, and @var{default} are passed to @code{completing-read},
825 and have semantics derived from that function. @ref{Minibuffer
826 Completion}. The default value of @var{history} is
827 @code{behavior-history}.
828 @end defun
829
830 @defun behavior-enabled-p name
831
832 Return non-nil if the behavior registered under @var{name} is enabled.
833
834 Unimplemented in 21.5.6.
835 @end defun
836
837 @defun enable-behavior behavior [force]
838 Enable the behavior registered under the symbol @var{behavior}.
839
840 The optional argument @var{force} is unimplemented in 21.5.6.
841
842 Called interactively, prompt the user for @var{behavior}, and take
843 @var{force} from the prefix argument.
844 @end defun
845
846 @defun disable-behavior (behavior &optional force)
847 Disable the behavior registered under the symbol @var{behavior}.
848
849 The optional argument @var{force} is unimplemented in 21.5.6.
850
851 Called interactively, prompt the user for @var{behavior}, and take
852 @var{force} from the prefix argument.
853 @end defun
854