Info Catalog elisp: Applying Customizations elisp: Customization

elisp: Custom Themes

 
 14.6 Custom Themes
 ==================
 
 “Custom themes” are collections of settings that can be enabled or
 disabled as a unit.  (emacs)Custom Themes.  Each Custom theme is
 defined by an Emacs Lisp source file, which should follow the
 conventions described in this section.  (Instead of writing a Custom
 theme by hand, you can also create one using a Customize-like interface;
 (emacs)Creating Custom Themes.)
 
    A Custom theme file should be named ‘FOO-theme.el’, where FOO is the
 theme name.  The first Lisp form in the file should be a call to
 ‘deftheme’, and the last form should be a call to ‘provide-theme’.
 
  -- Macro: deftheme theme &optional doc
      This macro declares THEME (a symbol) as the name of a Custom theme.
      The optional argument DOC should be a string describing the theme;
      this is the description shown when the user invokes the
      ‘describe-theme’ command or types ‘?’ in the ‘*Custom Themes*’
      buffer.
 
      Two special theme names are disallowed (using them causes an
      error): ‘user’ is a dummy theme that stores the user’s direct
      customization settings, and ‘changed’ is a dummy theme that stores
      changes made outside of the Customize system.
 
  -- Macro: provide-theme theme
      This macro declares that the theme named THEME has been fully
      specified.
 
    In between ‘deftheme’ and ‘provide-theme’ are Lisp forms specifying
 the theme settings: usually a call to ‘custom-theme-set-variables’
 and/or a call to ‘custom-theme-set-faces’.
 
  -- Function: custom-theme-set-variables theme &rest args
      This function specifies the Custom theme THEME’s variable settings.
      THEME should be a symbol.  Each argument in ARGS should be a list
      of the form
 
           (VAR EXPRESSION [NOW [REQUEST [COMMENT]]])
 
      where the list entries have the same meanings as in
      ‘custom-set-variables’.  Applying Customizations.
 
  -- Function: custom-theme-set-faces theme &rest args
      This function specifies the Custom theme THEME’s face settings.
      THEME should be a symbol.  Each argument in ARGS should be a list
      of the form
 
           (FACE SPEC [NOW [COMMENT]])
 
      where the list entries have the same meanings as in
      ‘custom-set-faces’.  Applying Customizations.
 
    In theory, a theme file can also contain other Lisp forms, which
 would be evaluated when loading the theme, but that is bad form.  To
 protect against loading themes containing malicious code, Emacs displays
 the source file and asks for confirmation from the user before loading
 any non-built-in theme for the first time.
 
    The following functions are useful for programmatically enabling and
 disabling themes:
 
  -- Function: custom-theme-p theme
      This function return a non-‘nil’ value if THEME (a symbol) is the
      name of a Custom theme (i.e., a Custom theme which has been loaded
      into Emacs, whether or not the theme is enabled).  Otherwise, it
      returns ‘nil’.
 
  -- Variable: custom-known-themes
      The value of this variable is a list of themes loaded into Emacs.
      Each theme is represented by a Lisp symbol (the theme name).  The
      default value of this variable is a list containing two dummy
      themes: ‘(user changed)’.  The ‘changed’ theme stores settings made
      before any Custom themes are applied (e.g., variables set outside
      of Customize).  The ‘user’ theme stores settings the user has
      customized and saved.  Any additional themes declared with the
      ‘deftheme’ macro are added to the front of this list.
 
  -- Command: load-theme theme &optional no-confirm no-enable
      This function loads the Custom theme named THEME from its source
      file, looking for the source file in the directories specified by
      the variable ‘custom-theme-load-path’.  (emacs)Custom
      Themes.  It also “enables” the theme (unless the optional
      argument NO-ENABLE is non-‘nil’), causing its variable and face
      settings to take effect.  It prompts the user for confirmation
      before loading the theme, unless the optional argument NO-CONFIRM
      is non-‘nil’.
 
  -- Command: enable-theme theme
      This function enables the Custom theme named THEME.  It signals an
      error if no such theme has been loaded.
 
  -- Command: disable-theme theme
      This function disables the Custom theme named THEME.  The theme
      remains loaded, so that a subsequent call to ‘enable-theme’ will
      re-enable it.
 

Info Catalog elisp: Applying Customizations elisp: Customization