comparison lispref/modes.texi @ 51917:3039afbb0746

(Major Mode Conventions): Explain about run-mode-hooks and about derived modes. (Minor Modes): Add minor-mode-list. (Defining Minor Modes): Keyword args for define-minor-mode. (Search-based Fontification): Explain managing other properties. (Other Font Lock Variables): Add font-lock-extra-managed-props. (Faces for Font Lock): Add font-locl-preprocessor-face. (Hooks): Add run-mode-hooks and delay-mode-hooks.

51916:f7b97d07a39c

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a @dfn{mode hook} named
@code{@var{modename}-mode-hook}.  The major mode command should run that
hook, with @code{run-hooks}, as the very last thing it
does.  @xref{Hooks}.

@item
The major mode command may also run the hooks of some more basic modes.
For example, @code{indented-text-mode} runs @code{text-mode-hook} as
well as @code{indented-text-mode-hook}.  It may run these other hooks
immediately before the mode's own hook (that is, after everything else),
or it may run them earlier.

@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).

  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
@end group
@end smallexample

  Here is the complete major mode function definition for Text mode:

@smallexample
@group
(defun text-mode ()
  "Major mode for editing text intended for humans to read...

  (setq indent-line-function 'indent-relative-maybe)
@end group
@group
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}
                                    ;   @r{customize the mode with a hook.}
@end group
@end smallexample

@cindex @file{lisp-mode.el}

  (lisp-mode-variables t)                ; @r{This defines various variables.}
@end group
@group
  (setq imenu-case-fold-search t)
  (set-syntax-table lisp-mode-syntax-table)
  (run-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
                                         ;   @r{hook to customize the mode.}
@end group
@end smallexample

@node Auto Major Mode

minor modes in effect.

  Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs.  Minor mode
keymaps make this easier than it used to be.

@menu
* Minor Mode Conventions::      Tips for writing a minor mode.
* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
* Defining Minor Modes::        A convenient facility for defining minor modes.

  The macro @code{define-minor-mode} offers a convenient way of
implementing a mode in one self-contained definition.  It supports only
buffer-local minor modes, not global ones.

@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
@tindex define-minor-mode
This macro defines a new minor mode whose name is @var{mode} (a symbol).
It defines a command named @var{mode} to toggle the minor
mode, with @var{doc} as its documentation string.  It also defines a
variable named @var{mode}, which is set to @code{t} or @code{nil} by
enabling or disabling the mode.  The variable is initialized to
@var{init-value}.

The command named @var{mode} finishes by executing the @var{body} forms,
if any, after it has performed the standard actions such as setting
the variable named @var{mode}.

The string @var{mode-indicator} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
in the mode line.

The optional argument @var{keymap} specifies the keymap for the minor mode.
It can be a variable name, whose value is the keymap, or it can be an alist
specifying bindings in this form:

@example
(@var{key-sequence} . @var{definition})
@end example
@end defmac

  Here is an example of using @code{define-minor-mode}:

@smallexample
(define-minor-mode hungry-mode

 ;; The minor mode bindings.
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t)))))
@end smallexample

@noindent
This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
mode is enabled.  It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.


@findex easy-mmode-define-minor-mode
  The name @code{easy-mmode-define-minor-mode} is an alias
for this macro.

@node Mode Line Format
@section Mode Line Format
@cindex mode line

;; @r{Highlight occurrences of @samp{fubar},}
;; @r{using the face which is the value of @code{fubar-face}.}
("fubar" . fubar-face)
@end example

@item (@var{matcher} . @var{highlighter})
In this kind of element, @var{highlighter} is a list
which specifies how to highlight matches found by @var{matcher}.
It has the form

but not too large so that refontification becomes slow.  Typical values
are @code{mark-defun} for programming modes or @code{mark-paragraph} for
textual modes.
@end defvar

@node Levels of Font Lock
@subsection Levels of Font Lock

  Many major modes offer three different levels of fontification.  You
can define multiple levels by using a list of symbols for @var{keywords}

@item font-lock-constant-face
@vindex font-lock-constant-face
Used (typically) for constant names.

@item font-lock-warning-face
@vindex font-lock-warning-face
Used (typically) for constructs that are peculiar, or that greatly
change the meaning of other text.  For example, this is used for
@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}

@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun

@defun run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions.  It calls each of the hook functions, passing
each of them the arguments @var{args}.
@end defun

51917:3039afbb0746

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a @dfn{mode hook} named
@code{@var{modename}-mode-hook}.  The major mode command should run that
hook, with @code{run-mode-hooks}, as the very last thing it
does.  @xref{Hooks}.

@item
The major mode command may start by calling some other major mode
command (called the @dfn{parent mode}) and then alter some of its
settings.  A mode that does this is called a @dfn{derived mode}.  The
recommended way to define one is to use @code{define-derived-mode},
but this is not required.  Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
(Using @code{define-derived-mode} does this automatically.) 

@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).

  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
@end group
@end smallexample

  This was formerly the complete major mode function definition for Text mode:

@smallexample
@group
(defun text-mode ()
  "Major mode for editing text intended for humans to read...

  (setq indent-line-function 'indent-relative-maybe)
@end group
@group
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
                                    ;   @r{customize the mode with a hook.}
@end group
@end smallexample

@cindex @file{lisp-mode.el}

  (lisp-mode-variables t)                ; @r{This defines various variables.}
@end group
@group
  (setq imenu-case-fold-search t)
  (set-syntax-table lisp-mode-syntax-table)
  (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
                                         ;   @r{hook to customize the mode.}
@end group
@end smallexample

@node Auto Major Mode

minor modes in effect.

  Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs.  Minor mode
keymaps make this easier than it used to be.

@defvar minor-mode-list
The value of this variable is a list of all minor mode commands.
@end defvar

@menu
* Minor Mode Conventions::      Tips for writing a minor mode.
* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
* Defining Minor Modes::        A convenient facility for defining minor modes.

  The macro @code{define-minor-mode} offers a convenient way of
implementing a mode in one self-contained definition.  It supports only
buffer-local minor modes, not global ones.

@defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]]
@tindex define-minor-mode
This macro defines a new minor mode whose name is @var{mode} (a
symbol).  It defines a command named @var{mode} to toggle the minor
mode, with @var{doc} as its documentation string.  It also defines a
variable named @var{mode}, which is set to @code{t} or @code{nil} by
enabling or disabling the mode.  The variable is initialized to
@var{init-value}.

The string @var{lighter} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
in the mode line.

The optional argument @var{keymap} specifies the keymap for the minor mode.
It can be a variable name, whose value is the keymap, or it can be an alist
specifying bindings in this form:

@example
(@var{key-sequence} . @var{definition})
@end example

The @var{keyword-args} consist of keywords followed by corresponding
values.  A few keywords have special meanings:

@table @code
@item :global @var{global}
If non-@code{nil} specifies that the minor mode should be global.
By default, minor modes are buffer-local.

@item :init-value @var{init-value}
This is equivalent to specifying @var{init-value} positionally.

@item :lighter @var{lighter}
This is equivalent to specifying @var{lighter} positionally.

@item :keymap @var{keymap}
This is equivalent to specifying @var{keymap} positionally.
@end table

Any other keyword arguments are passed passed directly to the
@code{defcustom} generated for the variable @var{mode}.

The command named @var{mode} finishes by executing the @var{body} forms,
if any, after it has performed the standard actions such as setting
the variable named @var{mode}.
@end defmac

@findex easy-mmode-define-minor-mode
  The name @code{easy-mmode-define-minor-mode} is an alias
for this macro.

  Here is an example of using @code{define-minor-mode}:

@smallexample
(define-minor-mode hungry-mode

 ;; The minor mode bindings.
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t))))
 :group 'hunger)
@end smallexample

@noindent
This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
mode is enabled.  It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  It puts the variable
@code{hungry-mode} into custom group @code{hunger}.  There are no
@var{body} forms---many minor modes don't need any.

  Here's an equivalent way to write it:

@smallexample
(define-minor-mode hungry-mode
  "Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 :initial-value nil
 ;; The indicator for the mode line.
 :lighter " Hungry"
 ;; The minor mode bindings.
 :keymap
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t))))
 :group 'hunger)
@end smallexample

@node Mode Line Format
@section Mode Line Format
@cindex mode line

;; @r{Highlight occurrences of @samp{fubar},}
;; @r{using the face which is the value of @code{fubar-face}.}
("fubar" . fubar-face)
@end example

The value of @var{facename} is usually a face name (a symbol), but it
can also be a list of the form

@example
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@end example

to specify various text properties to put on the text that matches.
If you do this, be sure to add the other text property names that you
set in this way to the value of @code{font-lock-extra-managed-props}
so that the properties will also be cleared out when they are no longer
appropriate.

@item (@var{matcher} . @var{highlighter})
In this kind of element, @var{highlighter} is a list
which specifies how to highlight matches found by @var{matcher}.
It has the form

but not too large so that refontification becomes slow.  Typical values
are @code{mark-defun} for programming modes or @code{mark-paragraph} for
textual modes.
@end defvar

@defvar font-lock-extra-managed-props
Additional properties (other than @code{face}) that are being managed
by Font Lock mode.  Font Lock mode normally manages only the @code{face}
property; if you want it to manage others as well, you must specify
them in a @var{facename} in @code{font-lock-keywords} as well as adding
them to this list.
@end defvar

@node Levels of Font Lock
@subsection Levels of Font Lock

  Many major modes offer three different levels of fontification.  You
can define multiple levels by using a list of symbols for @var{keywords}

@item font-lock-constant-face
@vindex font-lock-constant-face
Used (typically) for constant names.

@item font-locl-preprocessor-face
@vindex font-locl-preprocessor-face
Used (typically) for preprocessor commands.

@item font-lock-warning-face
@vindex font-lock-warning-face
Used (typically) for constructs that are peculiar, or that greatly
change the meaning of other text.  For example, this is used for
@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}

@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun

@defun run-mode-hooks &rest hookvars
Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
macro.
@end defun

@defmac delay-mode-hooks body...
This macro executes the @var{body} forms but defers all calls to
@code{run-mode-hooks} within them until the end of @var{body}.
This macro enables a derived mode to arrange not to run
its parent modes' mode hooks until the end.
@end defmac

@defun run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions.  It calls each of the hook functions, passing
each of them the arguments @var{args}.
@end defun