;;; custom.el --- tools for declaring and initializing options
;;
-;; Copyright (C) 1996, 1997, 1999, 2001, 2002 Free Software Foundation, Inc.
+;; Copyright (C) 1996, 1997, 1999, 2001, 2002, 2004, 2005
+;; Free Software Foundation, Inc.
;;
;; Author: Per Abrahamsen <abraham@dina.kvl.dk>
;; Maintainer: FSF
"Initialize SYMBOL with VALUE.
This will do nothing if symbol already has a default binding.
Otherwise, if symbol has a `saved-value' property, it will evaluate
-the car of that and used as the default binding for symbol.
+the car of that and use it as the default binding for symbol.
Otherwise, VALUE will be evaluated and used as the default binding for
symbol."
(unless (default-boundp symbol)
;; Do the actual initialization.
(unless custom-dont-initialize
(funcall initialize symbol default)))
- (push (cons 'defvar symbol) current-load-list)
+ (push symbol current-load-list)
(run-hooks 'custom-define-hook)
symbol)
"Declare SYMBOL as a customizable variable that defaults to VALUE.
DOC is the variable documentation.
-Neither SYMBOL nor VALUE needs to be quoted.
+Neither SYMBOL nor VALUE need to be quoted.
If SYMBOL is not already bound, initialize it to VALUE.
The remaining arguments should have the form
Include an external link after the documentation string for this
item. This is a sentence containing an active field which
references some other documentation.
-
+
There are three alternatives you can use for LINK-DATA:
-
+
(custom-manual INFO-NODE)
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in \"(emacs)Top\". The link appears as
`[manual]' in the customization buffer.
-
+
(info-link INFO-NODE)
Like `custom-manual' except that the link appears in the
customization buffer with the Info node name.
-
+
(url-link URL)
Link to a web page; URL is a string which specifies the URL.
The link appears in the customization buffer as URL.
-
+
You can specify the text to use in the customization buffer by
adding `:tag NAME' after the first element of the LINK-DATA; for
example, (info-link :tag \"foo\" \"(emacs)Top\") makes a link to the
Emacs manual which appears in the buffer as `foo'.
-
+
An item can have more than one external link; however, most items
have none at all.
:initialize
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
+If SYMBOL has a local binding, then this form affects the local
+binding. This is normally not what you want. Thus, if you need
+to load a file defining variables with this form, or with
+`defvar' or `defconst', you should always load that file
+_outside_ any bindings for these variables. \(`defvar' and
+`defconst' behave similarly in this respect.)
+
Read the section about customization in the Emacs Lisp manual for more
information."
;; It is better not to use backquote in this file,
Third argument DOC is the face documentation.
-If FACE has been set with `custom-set-face', set the face attributes
+If FACE has been set with `custom-set-faces', set the face attributes
as specified by that function, otherwise set the face attributes
according to SPEC.
SPEC should be an alist of the form ((DISPLAY ATTS)...).
-The first element of SPEC where the DISPLAY matches the frame
-is the one that takes effect in that frame. The ATTRs in this
-element take effect; the other elements are ignored, on that frame.
+In the first element, DISPLAY can be :default. The ATTS in that
+element then act as defaults for all the following elements.
+
+Aside from that, DISPLAY specifies conditions to match some or
+all frames. For each frame, the first element of SPEC where the
+DISPLAY conditions are satisfied is the one that applies to that
+frame. The ATTRs in this element take effect, and the following
+elements are ignored, on that frame.
+
+In the last element, DISPLAY can be t. That element applies to a
+frame if none of the previous elements (except the :default if
+any) did.
ATTS is a list of face attributes followed by their values:
(ATTR VALUE ATTR VALUE...)
`:slant', `:underline', `:overline', `:strike-through', `:box',
`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'.
-DISPLAY can either be the symbol t, which will match all frames, or an
-alist of the form \((REQ ITEM...)...). For the DISPLAY to match a
-FRAME, the REQ property of the frame must match one of the ITEM. The
-following REQ are defined:
+DISPLAY can be `:default' (only in the first element), the symbol
+t (only in the last element) to match all frames, or an alist of
+conditions of the form \(REQ ITEM...). For such an alist to
+match a frame, each of the conditions must be satisfied, meaning
+that the REQ property of the frame must match one of the
+corresponding ITEMs. These are the defined REQ values:
`type' (the value of `window-system')
Under X, in addition to the values `window-system' can take,
- `motif', `lucid' and `x-toolkit' are allowed, and match when
- the Motif toolkit, Lucid toolkit, or any X toolkit is in use.
+ `motif', `lucid', `gtk' and `x-toolkit' are allowed, and match when
+ the Motif toolkit, Lucid toolkit, GTK toolkit or any X toolkit is in use.
`class' (the frame's color support)
Should be one of `color', `grayscale', or `mono'.
`background' (what color is used for the background text)
Should be one of `light' or `dark'.
+`min-colors' (the minimum number of colors the frame should support)
+ Should be an integer, it is compared with the result of
+ `display-color-cells'.
+
+`supports' (only match frames that support the specified face attributes)
+ Should be a list of face attributes. See the documentation for
+ the function `display-supports-face-attributes-p' for more
+ information on exactly how testing is done.
+
Read the section about customization in the Emacs Lisp manual for more
information."
;; It is better not to use backquote in this file,
(unless (member load loads)
(put symbol 'custom-loads (cons (purecopy load) loads)))))
+(defun custom-autoload (symbol load)
+ "Mark SYMBOL as autoloaded custom variable and add dependency LOAD."
+ (put symbol 'custom-autoload t)
+ (custom-add-load symbol load))
+
+;; This test is also in the C code of `user-variable-p'.
+(defun custom-variable-p (variable)
+ "Return non-nil if VARIABLE is a custom variable."
+ (or (get variable 'standard-value)
+ (get variable 'custom-autoload)))
+
;;; Loading files needed to customize a symbol.
;;; This is in custom.el because menu-bar.el needs it for toggle cmds.
"Load all dependencies for SYMBOL."
(unless custom-load-recursion
(let ((custom-load-recursion t))
+ ;; Load these files if not already done,
+ ;; to make sure we know all the dependencies of SYMBOL.
+ (condition-case nil
+ (require 'cus-load)
+ (error nil))
+ (condition-case nil
+ (require 'cus-start)
+ (error nil))
(dolist (load (get symbol 'custom-loads))
(cond ((symbolp load) (condition-case nil (require load) (error nil)))
;; This is subsumed by the test below, but it's much faster.
(error "Keyword %s is missing an argument" keyword))
(setq args (cdr args))
(cond ((eq keyword :short-description)
- (put theme 'theme-short-description short-description))
+ (put theme 'theme-short-description value))
((eq keyword :immediate)
- (put theme 'theme-immediate immediate))
+ (put theme 'theme-immediate value))
((eq keyword :variable-set-string)
- (put theme 'theme-variable-set-string variable-set-string))
+ (put theme 'theme-variable-set-string value))
((eq keyword :variable-reset-string)
- (put theme 'theme-variable-reset-string variable-reset-string))
+ (put theme 'theme-variable-reset-string value))
((eq keyword :face-set-string)
- (put theme 'theme-face-set-string face-set-string))
+ (put theme 'theme-face-set-string value))
((eq keyword :face-reset-string)
- (put theme 'theme-face-reset-string face-reset-string)))))))
+ (put theme 'theme-face-reset-string value)))))))
(defmacro deftheme (theme &optional doc &rest args)
"Declare custom theme THEME.
(put 'custom-local-buffer 'permanent-local t)
(defun custom-set-variables (&rest args)
- "Initialize variables according to user preferences.
-The settings are registered as theme `user'.
+ "Install user customizations of variable values specified in ARGS.
+These settings are registered as theme `user'.
The arguments should each be a list of the form:
- (SYMBOL VALUE [NOW [REQUEST [COMMENT]]])
+ (SYMBOL EXP [NOW [REQUEST [COMMENT]]])
-The unevaluated VALUE is stored as the saved value for SYMBOL.
-If NOW is present and non-nil, VALUE is also evaluated and bound as
-the default value for the SYMBOL.
+This stores EXP (without evaluating it) as the saved value for SYMBOL.
+If NOW is present and non-nil, then also evaluate EXP and set
+the default value for the SYMBOL to the value of EXP.
-REQUEST is a list of features we must 'require for SYMBOL.
+REQUEST is a list of features we must require in order to
+handle SYMBOL properly.
COMMENT is a comment string about SYMBOL."
(apply 'custom-theme-set-variables 'user args))
+(defun custom-reevaluate-setting (symbol)
+ "Reset the value of SYMBOL by re-evaluating its saved or default value.
+This is useful for variables that are defined before their default value
+can really be computed. E.g. dumped variables whose default depends on
+run-time information."
+ (funcall (or (get symbol 'custom-set) 'set-default)
+ symbol
+ (eval (car (or (get symbol 'saved-value) (get symbol 'standard-value))))))
+
(defun custom-theme-set-variables (theme &rest args)
- "Initialize variables according to settings specified by args.
-Records the settings as belonging to THEME.
+ "Initialize variables for theme THEME according to settings in ARGS.
+Each of the arguments in ARGS should be a list of this form:
-The arguments should be a list where each entry has the form:
+ (SYMBOL EXP [NOW [REQUEST [COMMENT]]])
- (SYMBOL VALUE [NOW [REQUEST [COMMENT]]])
+This stores EXP (without evaluating it) as the saved value for SYMBOL.
+If NOW is present and non-nil, then also evaluate EXP and set
+the default value for the SYMBOL to the value of EXP.
-The unevaluated VALUE is stored as the saved value for SYMBOL.
-If NOW is present and non-nil, VALUE is also evaluated and bound as
-the default value for the SYMBOL.
-REQUEST is a list of features we must 'require for SYMBOL.
+REQUEST is a list of features we must require in order to
+handle SYMBOL properly.
COMMENT is a comment string about SYMBOL.
Several properties of THEME and SYMBOL are used in the process:
-If THEME property `theme-immediate' is non-nil, this is equivalent of
-providing the NOW argument to all symbols in the argument list: SYMBOL
-is bound to the evaluated VALUE. The only difference is SYMBOL property
+If THEME's property `theme-immediate' is non-nil, this is equivalent of
+providing the NOW argument to all symbols in the argument list:
+evaluate each EXP and set the corresponding SYMBOL. However,
+there's a difference in the handling of SYMBOL's property
`force-value': if NOW is non-nil, SYMBOL's property `force-value' is set to
the symbol `rogue', else if THEME's property `theme-immediate' is non-nil,
-FACE's property `force-face' is set to the symbol `immediate'.
+SYMBOL's property `force-value' is set to the symbol `immediate'.
-VALUE itself is saved unevaluated as SYMBOL property `saved-value' and
+EXP itself is saved unevaluated as SYMBOL property `saved-value' and
in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
(custom-check-theme theme)
- (let ((immediate (get theme 'theme-immediate)))
- (setq args
- (sort args
- (lambda (a1 a2)
- (let* ((sym1 (car a1))
- (sym2 (car a2))
- (1-then-2 (memq sym1 (get sym2 'custom-dependencies)))
- (2-then-1 (memq sym2 (get sym1 'custom-dependencies))))
- (cond ((and 1-then-2 2-then-1)
- (error "Circular custom dependency between `%s' and `%s'"
- sym1 sym2))
- (2-then-1 nil)
- ;; Put symbols with :require last. The macro
- ;; define-minor-mode generates a defcustom
- ;; with a :require and a :set, where the
- ;; setter function calls the mode function.
- ;; Putting symbols with :require last ensures
- ;; that the mode function will see other
- ;; customized values rather than default
- ;; values.
- (t (nth 3 a2)))))))
- (while args
- (let ((entry (car args)))
- (if (listp entry)
- (let* ((symbol (nth 0 entry))
- (value (nth 1 entry))
- (now (nth 2 entry))
- (requests (nth 3 entry))
- (comment (nth 4 entry))
- set)
- (when requests
- (put symbol 'custom-requests requests)
- (mapc 'require requests))
- (setq set (or (get symbol 'custom-set) 'custom-set-default))
- (put symbol 'saved-value (list value))
- (put symbol 'saved-variable-comment comment)
- (custom-push-theme 'theme-value symbol theme 'set value)
- ;; Allow for errors in the case where the setter has
+ (setq args
+ (sort args
+ (lambda (a1 a2)
+ (let* ((sym1 (car a1))
+ (sym2 (car a2))
+ (1-then-2 (memq sym1 (get sym2 'custom-dependencies)))
+ (2-then-1 (memq sym2 (get sym1 'custom-dependencies))))
+ (cond ((and 1-then-2 2-then-1)
+ (error "Circular custom dependency between `%s' and `%s'"
+ sym1 sym2))
+ (2-then-1 nil)
+ ;; Put symbols with :require last. The macro
+ ;; define-minor-mode generates a defcustom
+ ;; with a :require and a :set, where the
+ ;; setter function calls the mode function.
+ ;; Putting symbols with :require last ensures
+ ;; that the mode function will see other
+ ;; customized values rather than default
+ ;; values.
+ (t (nth 3 a2)))))))
+ (while args
+ (let ((entry (car args)))
+ (if (listp entry)
+ (let* ((symbol (indirect-variable (nth 0 entry)))
+ (value (nth 1 entry))
+ (now (nth 2 entry))
+ (requests (nth 3 entry))
+ (comment (nth 4 entry))
+ set)
+ (when requests
+ (put symbol 'custom-requests requests)
+ (mapc 'require requests))
+ (setq set (or (get symbol 'custom-set) 'custom-set-default))
+ (put symbol 'saved-value (list value))
+ (put symbol 'saved-variable-comment comment)
+ (custom-push-theme 'theme-value symbol theme 'set value)
+ ;; Allow for errors in the case where the setter has
;; changed between versions, say, but let the user know.
(condition-case data
(cond (now
((default-boundp symbol)
;; Something already set this, overwrite it.
(funcall set symbol (eval value))))
- (error
+ (error
(message "Error setting %s: %s" symbol data)))
- (setq args (cdr args))
- (and (or now (default-boundp symbol))
- (put symbol 'variable-comment comment)))
- ;; Old format, a plist of SYMBOL VALUE pairs.
- (message "Warning: old format `custom-set-variables'")
- (ding)
- (sit-for 2)
- (let ((symbol (nth 0 args))
- (value (nth 1 args)))
- (put symbol 'saved-value (list value))
- (custom-push-theme 'theme-value symbol theme 'set value))
- (setq args (cdr (cdr args))))))))
+ (setq args (cdr args))
+ (and (or now (default-boundp symbol))
+ (put symbol 'variable-comment comment)))
+ ;; Old format, a plist of SYMBOL VALUE pairs.
+ (message "Warning: old format `custom-set-variables'")
+ (ding)
+ (sit-for 2)
+ (let ((symbol (indirect-variable (nth 0 args)))
+ (value (nth 1 args)))
+ (put symbol 'saved-value (list value))
+ (custom-push-theme 'theme-value symbol theme 'set value))
+ (setq args (cdr (cdr args)))))))
(defun custom-set-default (variable value)
"Default :set function for a customizable variable.
(set variable value))
(set-default variable value)))
+(defun custom-set-minor-mode (variable value)
+ ":set function for minor mode variables.
+Normally, this sets the default value of VARIABLE to nil if VALUE
+is nil and to t otherwise,
+but if `custom-local-buffer' is non-nil,
+this sets the local binding in that buffer instead."
+ (if custom-local-buffer
+ (with-current-buffer custom-local-buffer
+ (funcall variable (if value 1 0)))
+ (funcall variable (if value 1 0))))
+
(defun custom-quote (sexp)
"Quote SEXP iff it is not self quoting."
(if (or (memq sexp '(t nil))
(defun customize-mark-to-save (symbol)
"Mark SYMBOL for later saving.
-If the default value of SYMBOL is different from the standard value,
+If the default value of SYMBOL is different from the standard value,
set the `saved-value' property to a list whose car evaluates to the
-default value. Otherwise, set it til nil.
+default value. Otherwise, set it to nil.
To actually save the value, call `custom-save-all'.
(defun customize-mark-as-set (symbol)
"Mark current value of SYMBOL as being set from customize.
-If the default value of SYMBOL is different from the saved value if any,
+If the default value of SYMBOL is different from the saved value if any,
or else if it is different from the standard value, set the
-`customized-value' property to a list whose car evaluates to the
-default value. Otherwise, set it til nil.
+`customized-value' property to a list whose car evaluates to the
+default value. Otherwise, set it to nil.
Return non-nil iff the `customized-value' property actually changed."
(let* ((get (or (get symbol 'custom-get) 'default-value))
(old (or (get symbol 'saved-value) (get symbol 'standard-value))))
;; Mark default value as set iff different from old value.
(if (or (null old)
- (not (equal value (condition-case nil
+ (not (equal value (condition-case nil
(eval (car old))
(error nil)))))
(put symbol 'customized-value (list (custom-quote value)))
(custom-make-theme-feature theme))))
(defun custom-remove-theme (spec-alist theme)
- "Detelete all elements from SPEC-ALIST whose car is THEME."
+ "Delete all elements from SPEC-ALIST whose car is THEME."
(let ((elt (assoc theme spec-alist)))
(while elt
(setq spec-alist (delete elt spec-alist)
(provide 'custom)
+;; arch-tag: 041b6116-aabe-4f9a-902d-74092bc3dab2
;;; custom.el ends here