For variables in preloaded files, you can simply use this
function for the :initialize property. For autoloaded variables,
you will also need to add an autoload stanza calling this
-function, and another one setting the standard-value property."
+function, and another one setting the standard-value property.
+Or you can wrap the defcustom in a progn, to force the autoloader
+to include all of it." ; see eg vc-sccs-search-project-dir
;; No longer true:
;; "See `send-mail-function' in sendmail.el for an example."
is `default-value'.
:require
VALUE should be a feature symbol. If you save a value
- for this option, then when your `.emacs' file loads the value,
+ for this option, then when your init file loads the value,
it does (require VALUE) first.
:set-after VARIABLES
Specifies that SYMBOL should be set after the list of variables
;; expression is checked by the byte-compiler, and that
;; lexical-binding is obeyed, so quote the expression with
;; `lambda' rather than with `quote'.
- `(list (lambda () ,standard))
+ ``(funcall #',(lambda () ,standard))
`',standard)
,doc
,@args))
Third argument DOC is the face documentation.
-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.
-
-The remaining arguments should have the form
-
- [KEYWORD VALUE]...
+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.
+The remaining arguments should have the form [KEYWORD VALUE]...
For a list of valid keywords, see the common keywords listed in
`defcustom'.
-SPEC should be an alist of the form ((DISPLAY ATTS)...).
-
-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...)
-
-The possible attributes are `:family', `:width', `:height', `:weight',
-`:slant', `:underline', `:overline', `:strike-through', `:box',
-`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'.
-
-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', `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.
-
-See Info node `(elisp) Customization' in the Emacs Lisp manual
-for more information."
+SPEC should be an alist of the form
+
+ ((DISPLAY . ATTS)...)
+
+where DISPLAY is a form specifying conditions to match certain
+terminals and ATTS is a property list (ATTR VALUE ATTR VALUE...)
+specifying face attributes and values for frames on those
+terminals. On each terminal, the first element with a matching
+DISPLAY specification takes effect, and the remaining elements in
+SPEC are disregarded.
+
+As a special exception, in the first element of SPEC, DISPLAY can
+be the special value `default'. Then the ATTS in that element
+act as defaults for all the following elements.
+
+For backward compatibility, elements of SPEC can be written
+as (DISPLAY ATTS) instead of (DISPLAY . ATTS).
+
+Each DISPLAY can have the following values:
+ - `default' (only in the first element).
+ - The symbol t, which matches all terminals.
+ - An alist of conditions. Each alist element must have the form
+ (REQ ITEM...). A matching terminal must satisfy each
+ specified condition by matching one of its ITEMs. Each REQ
+ must be one of the following:
+ - `type' (the terminal type).
+ Each ITEM must be one of the values returned by
+ `window-system'. Under X, additional allowed values are
+ `motif', `lucid', `gtk' and `x-toolkit'.
+ - `class' (the terminal's color support).
+ Each ITEM should be one of `color', `grayscale', or `mono'.
+ - `background' (what color is used for the background text)
+ Each ITEM should be one of `light' or `dark'.
+ - `min-colors' (the minimum number of supported colors)
+ Each ITEM should be an integer, which is compared with the
+ result of `display-color-cells'.
+ - `supports' (match terminals supporting certain attributes).
+ Each ITEM should be a list of face attributes. See
+ `display-supports-face-attributes-p' for more information on
+ exactly how testing is done.
+
+In the ATTS property list, possible attributes are `:family',
+`:width', `:height', `:weight', `:slant', `:underline',
+`:overline', `:strike-through', `:box', `:foreground',
+`:background', `:stipple', `:inverse-video', and `:inherit'.
+
+See Info node `(elisp) Faces' in the Emacs Lisp manual for more
+information."
(declare (doc-string 3))
;; It is better not to use backquote in this file,
;; because that makes a bootstrapping problem
(put symbol 'custom-autoload (if noset 'noset 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 customizable variable.
A customizable variable is either (i) a variable whose property
list contains a non-nil `standard-value' or `custom-autoload'
property, or (ii) an alias for another customizable variable."
- (setq variable (indirect-variable variable))
- (or (get variable 'standard-value)
- (get variable 'custom-autoload)))
+ (when (symbolp variable)
+ (setq variable (indirect-variable variable))
+ (or (get variable 'standard-value)
+ (get variable 'custom-autoload))))
+
+(define-obsolete-function-alias 'user-variable-p 'custom-variable-p "24.3")
(defun custom-note-var-changed (variable)
"Inform Custom that VARIABLE has been set (changed).
(SYMBOL EXP [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.
+SYMBOL is the variable name, and EXP is an expression which
+evaluates to the customized value. EXP will also be stored,
+without evaluating it, in SYMBOL's `saved-value' property, so
+that it can be restored via the Customize interface. It is also
+added to the alist in SYMBOL's `theme-value' property \(by
+calling `custom-push-theme').
-REQUEST is a list of features we must require in order to
-handle SYMBOL properly.
-COMMENT is a comment string about SYMBOL.
+NOW, if present and non-nil, means to install the variable's
+value directly now, even if its `defcustom' declaration has not
+been executed. This is for internal use only.
+
+REQUEST is a list of features to `require' (which are loaded
+prior to evaluating EXP).
-EXP itself is saved unevaluated as SYMBOL property `saved-value' and
-in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
+COMMENT is a comment string about SYMBOL."
(custom-check-theme theme)
;; Process all the needed autoloads before anything else, so that the
Any theme `foo' should be defined in a file called `foo-theme.el';
see `custom-make-theme-feature' for more information."
+ (declare (doc-string 2))
(let ((feature (custom-make-theme-feature theme)))
;; It is better not to use backquote in this file,
;; because that makes a bootstrapping problem
The theme file is named THEME-theme.el, in one of the directories
specified by `custom-theme-load-path'.
-If optional arg NO-CONFIRM is non-nil, and THEME is not
-considered safe according to `custom-safe-themes', prompt the
-user for confirmation.
+If the theme is not considered safe by `custom-safe-themes',
+prompt the user for confirmation before loading it. But if
+optional arg NO-CONFIRM is non-nil, load the theme without
+prompting.
-Normally, this function also enables THEME; if optional arg
-NO-ENABLE is non-nil, load the theme but don't enable it.
+Normally, this function also enables THEME. If optional arg
+NO-ENABLE is non-nil, load the theme but don't enable it, unless
+the theme was already enabled.
This function is normally called through Customize when setting
`custom-enabled-themes'. If used directly in your init file, it
nil nil))
(unless (custom-theme-name-valid-p theme)
(error "Invalid theme name `%s'" theme))
+ ;; If THEME is already enabled, re-enable it after loading, even if
+ ;; NO-ENABLE is t.
+ (if no-enable
+ (setq no-enable (not (custom-theme-enabled-p theme))))
;; If reloading, clear out the old theme settings.
(when (custom-theme-p theme)
(disable-theme theme)
(expand-file-name "themes/" data-directory)))
(member hash custom-safe-themes)
(custom-theme-load-confirm hash))
- (let ((custom--inhibit-theme-enable t))
+ (let ((custom--inhibit-theme-enable t)
+ (buffer-file-name fn)) ;For load-history.
(eval-buffer))
;; Optimization: if the theme changes the `default' face, put that
;; entry first. This avoids some `frame-set-background-mode' rigmarole
"Query the user about loading a Custom theme that may not be safe.
The theme should be in the current buffer. If the user agrees,
query also about adding HASH to `custom-safe-themes'."
- (if noninteractive
- nil
- (let ((exit-chars '(?y ?n ?\s))
- window prompt char)
- (save-window-excursion
- (rename-buffer "*Custom Theme*" t)
- (emacs-lisp-mode)
- (setq window (display-buffer (current-buffer)))
- (setq prompt
- (format "Loading a theme can run Lisp code. Really load?%s"
- (if (and window
- (< (line-number-at-pos (point-max))
- (window-body-height)))
- " (y or n) "
- (push ?\C-v exit-chars)
- "\nType y or n, or C-v to scroll: ")))
- (goto-char (point-min))
- (while (null char)
- (setq char (read-char-choice prompt exit-chars))
- (when (eq char ?\C-v)
- (if window
- (with-selected-window window
- (condition-case nil
- (scroll-up)
- (error (goto-char (point-min))))))
- (setq char nil)))
- (when (memq char '(?\s ?y))
- ;; Offer to save to `custom-safe-themes'.
- (and (or custom-file user-init-file)
- (y-or-n-p "Treat this theme as safe in future sessions? ")
- (customize-push-and-save 'custom-safe-themes (list hash)))
- t)))))
+ (unless noninteractive
+ (save-window-excursion
+ (rename-buffer "*Custom Theme*" t)
+ (emacs-lisp-mode)
+ (pop-to-buffer (current-buffer))
+ (goto-char (point-min))
+ (prog1 (when (y-or-n-p "Loading a theme can run Lisp code. Really load? ")
+ ;; Offer to save to `custom-safe-themes'.
+ (and (or custom-file user-init-file)
+ (y-or-n-p "Treat this theme as safe in future sessions? ")
+ (customize-push-and-save 'custom-safe-themes (list hash)))
+ t)
+ (quit-window)))))
(defun custom-theme-name-valid-p (name)
"Return t if NAME is a valid name for a Custom theme, nil otherwise.