path: root/devdocs/elisp/custom-themes.html

 <h3 class="section">Custom Themes</h3>  <p><em>Custom themes</em> are collections of settings that can be enabled or disabled as a unit. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Custom-Themes.html#Custom-Themes">Custom Themes</a> in <cite>The GNU Emacs Manual</cite>. 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; see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Creating-Custom-Themes.html#Creating-Custom-Themes">Creating Custom Themes</a> in <cite>The GNU Emacs Manual</cite>.) </p> <p>A Custom theme file should be named <samp><var>foo</var>-theme.el</samp>, where <var>foo</var> is the theme name. The first Lisp form in the file should be a call to <code>deftheme</code>, and the last form should be a call to <code>provide-theme</code>. </p> <dl> <dt id="deftheme">Macro: <strong>deftheme</strong> <em>theme &amp;optional doc</em>
</dt> <dd>
<p>This macro declares <var>theme</var> (a symbol) as the name of a Custom theme. The optional argument <var>doc</var> should be a string describing the theme; this is the description shown when the user invokes the <code>describe-theme</code> command or types <kbd>?</kbd> in the ‘<samp>*Custom Themes*</samp>’ buffer. </p> <p>Two special theme names are disallowed (using them causes an error): <code>user</code> is a dummy theme that stores the user’s direct customization settings, and <code>changed</code> is a dummy theme that stores changes made outside of the Customize system. </p>
</dd>
</dl> <dl> <dt id="provide-theme">Macro: <strong>provide-theme</strong> <em>theme</em>
</dt> <dd><p>This macro declares that the theme named <var>theme</var> has been fully specified. </p></dd>
</dl> <p>In between <code>deftheme</code> and <code>provide-theme</code> are Lisp forms specifying the theme settings: usually a call to <code>custom-theme-set-variables</code> and/or a call to <code>custom-theme-set-faces</code>. </p> <dl> <dt id="custom-theme-set-variables">Function: <strong>custom-theme-set-variables</strong> <em>theme &amp;rest args</em>
</dt> <dd>
<p>This function specifies the Custom theme <var>theme</var>’s variable settings. <var>theme</var> should be a symbol. Each argument in <var>args</var> should be a list of the form </p> <div class="example"> <pre class="example">(<var>var</var> <var>expression</var> [<var>now</var> [<var>request</var> [<var>comment</var>]]])
</pre>
</div> <p>where the list entries have the same meanings as in <code>custom-set-variables</code>. See <a href="applying-customizations">Applying Customizations</a>. </p>
</dd>
</dl> <dl> <dt id="custom-theme-set-faces">Function: <strong>custom-theme-set-faces</strong> <em>theme &amp;rest args</em>
</dt> <dd>
<p>This function specifies the Custom theme <var>theme</var>’s face settings. <var>theme</var> should be a symbol. Each argument in <var>args</var> should be a list of the form </p> <div class="example"> <pre class="example">(<var>face</var> <var>spec</var> [<var>now</var> [<var>comment</var>]])
</pre>
</div> <p>where the list entries have the same meanings as in <code>custom-set-faces</code>. See <a href="applying-customizations">Applying Customizations</a>. </p>
</dd>
</dl> <p>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. As such, themes are not ordinarily byte-compiled, and source files usually take precedence when Emacs is looking for a theme to load. </p> <p>The following functions are useful for programmatically enabling and disabling themes: </p> <dl> <dt id="custom-theme-p">Function: <strong>custom-theme-p</strong> <em>theme</em>
</dt> <dd><p>This function return a non-<code>nil</code> value if <var>theme</var> (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 <code>nil</code>. </p></dd>
</dl> <dl> <dt id="custom-known-themes">Variable: <strong>custom-known-themes</strong>
</dt> <dd><p>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: <code>(user changed)</code>. The <code>changed</code> theme stores settings made before any Custom themes are applied (e.g., variables set outside of Customize). The <code>user</code> theme stores settings the user has customized and saved. Any additional themes declared with the <code>deftheme</code> macro are added to the front of this list. </p></dd>
</dl> <dl> <dt id="load-theme">Command: <strong>load-theme</strong> <em>theme &amp;optional no-confirm no-enable</em>
</dt> <dd><p>This function loads the Custom theme named <var>theme</var> from its source file, looking for the source file in the directories specified by the variable <code>custom-theme-load-path</code>. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Custom-Themes.html#Custom-Themes">Custom Themes</a> in <cite>The GNU Emacs Manual</cite>. It also <em>enables</em> the theme (unless the optional argument <var>no-enable</var> is non-<code>nil</code>), causing its variable and face settings to take effect. It prompts the user for confirmation before loading the theme, unless the optional argument <var>no-confirm</var> is non-<code>nil</code>. </p></dd>
</dl> <dl> <dt id="require-theme">Function: <strong>require-theme</strong> <em>feature &amp;optional noerror</em>
</dt> <dd>
<p>This function searches <code>custom-theme-load-path</code> for a file that provides <var>feature</var> and then loads it. This is like the function <code>require</code> (see <a href="named-features">Named Features</a>), except it searches <code>custom-theme-load-path</code> instead of <code>load-path</code> (see <a href="library-search">Library Search</a>). This can be useful in Custom themes that need to load supporting Lisp files when <code>require</code> is unsuitable for that. </p> <p>If <var>feature</var>, which should be a symbol, is not already present in the current Emacs session according to <code>featurep</code>, then <code>require-theme</code> searches for a file named <var>feature</var> with an added ‘<samp>.elc</samp>’ or ‘<samp>.el</samp>’ suffix, in that order, in the directories specified by <code>custom-theme-load-path</code>. </p> <p>If a file providing <var>feature</var> is successfully found and loaded, then <code>require-theme</code> returns <var>feature</var>. The optional argument <var>noerror</var> determines what happens if the search or loading fails. If it is <code>nil</code>, the function signals an error; otherwise, it returns <code>nil</code>. If the file loads successfully but does not provide <var>feature</var>, then <code>require-theme</code> signals an error; this cannot be suppressed. </p>
</dd>
</dl> <dl> <dt id="enable-theme">Command: <strong>enable-theme</strong> <em>theme</em>
</dt> <dd><p>This function enables the Custom theme named <var>theme</var>. It signals an error if no such theme has been loaded. </p></dd>
</dl> <dl> <dt id="disable-theme">Command: <strong>disable-theme</strong> <em>theme</em>
</dt> <dd><p>This function disables the Custom theme named <var>theme</var>. The theme remains loaded, so that a subsequent call to <code>enable-theme</code> will re-enable it. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Custom-Themes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Custom-Themes.html</a>
  </p>
</div>