@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/modes
@node Modes, Documentation, Keymaps, Top
to be called on a particular occasion by an existing program. Emacs
provides hooks for the sake of customization. Most often, hooks are set
up in the init file (@pxref{Init File}), but Lisp programs can set them also.
-@xref{Standard Hooks}, for a list of standard hook variables.
+@xref{Standard Hooks}, for a list of some standard hook variables.
@cindex normal hook
Most of the hooks in Emacs are @dfn{normal hooks}. These variables
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
+* Mode Hooks:: Hooks run at the end of major mode commands.
+* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
-* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
@end menu
@code{special} modes, Fundamental mode is used instead. Modes such as
Dired, Rmail, and Buffer List use this feature.
+The function @code{view-buffer} does not enable View mode in buffers
+whose mode-class is special, because such modes usually provide their
+own View-like bindings.
+
The @code{define-derived-mode} macro automatically marks the derived
mode as special if the parent mode is special. Special mode is a
convenient parent for such modes to inherit from; @xref{Basic Major
mode no parent. Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.
-The argument @var{docstring} specifies the documentation string for
-the new mode. @code{define-derived-mode} adds some general
-information about the mode's hook, followed by the mode's keymap, at
-the end of this docstring. If you omit @var{docstring},
+The argument @var{docstring} specifies the documentation string for the
+new mode. @code{define-derived-mode} adds some general information
+about the mode's hook, followed by the mode's keymap, at the end of this
+documentation string. If you omit @var{docstring},
@code{define-derived-mode} generates a documentation string.
The @var{keyword-args} are pairs of keywords and values. The values
@deffn Command special-mode
Special mode is a basic major mode for buffers containing text that is
-produced specially by Emacs, rather than from a file. Major modes
-derived from Special mode are given a @code{mode-class} property of
-@code{special} (@pxref{Major Mode Conventions}).
+produced specially by Emacs, rather than directly from a file. Major
+modes derived from Special mode are given a @code{mode-class} property
+of @code{special} (@pxref{Major Mode Conventions}).
Special mode sets the buffer to read-only. Its keymap defines several
common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn
-@cindex tables of data
-@deffn Command tabulated-list-mode
-Tabulated List mode is another mode that derives from Special mode. It
-displays tabulated data, i.e. a series of rows and columns, where each
-row represents a particular entry, whose properties are displayed in the
-various columns. It provides a general mechanism for sorting on
-columns. You can use Tabulated List mode as the basis for other modes
-that need to display lists. For example, the @samp{*Packages*} buffer
-uses this (@pxref{Packages,,, emacs, The GNU Emacs Manual}). The
-documentation of the @code{tabulated-list-mode} function explains what
-you need to do to use it. At a minimum, specify the column format via
-the @code{tabulated-list-format} variable.
-@end deffn
-
-@node Generic Modes
-@subsection Generic Modes
-@cindex generic mode
-
- @dfn{Generic modes} are simple major modes with basic support for
-comment syntax and Font Lock mode. To define a generic mode, use the
-macro @code{define-generic-mode}. See the file @file{generic-x.el}
-for some examples of the use of @code{define-generic-mode}.
-
-@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
-This macro defines a generic mode command named @var{mode} (a symbol,
-not quoted). The optional argument @var{docstring} is the
-documentation for the mode command. If you do not supply it,
-@code{define-generic-mode} generates one by default.
-
-The argument @var{comment-list} is a list in which each element is
-either a character, a string of one or two characters, or a cons cell.
-A character or a string is set up in the mode's syntax table as a
-``comment starter.'' If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
-(Use @code{nil} for the latter if you want comments to end at the end
-of the line.) Note that the syntax table mechanism has limitations
-about what comment starters and enders are actually possible.
-@xref{Syntax Tables}.
-
-The argument @var{keyword-list} is a list of keywords to highlight
-with @code{font-lock-keyword-face}. Each keyword should be a string.
-Meanwhile, @var{font-lock-list} is a list of additional expressions to
-highlight. Each element of this list should have the same form as an
-element of @code{font-lock-keywords}. @xref{Search-based
-Fontification}.
-
-The argument @var{auto-mode-list} is a list of regular expressions to
-add to the variable @code{auto-mode-alist}. They are added by the execution
-of the @code{define-generic-mode} form, not by expanding the macro call.
-
-Finally, @var{function-list} is a list of functions for the mode
-command to call for additional setup. It calls these functions just
-before it runs the mode hook variable @code{@var{mode}-hook}.
-@end defmac
+ In addition, modes for buffers of tabulated data can inherit from
+Tabulated List mode, which is in turn derived from Special mode.
+@xref{Tabulated List Mode}.
@node Mode Hooks
@subsection Mode Hooks
very end of every properly-written major mode command.
@end defvar
+@node Tabulated List Mode
+@subsection Tabulated List mode
+@cindex Tabulated List mode
+
+ Tabulated List mode is a major mode for displaying tabulated data,
+i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
+text with its contents divided into columns. Tabulated List mode
+provides facilities for pretty-printing rows and columns, and sorting
+the rows according to the values in each column. It is derived from
+Special mode (@pxref{Basic Major Modes}).
+
+ Tabulated List mode is intended to be used as a parent mode by a more
+specialized major mode. Examples include Process Menu mode
+(@pxref{Process Information}) and Package Menu mode (@pxref{Package
+Menu,,, emacs, The GNU Emacs Manual}).
+
+@findex tabulated-list-mode
+ Such a derived mode should use @code{define-derived-mode} in the usual
+way, specifying @code{tabulated-list-mode} as the second argument
+(@pxref{Derived Modes}). The body of the @code{define-derived-mode}
+form should specify the format of the tabulated data, by assigning
+values to the variables documented below; then, it should call the
+function @code{tabulated-list-init-header} to initialize the header
+line.
+
+ The derived mode should also define a @dfn{listing command}. This,
+not the mode command, is what the user calls (e.g.@: @kbd{M-x
+list-processes}). The listing command should create or switch to a
+buffer, turn on the derived mode, specify the tabulated data, and
+finally call @code{tabulated-list-print} to populate the buffer.
+
+@defvar tabulated-list-format
+This buffer-local variable specifies the format of the Tabulated List
+data. Its value should be a vector. Each element of the vector
+represents a data column, and should be a list @code{(@var{name}
+@var{width} @var{sort})}, where
+
+@itemize
+@item
+@var{name} is the column's name (a string).
+
+@item
+@var{width} is the width to reserve for the column (an integer). This
+is meaningless for the last column, which runs to the end of each line.
+
+@item
+@var{sort} specifies how to sort entries by the column. If @code{nil},
+the column cannot be used for sorting. If @code{t}, the column is
+sorted by comparing string values. Otherwise, this should be a
+predicate function for @code{sort} (@pxref{Rearrangement}), which
+accepts two arguments with the same form as the elements of
+@code{tabulated-list-entries} (see below).
+@end itemize
+@end defvar
+
+@defvar tabulated-list-entries
+This buffer-local variable specifies the entries displayed in the
+Tabulated List buffer. Its value should be either a list, or a
+function.
+
+If the value is a list, each list element corresponds to one entry, and
+should have the form @w{@code{(@var{id} @var{contents})}}, where
+
+@itemize
+@item
+@var{id} is either @code{nil}, or a Lisp object that identifies the
+entry. If the latter, the cursor stays on the ``same'' entry when
+re-sorting entries. Comparison is done with @code{equal}.
+
+@item
+@var{contents} is a vector with the same number of elements as
+@code{tabulated-list-format}. Each vector element is either a string,
+which is inserted into the buffer as-is, or a list @code{(@var{label}
+. @var{properties})}, which means to insert a text button by calling
+@code{insert-text-button} with @var{label} and @var{properties} as
+arguments (@pxref{Making Buttons}).
+
+There should be no newlines in any of these strings.
+@end itemize
+
+Otherwise, the value should be a function which returns a list of the
+above form when called with no arguments.
+@end defvar
+
+@defvar tabulated-list-revert-hook
+This normal hook is run prior to reverting a Tabulated List buffer. A
+derived mode can add a function to this hook to recompute
+@code{tabulated-list-entries}.
+@end defvar
+
+@defvar tabulated-list-printer
+The value of this variable is the function called to insert an entry at
+point, including its terminating newline. The function should accept
+two arguments, @var{id} and @var{contents}, having the same meanings as
+in @code{tabulated-list-entries}. The default value is a function which
+inserts an entry in a straightforward way; a mode which uses Tabulated
+List mode in a more complex way can specify another function.
+@end defvar
+
+@defvar tabulated-list-sort-key
+The value of this variable specifies the current sort key for the
+Tabulated List buffer. If it is @code{nil}, no sorting is done.
+Otherwise, it should have the form @code{(@var{name} . @var{flip})},
+where @var{name} is a string matching one of the column names in
+@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
+to invert the sort order.
+@end defvar
+
+@defun tabulated-list-init-header
+This function computes and sets @code{header-line-format} for the
+Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
+the header line to allow sort entries by clicking on column headers.
+
+Modes derived from Tabulated List mode should call this after setting
+the above variables (in particular, only after setting
+@code{tabulated-list-format}).
+@end defun
+
+@defun tabulated-list-print &optional remember-pos
+This function populates the current buffer with entries. It should be
+called by the listing command. It erases the buffer, sorts the entries
+specified by @code{tabulated-list-entries} according to
+@code{tabulated-list-sort-key}, then calls the function specified by
+@code{tabulated-list-printer} to insert each entry.
+
+If the optional argument @var{remember-pos} is non-@code{nil}, this
+function looks for the @var{id} element on the current line, if any, and
+tries to move to that entry after all the entries are (re)inserted.
+@end defun
+
+@node Generic Modes
+@subsection Generic Modes
+@cindex generic mode
+
+ @dfn{Generic modes} are simple major modes with basic support for
+comment syntax and Font Lock mode. To define a generic mode, use the
+macro @code{define-generic-mode}. See the file @file{generic-x.el}
+for some examples of the use of @code{define-generic-mode}.
+
+@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
+This macro defines a generic mode command named @var{mode} (a symbol,
+not quoted). The optional argument @var{docstring} is the
+documentation for the mode command. If you do not supply it,
+@code{define-generic-mode} generates one by default.
+
+The argument @var{comment-list} is a list in which each element is
+either a character, a string of one or two characters, or a cons cell.
+A character or a string is set up in the mode's syntax table as a
+``comment starter.'' If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+(Use @code{nil} for the latter if you want comments to end at the end
+of the line.) Note that the syntax table mechanism has limitations
+about what comment starters and enders are actually possible.
+@xref{Syntax Tables}.
+
+The argument @var{keyword-list} is a list of keywords to highlight
+with @code{font-lock-keyword-face}. Each keyword should be a string.
+Meanwhile, @var{font-lock-list} is a list of additional expressions to
+highlight. Each element of this list should have the same form as an
+element of @code{font-lock-keywords}. @xref{Search-based
+Fontification}.
+
+The argument @var{auto-mode-list} is a list of regular expressions to
+add to the variable @code{auto-mode-alist}. They are added by the execution
+of the @code{define-generic-mode} form, not by expanding the macro call.
+
+Finally, @var{function-list} is a list of functions for the mode
+command to call for additional setup. It calls these functions just
+before it runs the mode hook variable @code{@var{mode}-hook}.
+@end defmac
+
@node Example Major Modes
@subsection Major Mode Examples
@var{place} can also be a cons @code{(@var{get} . @var{set})},
where @var{get} is an expression that returns the current state,
and @var{set} is a function of one argument (a state) that sets it.
+
+@item :after-hook @var{after-hook}
+This defines a single Lisp form which is evaluated after the mode hooks
+have run. It should not be quoted.
@end table
Any other keyword arguments are passed directly to the
@code{defcustom} generated for the variable @var{mode}.
-The command named @var{mode} first performs the standard actions such
-as setting the variable named @var{mode} and then executes the
-@var{body} forms, if any. It finishes by running the mode hook
-variable @code{@var{mode}-hook}.
+The command named @var{mode} first performs the standard actions such as
+setting the variable named @var{mode} and then executes the @var{body}
+forms, if any. It then runs the mode hook variable
+@code{@var{mode}-hook} and finishes by evaluating any form in
+@code{:after-hook}.
@end defmac
The initial value must be @code{nil} except in cases where (1) the
optionally bound to @code{desktop-save-buffer}.
@end defvar
-@ignore
- Local Variables:
- fill-column: 72
- End:
-@end ignore
HCoop / bpt / emacs.git / blobdiff