@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
Text mode except that it provides two additional commands. Its
definition is distinct from that of Text mode, but uses that of Text mode.
+ Even if the new mode is not an obvious derivative of any other mode,
+it is convenient to use @code{define-derived-mode} with a @code{nil}
+parent argument, since it automatically enforces the most important
+coding conventions for you.
+
Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands). In such cases, the
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. Please follow these conventions when you
-define a new major mode:
+define a new major mode.
+
+ This list of conventions is only partial, because each major mode
+should aim for consistency in general with other Emacs major modes.
+This makes Emacs as a whole more coherent. It is impossible to list
+here all the possible points where this issue might come up; if the
+Emacs developers point out an area where your major mode deviates from
+the usual conventions, please make it compatible.
@itemize @bullet
@item
have names that start with the major mode name (or with an abbreviation
of it if the name is long). @xref{Coding Conventions}.
+@item
+In a major mode for editing some kind of structured text, such as a
+programming language, indentation of text according to structure is
+probably useful. So the mode should set @code{indent-line-function}
+to a suitable function, and probably customize other variables
+for indentation.
+
@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
text can reasonably redefine letters and other printing characters as
editing commands. Dired and Rmail both do this.
+@item
+Major modes must not define @key{RET} to do anything other than insert
+a newline. The command to insert a newline and then indent is
+@kbd{C-j}. Please keep this distinction uniform for all major modes.
+
+@item
+Major modes should not alter options that are primary a matter of user
+preference, such as whether Auto-Fill mode is enabled. Leave this to
+each user to decide. However, a major mode should customize other
+variables so that Auto-Fill mode will work usefully @emph{if} the user
+decides to use it.
+
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
would affect buffers that do not use this mode. It is undesirable for a
mode to have such global effects. @xref{Buffer-Local Variables}.
-With rare exceptions, the only reasonable way to use use
+With rare exceptions, the only reasonable way to use
@code{make-variable-buffer-local} in a Lisp package is for a variable
which is used only within that package. Using it on a variable used by
other packages would interfere with them.
mode specification error}, followed by the original error message.
@end deffn
-@defopt enable-local-variables
-This variable controls processing of local variables lists in files
-being visited. A value of @code{t} means process the local variables
-lists unconditionally; @code{nil} means ignore them; anything else means
-ask the user what to do for each file. The default value is @code{t}.
-@end defopt
-
-@defvar ignored-local-variables
-This variable holds a list of variables that should not be
-set by a file's local variables list. Any value specified
-for one of these variables is ignored.
-@end defvar
-
-In addition to this list, any variable whose name has a non-@code{nil}
-@code{risky-local-variable} property is also ignored.
-
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in local variables
-lists in files being visited. A value of @code{t} means process them
-unconditionally; @code{nil} means ignore them; anything else means ask
-the user what to do for each file. The default value is @code{maybe}.
-@end defopt
-
@defun set-auto-mode
@cindex visited file mode
This function selects the major mode that is appropriate for the
not indicate which major mode to use.
@end defvar
-@defun hack-local-variables &optional force
-This function parses, and binds or evaluates as appropriate, any local
-variables specified by the contents of the current buffer.
-
-The handling of @code{enable-local-variables} documented for
-@code{normal-mode} actually takes place here. The argument @var{force}
-usually comes from the argument @var{find-file} given to
-@code{normal-mode}.
-@end defun
-
@node Mode Help
@subsection Getting Help about a Major Mode
@cindex mode help
(define-key hypertext-mode-map
[down-mouse-3] 'do-hyper-link)
@end example
+
+Do not write an @code{interactive} spec in the definition;
+@code{define-derived-mode} does that automatically.
@end defmac
@node Minor Modes
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
-* Easy-Mmode:: A convenient facility for defining minor modes.
+* Defining Minor Modes:: A convenient facility for defining minor modes.
@end menu
@node Minor Mode Conventions
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
characters are reserved for major modes.)
-@node Easy-Mmode
-@subsection Easy-Mmode
+@node Defining Minor Modes
+@subsection Defining Minor Modes
- The easy-mmode package provides a convenient way of implementing a
-mode in one self-contained definition. It currently supports only
+ 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 easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
-@tindex easy-mmode-define-minor-mode
+@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}.
-This macro defines a command named @var{mode} which toggles the minor
-mode, and has @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
@end example
@end defmac
- Here is an example of using @code{easy-mmode-define-minor-mode}:
+ Here is an example of using @code{define-minor-mode}:
@smallexample
-(easy-mmode-define-minor-mode hungry-mode
+(define-minor-mode hungry-mode
"Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
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
window is scrolled. @code{header-line-format} is used likewise for
header lines.
- The mode line and header line of a window are normally updated
-whenever a different buffer is shown in the window, or when the buffer's
-modified-status changes from @code{nil} to @code{t} or vice-versa. If
-you modify any of the variables referenced by @code{mode-line-format}
-(@pxref{Mode Line Variables}), or any other variables and data
-structures that affect how text is displayed (@pxref{Display}), you may
-want to force an update of the mode line so as to display the new
-information or display it in the new way.
+ For efficiency, Emacs does not recompute the mode line and header
+line of a window in every redisplay. It does so when circumstances
+appear to call for it---for instance, if you change the window
+configuration, switch buffers, narrow or widen the buffer, scroll, or
+change the buffer's modification status. If you modify any of the
+variables referenced by @code{mode-line-format} (@pxref{Mode Line
+Variables}), or any other variables and data structures that affect
+how text is displayed (@pxref{Display}), you may want to force an
+update of the mode line so as to display the new information or
+display it in the new way.
@c Emacs 19 feature
@defun force-mode-line-update
Force redisplay of the current buffer's mode line and header line.
+The next redisplay will update the mode line and header line based on
+the latest values of all relevant variables.
+
+This function also forces recomputation of the menu bar menus
+and the frame title.
@end defun
The mode line is usually displayed in inverse video; see
@code{mode-line-inverse-video} in @ref{Inverse Video}.
+ A window that is just one line tall does not display either a mode
+line or a header line, even if the variables call for one. A window
+that is two lines tall cannot display both a mode line and a header
+line at once; if the variables call for both, only the mode line
+actually appears.
+
@menu
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
@code{mode-line-format} were changed to use them.
@defvar mode-line-mule-info
-@tindex mode-line-mule-info
This variable holds the value of the mode-line construct that displays
information about the language environment, buffer coding system, and
current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-frame-identification
-@tindex mode-line-frame-identification
This variable identifies the current frame. The default value is
@code{" "} if you are using a window system which can show multiple
frames, or @code{"-%F "} on an ordinary terminal which shows only one
@group
" %[("
;; @r{@code{mode-line-mode-name} is a function}
- ;; @r{that copies the mode name and adds text
+ ;; @r{that copies the mode name and adds text}
;; @r{properties to make it mouse-sensitive.}
(:eval (mode-line-mode-name))
mode-line-process
@defvar header-line-format
This variable, local in every buffer, specifies how to display the
header line, for windows displaying the buffer. The format of the value
-is the same as for @code{mode-line-format} (@xref{Mode Line Data}).
+is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
@end defvar
@tindex default-header-line-format
@code{imenu-extract-index-name-function}:
@defvar imenu-prev-index-position-function
-If this variable is non-@code{nil}, its value should be a funtion that
+If this variable is non-@code{nil}, its value should be a function that
finds the next ``definition'' to put in the buffer index, scanning
backward in the buffer from point. It should return @code{nil} if it
doesn't find another ``definition'' before point. Otherwise it shuould
it finds using @code{font-lock-keyword-face}.
When @var{function} is called, it receives one argument, the limit of
-the search. It should return non-@code{nil} if it succeeds, and set the
-match data to describe the match that was found.
+the search; it should searching at point, and not search beyond the
+limit. It should return non-@code{nil} if it succeeds, and set the
+match data to describe the match that was found. Returning @code{nil}
+indicates failure of the search.
+
+Fontification will call @var{function} repeatedly with the same limit,
+and with point where the previous invocation left it, until
+@var{function} fails. On failure, @var{function} need not reset point
+in any particular way.
@item (@var{matcher} . @var{match})
In this kind of element, @var{matcher} is either a regular
If @var{laxmatch} is non-@code{nil}, it means there should be no error
if there is no subexpression numbered @var{subexp} in @var{matcher}.
+Obviously, fontification of the subexpression numbered @var{subexp} will
+not occur. However, fontification of other subexpressions (and other
+regexps) will continue. If @var{laxmatch} is @code{nil}, and the
+specified subexpression is missing, then an error is signalled which
+terminates search-based fontification.
Here are some examples of elements of this kind, and what they do:
these functions are called with arguments or their values are used in
some way. You can use @code{add-hook} to add a function to the list,
but you must take care in writing the function. (A few of these
-variables are actually normal hooks which were named before we
-established the convention of using @samp{-hook} for them.)
+variables, notably those ending in @samp{-hooks}, are actually
+normal hooks which were named before we established the convention of
+using @samp{-hook} for them.)
If the variable's name ends in @samp{-function}, then its value
is just a single function, not a list of functions.
argument @var{append} is non-@code{nil}, the new hook function goes at
the end of the hook list and will be executed last.
-If @var{local} is non-@code{nil}, that says to make the new hook
-function buffer-local in the current buffer. Before you can do this, you must
-make the hook itself buffer-local by calling @code{make-local-hook}
-(@strong{not} @code{make-local-variable}). If the hook itself is not
-buffer-local, then the value of @var{local} makes no difference---the
-hook function is always global.
+If @var{local} is non-@code{nil}, that says to add @var{function}
+to the buffer-local hook list instead of to the global hook list.
@end defun
@defun remove-hook hook function &optional local
If @var{local} is non-@code{nil}, that says to remove @var{function}
from the buffer-local hook list instead of from the global hook list.
-If the hook variable itself is not buffer-local, then the value of
-@var{local} makes no difference.
-@end defun
-
-@defun make-local-hook hook
-This function makes the hook variable @code{hook} buffer-local in the
-current buffer. When a hook variable is buffer-local, it can have
-buffer-local and global hook functions, and @code{run-hooks} runs all of
-them.
-
-This function works by adding @code{t} as an element of the buffer-local
-value. That serves as a flag to use the hook functions listed in the default
-value of the hook variable, as well as those listed in the buffer-local value.
-Since @code{run-hooks} understands this flag, @code{make-local-hook}
-works with all normal hooks. It works for only some non-normal
-hooks---those whose callers have been updated to understand this meaning
-of @code{t}.
-
-Do not use @code{make-local-variable} directly for hook variables; it is
-not sufficient.
@end defun
HCoop / bpt / emacs.git / blobdiff