path: root/devdocs/elisp/mode-hooks.html

 <h4 class="subsection">Mode Hooks</h4> <p>Every major mode command should finish by running the mode-independent normal hook <code>change-major-mode-after-body-hook</code>, its mode hook, and the normal hook <code>after-change-major-mode-hook</code>. It does this by calling <code>run-mode-hooks</code>. If the major mode is a derived mode, that is if it calls another major mode (the parent mode) in its body, it should do this inside <code>delay-mode-hooks</code> so that the parent won’t run these hooks itself. Instead, the derived mode’s call to <code>run-mode-hooks</code> runs the parent’s mode hook too. See <a href="major-mode-conventions">Major Mode Conventions</a>. </p> <p>Emacs versions before Emacs 22 did not have <code>delay-mode-hooks</code>. Versions before 24 did not have <code>change-major-mode-after-body-hook</code>. When user-implemented major modes do not use <code>run-mode-hooks</code> and have not been updated to use these newer features, they won’t entirely follow these conventions: they may run the parent’s mode hook too early, or fail to run <code>after-change-major-mode-hook</code>. If you encounter such a major mode, please correct it to follow these conventions. </p> <p>When you define a major mode using <code>define-derived-mode</code>, it automatically makes sure these conventions are followed. If you define a major mode “by hand”, not using <code>define-derived-mode</code>, use the following functions to handle these conventions automatically. </p> <dl> <dt id="run-mode-hooks">Function: <strong>run-mode-hooks</strong> <em>&amp;rest hookvars</em>
</dt> <dd>
<p>Major modes should run their mode hook using this function. It is similar to <code>run-hooks</code> (see <a href="hooks">Hooks</a>), but it also runs <code>change-major-mode-after-body-hook</code>, <code>hack-local-variables</code> (when the buffer is visiting a file) (see <a href="file-local-variables">File Local Variables</a>), and <code>after-change-major-mode-hook</code>. The last thing it does is to evaluate any <code>:after-hook</code> forms declared by parent modes (see <a href="derived-modes">Derived Modes</a>). </p> <p>When this function is called during the execution of a <code>delay-mode-hooks</code> form, it does not run the hooks or <code>hack-local-variables</code> or evaluate the forms immediately. Instead, it arranges for the next call to <code>run-mode-hooks</code> to run them. </p>
</dd>
</dl> <dl> <dt id="delay-mode-hooks">Macro: <strong>delay-mode-hooks</strong> <em>body…</em>
</dt> <dd>
<p>When one major mode command calls another, it should do so inside of <code>delay-mode-hooks</code>. </p> <p>This macro executes <var>body</var>, but tells all <code>run-mode-hooks</code> calls during the execution of <var>body</var> to delay running their hooks. The hooks will actually run during the next call to <code>run-mode-hooks</code> after the end of the <code>delay-mode-hooks</code> construct. </p>
</dd>
</dl> <dl> <dt id="change-major-mode-after-body-hook">Variable: <strong>change-major-mode-after-body-hook</strong>
</dt> <dd><p>This is a normal hook run by <code>run-mode-hooks</code>. It is run before the mode hooks. </p></dd>
</dl> <dl> <dt id="after-change-major-mode-hook">Variable: <strong>after-change-major-mode-hook</strong>
</dt> <dd><p>This is a normal hook run by <code>run-mode-hooks</code>. It is run at the very end of every properly-written major mode command. </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/Mode-Hooks.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Hooks.html</a>
  </p>
</div>