1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter
58 A "gutter" is a rectangle displayed along one edge of a frame. It
59 can contain arbitrary text or graphics. It could be considered a
60 generalization of a toolbar, although toolbars are not currently
61 implemented using gutters.
63 In XEmacs, a gutter can be displayed along any of the four edges of
64 the frame, and two or more different edges can be displaying gutters
65 simultaneously. The contents, thickness, and visibility of the gutters
66 can be controlled separately, and the values can be per-buffer,
67 per-frame, etc., using specifiers (*note Specifiers::).
69 Normally, there is one gutter displayed in a frame. Usually, this is
70 the default gutter, containing buffer tabs, but modes cab override this
71 and substitute their own gutter. This default gutter is usually
72 positioned along the top of the frame, but this can be changed using
73 `set-default-gutter-position'.
75 Note that, for each of the gutter properties (contents, thickness,
76 and visibility), there is a separate specifier for each of the four
77 gutter positions (top, bottom, left, and right), and an additional
78 specifier for the "default" gutter, i.e. the gutter whose position is
79 controlled by `set-default-gutter-position'. The way this works is
80 that `set-default-gutter-position' arranges things so that the
81 appropriate position-specific specifiers for the default position
82 inherit from the corresponding default specifiers. That way, if the
83 position-specific specifier does not give a value (which it usually
84 doesn't), then the value from the default specifier applies. If you
85 want to control the default gutter, you just change the default
86 specifiers, and everything works. A package such as VM that wants to
87 put its own gutter in a different location from the default just sets
88 the position-specific specifiers, and if the user sets the default
89 gutter to the same position, it will just not be visible.
92 File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter
97 - Function: make-gutter-specifier spec-list
98 Return a new `gutter' specifier object with the given specification
99 list. SPEC-LIST can be a list of specifications (each of which is
100 a cons of a locale and a list of instantiators), a single
101 instantiator, or a list of instantiators. *Note Specifiers::, for
102 more information about specifiers.
104 Gutter specifiers are used to specify the format of a gutter. The
105 values of the variables `default-gutter', `top-gutter',
106 `left-gutter', `right-gutter', and `bottom-gutter' are always
109 Valid gutter instantiators are called "gutter descriptors" and are
110 either strings or property-lists of strings. See `default-gutter'
111 for a description of the exact format.
113 - Function: make-gutter-size-specifier spec-list
114 Return a new `gutter-size' specifier object with the given spec
115 list. SPEC-LIST can be a list of specifications (each of which is
116 a cons of a locale and a list of instantiators), a single
117 instantiator, or a list of instantiators. *Note Specifiers::, for
118 more information about specifiers.
120 Gutter-size specifiers are used to specify the size of a gutter.
121 The values of the variables `default-gutter-size',
122 `top-gutter-size', `left-gutter-size', `right-gutter-size', and
123 `bottom-gutter-size' are always gutter-size specifiers.
125 Valid gutter-size instantiators are either integers or the special
126 symbol `autodetect'. If a gutter-size is set to `autodetect' them
127 the size of the gutter will be adjusted to just accommodate the
128 gutters contents. `autodetect' only works for top and bottom
131 - Function: make-gutter-visible-specifier spec-list
132 Return a new `gutter-visible' specifier object with the given spec
133 list. SPEC-LIST can be a list of specifications (each of which is
134 a cons of a locale and a list of instantiators), a single
135 instantiator, or a list of instantiators. *Note Specifiers::, for
136 more information about specifiers.
138 Gutter-visible specifiers are used to specify the visibility of a
139 gutter. The values of the variables `default-gutter-visible-p',
140 `top-gutter-visible-p', `left-gutter-visible-p',
141 `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
142 gutter-visible specifiers.
144 Valid gutter-visible instantiators are `t', `nil' or a list of
145 symbols. If a gutter-visible instantiator is set to a list of
146 symbols, and the corresponding gutter specification is a
147 property-list strings, then elements of the gutter specification
148 will only be visible if the corresponding symbol occurs in the
149 gutter-visible instantiator.
152 File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter
154 Gutter Descriptor Format
155 ========================
157 The contents of a gutter are specified using a "gutter descriptor".
158 The format of a gutter descriptor is a list of "gutter button
159 descriptors". Each gutter button descriptor is a vector in one of the
162 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
164 * `[:style 2D-OR-3D]'
166 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
168 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
170 Optionally, one of the gutter button descriptors may be `nil'
171 instead of a vector; this signifies the division between the gutter
172 buttons that are to be displayed flush-left, and the buttons to be
173 displayed flush-right.
175 The first vector format above specifies a normal gutter button; the
176 others specify blank areas in the gutter.
178 For the first vector format:
180 * GLYPH-LIST should be a list of one to six glyphs (as created by
181 `make-glyph') or a symbol whose value is such a list. The first
182 glyph, which must be provided, is the glyph used to display the
183 gutter button when it is in the "up" (not pressed) state. The
184 optional second glyph is for displaying the button when it is in
185 the "down" (pressed) state. The optional third glyph is for when
186 the button is disabled. The last three glyphs are for displaying
187 the button in the "up", "down", and "disabled" states,
188 respectively, but are used when the user has called for captioned
189 gutter buttons (using `gutter-buttons-captioned-p'). The function
190 `gutter-make-button-list' is useful in creating these glyph lists.
192 * Even if you do not provide separate down-state and disabled-state
193 glyphs, the user will still get visual feedback to indicate which
194 state the button is in. Buttons in the up-state are displayed
195 with a shadowed border that gives a raised appearance to the
196 button. Buttons in the down-state are displayed with shadows that
197 give a recessed appearance. Buttons in the disabled state are
198 displayed with no shadows, giving a 2-d effect.
200 * If some of the gutter glyphs are not provided, they inherit as
205 DISABLED: disabled -> up
207 CAP-DOWN: cap-down -> cap-up -> down -> up
208 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
210 * The second element FUNCTION is a function to be called when the
211 gutter button is activated (i.e. when the mouse is released over
212 the gutter button, if the press occurred in the gutter). It can
213 be any form accepted by `call-interactively', since this is how it
216 * The third element ENABLED-P specifies whether the gutter button is
217 enabled (disabled buttons do nothing when they are activated, and
218 are displayed differently; see above). It should be either a
219 boolean or a form that evaluates to a boolean.
221 * The fourth element HELP, if non-`nil', should be a string. This
222 string is displayed in the echo area when the mouse passes over the
225 For the other vector formats (specifying blank areas of the gutter):
227 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
228 whether the area is displayed with shadows (giving it a raised,
229 3-d appearance) or without shadows (giving it a flat appearance).
231 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
232 area. If omitted, it defaults to a device-specific value (8
233 pixels for X devices).
235 - Function: gutter-make-button-list up &optional down disabled cap-up
236 cap-down cap-disabled
237 This function calls `make-glyph' on each arg and returns a list of
238 the results. This is useful for setting the first argument of a
239 gutter button descriptor (typically, the result of this function
240 is assigned to a symbol, which is specified as the first argument
241 of the gutter button descriptor).
243 - Function: check-gutter-button-syntax button &optional noerror
244 Verify the syntax of entry BUTTON in a gutter description list.
245 If you want to verify the syntax of a gutter description list as a
246 whole, use `check-valid-instantiator' with a specifier type of
250 File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
255 In order to specify the contents of a gutter, set one of the
256 specifier variables `default-gutter', `top-gutter', `bottom-gutter',
257 `left-gutter', or `right-gutter'. These are specifiers, which means
258 you set them with `set-specifier' and query them with `specifier-specs'
259 or `specifier-instance'. You will get an error if you try to set them
260 using `setq'. The valid instantiators for these specifiers are gutter
261 descriptors, as described above. *Note Specifiers::, for more
264 Most of the time, you will set `default-gutter', which allows the
265 user to choose where the gutter should go.
267 - Specifier: default-gutter
268 The position of this gutter is specified in the function
269 `default-gutter-position'. If the corresponding position-specific
270 gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
271 does not specify a gutter in a particular domain, then the value
272 of `default-gutter' in that domain, of any, will be used instead.
274 Note that the gutter at any particular position will not be displayed
275 unless its thickness (width or height, depending on orientation) is
276 non-zero and its visibility status is true. The thickness is controlled
277 by the specifiers `top-gutter-height', `bottom-gutter-height',
278 `left-gutter-width', and `right-gutter-width', and the visibility
279 status is controlled by the specifiers `top-gutter-visible-p',
280 `bottom-gutter-visible-p', `left-gutter-visible-p', and
281 `right-gutter-visible-p' (*note Other Gutter Variables::).
283 - Function: set-default-gutter-position position
284 This function sets the position that the `default-gutter' will be
285 displayed at. Valid positions are the symbols `top', `bottom',
286 `left' and `right'. What this actually does is set the fallback
287 specifier for the position-specific specifier corresponding to the
288 given position to `default-gutter', and set the fallbacks for the
289 other position-specific specifiers to `nil'. It also does the
290 same thing for the position-specific thickness and visibility
291 specifiers, which inherit from one of `default-gutter-height' or
292 `default-gutter-width', and from `default-gutter-visible-p',
293 respectively (*note Other Gutter Variables::).
295 - Function: default-gutter-position
296 This function returns the position that the `default-gutter' will
299 You can also explicitly set a gutter at a particular position. When
300 redisplay determines what to display at a particular position in a
301 particular domain (i.e. window), it first consults the position-specific
302 gutter. If that does not yield a gutter descriptor, the
303 `default-gutter' is consulted if `default-gutter-position' indicates
306 - Specifier: top-gutter
307 Specifier for the gutter at the top of the frame.
309 - Specifier: bottom-gutter
310 Specifier for the gutter at the bottom of the frame.
312 - Specifier: left-gutter
313 Specifier for the gutter at the left edge of the frame.
315 - Specifier: right-gutter
316 Specifier for the gutter at the right edge of the frame.
318 - Function: gutter-specifier-p object
319 This function returns non-`nil' if OBJECT is a gutter specifier.
320 Gutter specifiers are the actual objects contained in the gutter
321 variables described above, and their valid instantiators are
322 gutter descriptors (*note Gutter Descriptor Format::).
325 File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
327 Other Gutter Variables
328 ======================
330 The variables to control the gutter thickness, visibility status, and
331 captioned status are all specifiers. *Note Specifiers::.
333 - Specifier: default-gutter-height
334 This specifies the height of the default gutter, if it's oriented
335 horizontally. The position of the default gutter is specified by
336 the function `set-default-gutter-position'. If the corresponding
337 position-specific gutter thickness specifier (e.g.
338 `top-gutter-height' if `default-gutter-position' is `top') does
339 not specify a thickness in a particular domain (a window or a
340 frame), then the value of `default-gutter-height' or
341 `default-gutter-width' (depending on the gutter orientation) in
342 that domain, if any, will be used instead.
344 - Specifier: default-gutter-width
345 This specifies the width of the default gutter, if it's oriented
346 vertically. This behaves like `default-gutter-height'.
348 Note that `default-gutter-height' is only used when
349 `default-gutter-position' is `top' or `bottom', and
350 `default-gutter-width' is only used when `default-gutter-position' is
353 - Specifier: top-gutter-height
354 This specifies the height of the top gutter.
356 - Specifier: bottom-gutter-height
357 This specifies the height of the bottom gutter.
359 - Specifier: left-gutter-width
360 This specifies the width of the left gutter.
362 - Specifier: right-gutter-width
363 This specifies the width of the right gutter.
365 Note that all of the position-specific gutter thickness specifiers
366 have a fallback value of zero when they do not correspond to the
367 default gutter. Therefore, you will have to set a non-zero thickness
368 value if you want a position-specific gutter to be displayed.
370 - Specifier: default-gutter-visible-p
371 This specifies whether the default gutter is visible. The
372 position of the default gutter is specified by the function
373 `set-default-gutter-position'. If the corresponding
374 position-specific gutter visibility specifier (e.g.
375 `top-gutter-visible-p' if `default-gutter-position' is `top') does
376 not specify a visible-p value in a particular domain (a window or
377 a frame), then the value of `default-gutter-visible-p' in that
378 domain, if any, will be used instead.
380 - Specifier: top-gutter-visible-p
381 This specifies whether the top gutter is visible.
383 - Specifier: bottom-gutter-visible-p
384 This specifies whether the bottom gutter is visible.
386 - Specifier: left-gutter-visible-p
387 This specifies whether the left gutter is visible.
389 - Specifier: right-gutter-visible-p
390 This specifies whether the right gutter is visible.
392 `default-gutter-visible-p' and all of the position-specific gutter
393 visibility specifiers have a fallback value of true.
395 Internally, gutter thickness and visibility specifiers are
396 instantiated in both window and frame domains, for different purposes.
397 The value in the domain of a frame's selected window specifies the
398 actual gutter thickness or visibility that you will see in that frame.
399 The value in the domain of a frame itself specifies the gutter
400 thickness or visibility that is used in frame geometry calculations.
402 Thus, for example, if you set the frame width to 80 characters and
403 the left gutter width for that frame to 68 pixels, then the frame will
404 be sized to fit 80 characters plus a 68-pixel left gutter. If you then
405 set the left gutter width to 0 for a particular buffer (or if that
406 buffer does not specify a left gutter or has a `nil' value specified for
407 `left-gutter-visible-p'), you will find that, when that buffer is
408 displayed in the selected window, the window will have a width of 86 or
409 87 characters - the frame is sized for a 68-pixel left gutter but the
410 selected window specifies that the left gutter is not visible, so it is
411 expanded to take up the slack.
413 - Specifier: gutter-buttons-captioned-p
414 Whether gutter buttons are captioned. This affects which glyphs
415 from a gutter button descriptor are chosen. *Note Gutter
418 You can also reset the gutter to what it was when XEmacs started up.
420 - Constant: initial-gutter-spec
421 The gutter descriptor used to initialize `default-gutter' at
425 File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
427 Common Gutter Widgets
428 =====================
430 A gutter can contain arbitrary text. So, for example, in an Info
431 buffer you could put the title of the current node in the top gutter,
432 and it would not scroll out of view in a long node. (This is an
433 artificial example, since usually the node name is sufficiently
434 descriptive, and Info puts that in the mode line.)
436 A more common use for the gutter is to hold some kind of active
437 widget. The buffer-tab facility, available in all XEmacs frames,
438 creates an array of file-folder-like tabs, which the user can click with
439 the mouse to switch buffers. W3 uses a progress-bar widget in the
440 bottom gutter to give a visual indication of the progress of
441 time-consuming operations like downloading.
445 * Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
446 * Progress Bars:: Visual indication of operation progress.
449 File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
457 File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
465 File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
473 File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
478 _WARNING_: the Drag'n'Drop API is still under development and the
479 interface may change! The current implementation is considered
482 Drag'n'drop is a way to transfer information between multiple
483 applications. To do this several GUIs define their own protocols.
484 Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
485 To catch all these protocols, XEmacs provides a generic API.
487 One prime idea behind the API is to use a data interface that is
488 transparent for all systems. The author thinks that this is best
489 archived by using URL and MIME data, cause any internet enabled system
490 must support these for email already. XEmacs also already provides
491 powerful interfaces to support these types of data (tm and w3).
495 * Supported Protocols:: Which low-level protocols are supported.
496 * Drop Interface:: How XEmacs handles a drop from another application.
497 * Drag Interface:: Calls to initiate a drag from XEmacs.
500 File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
505 The current release of XEmacs only support a small set of Drag'n'drop
506 protocols. Some of these only support limited options available in the
511 * OffiX DND:: A generic X based protocol.
512 * CDE dt:: Common Desktop Environment used on suns.
513 * MSWindows OLE:: Mr. Gates way of live.
514 * Loose ends:: The other protocols.
517 File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
522 _WARNING_: If you compile in OffiX, you may not be able to use
523 multiple X displays successfully. If the two servers are from
524 different vendors, the results may be unpredictable.
526 The OffiX Drag'n'Drop protocol is part of a X API/Widget library
527 created by Cesar Crusius. It is based on X-Atoms and ClientMessage
528 events, and works with any X platform supporting them.
530 OffiX is supported if 'offix is member of the variable
531 dragdrop-protocols, or the feature 'offix is defined.
533 Unfortunately it uses it's own data types. Examples are: File, Files,
534 Exe, Link, URL, MIME. The API tries to choose the right type for the
535 data that is dragged from XEmacs (well, not yet...).
537 XEmacs supports both MIME and URL drags and drops using this API. No
538 application interaction is possible while dragging is in progress.
540 For information about the OffiX project have a look at
541 http://leb.net/~offix/
544 File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
549 CDE stands for Common Desktop Environment. It is based on the Motif
550 widget library. It's drag'n'drop protocol is also an abstraction of the
551 Motif protocol (so it might be possible, that XEmacs will also support
552 the Motif protocol soon).
554 CDE has three different types: file, buffer, and text. XEmacs only
555 uses file and buffer drags. The API will disallow full URL drags, only
556 file method URLs are passed through.
558 Buffer drags are always converted to plain text.
561 File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
566 Only allows file drags and drops.
569 File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
574 The following protocols will be supported soon: Xdnd, Motif, Xde (if
575 I get some specs), KDE OffiX (if KDE can find XEmacs windows).
577 In particular Xdnd will be one of the protocols that can benefit from
578 the XEmacs API, cause it also uses MIME types to encode dragged data.
581 File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
586 For each activated low-level protocol, a internal routine will catch
587 incoming drops and convert them to a dragdrop-drop type misc-user-event.
589 This misc-user-event has its function argument set to
590 `dragdrop-drop-dispatch' and the object contains the data of the drop
591 (converted to URL/MIME specific data). This function will search the
592 variable `experimental-dragdrop-drop-functions' for a function that can
593 handle the dropped data.
595 To modify the drop behavior, the user can modify the variable
596 `experimental-dragdrop-drop-functions'. Each element of this list
597 specifies a possible handler for dropped data. The first one that can
598 handle the data will return `t' and exit. Another possibility is to set
599 a extent-property with the same name. Extents are checked prior to the
602 The customization group `drag-n-drop' shows all variables of user
606 File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
611 This describes the drag API (not implemented yet).
614 File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
616 Major and Minor Modes
617 *********************
619 A "mode" is a set of definitions that customize XEmacs and can be
620 turned on and off while you edit. There are two varieties of modes:
621 "major modes", which are mutually exclusive and used for editing
622 particular kinds of text, and "minor modes", which provide features
623 that users can enable individually.
625 This chapter describes how to write both major and minor modes, how
626 to indicate them in the modeline, and how they run hooks supplied by the
627 user. For related topics such as keymaps and syntax tables, see *Note
628 Keymaps::, and *Note Syntax Tables::.
632 * Major Modes:: Defining major modes.
633 * Minor Modes:: Defining minor modes.
634 * Modeline Format:: Customizing the text that appears in the modeline.
635 * Hooks:: How to use hooks; how to write code that provides hooks.
638 File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
643 Major modes specialize XEmacs for editing particular kinds of text.
644 Each buffer has only one major mode at a time.
646 The least specialized major mode is called "Fundamental mode". This
647 mode has no mode-specific definitions or variable settings, so each
648 XEmacs command behaves in its default manner, and each option is in its
649 default state. All other major modes redefine various keys and options.
650 For example, Lisp Interaction mode provides special key bindings for
651 <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
654 When you need to write several editing commands to help you perform a
655 specialized editing task, creating a new major mode is usually a good
656 idea. In practice, writing a major mode is easy (in contrast to
657 writing a minor mode, which is often difficult).
659 If the new mode is similar to an old one, it is often unwise to
660 modify the old one to serve two purposes, since it may become harder to
661 use and maintain. Instead, copy and rename an existing major mode
662 definition and alter the copy--or define a "derived mode" (*note
663 Derived Modes::). For example, Rmail Edit mode, which is in
664 `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
665 mode except that it provides three additional commands. Its definition
666 is distinct from that of Text mode, but was derived from it.
668 Rmail Edit mode is an example of a case where one piece of text is
669 put temporarily into a different major mode so it can be edited in a
670 different way (with ordinary XEmacs commands rather than Rmail). In
671 such cases, the temporary major mode usually has a command to switch
672 back to the buffer's usual mode (Rmail mode, in this case). You might
673 be tempted to present the temporary redefinitions inside a recursive
674 edit and restore the usual ones when the user exits; but this is a bad
675 idea because it constrains the user's options when it is done in more
676 than one buffer: recursive edits must be exited most-recently-entered
677 first. Using alternative major modes avoids this limitation. *Note
680 The standard XEmacs Lisp library directory contains the code for
681 several major modes, in files including `text-mode.el', `texinfo.el',
682 `lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
683 libraries to see how modes are written. Text mode is perhaps the
684 simplest major mode aside from Fundamental mode. Rmail mode is a
685 complicated and specialized mode.
689 * Major Mode Conventions:: Coding conventions for keymaps, etc.
690 * Example Major Modes:: Text mode and Lisp modes.
691 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
692 * Mode Help:: Finding out how to use a mode.
693 * Derived Modes:: Defining a new major mode based on another major
697 File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
699 Major Mode Conventions
700 ----------------------
702 The code for existing major modes follows various coding conventions,
703 including conventions for local keymap and syntax table initialization,
704 global names, and hooks. Please follow these conventions when you
705 define a new major mode:
707 * Define a command whose name ends in `-mode', with no arguments,
708 that switches to the new mode in the current buffer. This command
709 should set up the keymap, syntax table, and local variables in an
710 existing buffer without changing the buffer's text.
712 * Write a documentation string for this command that describes the
713 special commands available in this mode. `C-h m'
714 (`describe-mode') in your mode will display this string.
716 The documentation string may include the special documentation
717 substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
718 enable the documentation to adapt automatically to the user's own
719 key bindings. *Note Keys in Documentation::.
721 * The major mode command should start by calling
722 `kill-all-local-variables'. This is what gets rid of the local
723 variables of the major mode previously in effect.
725 * The major mode command should set the variable `major-mode' to the
726 major mode command symbol. This is how `describe-mode' discovers
727 which documentation to print.
729 * The major mode command should set the variable `mode-name' to the
730 "pretty" name of the mode, as a string. This appears in the mode
733 * Since all global names are in the same name space, all the global
734 variables, constants, and functions that are part of the mode
735 should have names that start with the major mode name (or with an
736 abbreviation of it if the name is long). *Note Style Tips::.
738 * The major mode should usually have its own keymap, which is used
739 as the local keymap in all buffers in that mode. The major mode
740 function should call `use-local-map' to install this local map.
741 *Note Active Keymaps::, for more information.
743 This keymap should be kept in a global variable named
744 `MODENAME-mode-map'. Normally the library that defines the mode
747 * The mode may have its own syntax table or may share one with other
748 related modes. If it has its own syntax table, it should store
749 this in a variable named `MODENAME-mode-syntax-table'. *Note
752 * The mode may have its own abbrev table or may share one with other
753 related modes. If it has its own abbrev table, it should store
754 this in a variable named `MODENAME-mode-abbrev-table'. *Note
757 * Use `defvar' to set mode-related variables, so that they are not
758 reinitialized if they already have a value. (Such reinitialization
759 could discard customizations made by the user.)
761 * To make a buffer-local binding for an Emacs customization
762 variable, use `make-local-variable' in the major mode command, not
763 `make-variable-buffer-local'. The latter function would make the
764 variable local to every buffer in which it is subsequently set,
765 which would affect buffers that do not use this mode. It is
766 undesirable for a mode to have such global effects. *Note
767 Buffer-Local Variables::.
769 It's ok to use `make-variable-buffer-local', if you wish, for a
770 variable used only within a single Lisp package.
772 * Each major mode should have a "mode hook" named
773 `MODENAME-mode-hook'. The major mode command should run that
774 hook, with `run-hooks', as the very last thing it does. *Note
777 * The major mode command may also run the hooks of some more basic
778 modes. For example, `indented-text-mode' runs `text-mode-hook' as
779 well as `indented-text-mode-hook'. It may run these other hooks
780 immediately before the mode's own hook (that is, after everything
781 else), or it may run them earlier.
783 * If something special should be done if the user switches a buffer
784 from this mode to any other major mode, the mode can set a local
785 value for `change-major-mode-hook'.
787 * If this mode is appropriate only for specially-prepared text, then
788 the major mode command symbol should have a property named
789 `mode-class' with value `special', put on as follows:
791 (put 'funny-mode 'mode-class 'special)
793 This tells XEmacs that new buffers created while the current
794 buffer has Funny mode should not inherit Funny mode. Modes such
795 as Dired, Rmail, and Buffer List use this feature.
797 * If you want to make the new mode the default for files with certain
798 recognizable names, add an element to `auto-mode-alist' to select
799 the mode for those file names. If you define the mode command to
800 autoload, you should add this element in the same file that calls
801 `autoload'. Otherwise, it is sufficient to add the element in the
802 file that contains the mode definition. *Note Auto Major Mode::.
804 * In the documentation, you should provide a sample `autoload' form
805 and an example of how to add to `auto-mode-alist', that users can
806 include in their `.emacs' files.
808 * The top-level forms in the file defining the mode should be
809 written so that they may be evaluated more than once without
810 adverse consequences. Even if you never load the file more than
811 once, someone else will.
813 - Variable: change-major-mode-hook
814 This normal hook is run by `kill-all-local-variables' before it
815 does anything else. This gives major modes a way to arrange for
816 something special to be done if the user switches to a different
817 major mode. For best results, make this variable buffer-local, so
818 that it will disappear after doing its job and will not interfere
819 with the subsequent major mode. *Note Hooks::.
822 File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
827 Text mode is perhaps the simplest mode besides Fundamental mode.
828 Here are excerpts from `text-mode.el' that illustrate many of the
829 conventions listed above:
831 ;; Create mode-specific tables.
832 (defvar text-mode-syntax-table nil
833 "Syntax table used while in text mode.")
835 (if text-mode-syntax-table
836 () ; Do not change the table if it is already set up.
837 (setq text-mode-syntax-table (make-syntax-table))
838 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
839 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
840 (modify-syntax-entry ?' "w " text-mode-syntax-table))
842 (defvar text-mode-abbrev-table nil
843 "Abbrev table used while in text mode.")
844 (define-abbrev-table 'text-mode-abbrev-table ())
846 (defvar text-mode-map nil) ; Create a mode-specific keymap.
849 () ; Do not change the keymap if it is already set up.
850 (setq text-mode-map (make-sparse-keymap))
851 (define-key text-mode-map "\t" 'tab-to-tab-stop)
852 (define-key text-mode-map "\es" 'center-line)
853 (define-key text-mode-map "\eS" 'center-paragraph))
855 Here is the complete major mode function definition for Text mode:
858 "Major mode for editing text intended for humans to read.
859 Special commands: \\{text-mode-map}
860 Turning on text-mode runs the hook `text-mode-hook'."
862 (kill-all-local-variables)
863 (use-local-map text-mode-map) ; This provides the local keymap.
864 (setq mode-name "Text") ; This name goes into the modeline.
865 (setq major-mode 'text-mode) ; This is how `describe-mode'
866 ; finds the doc string to print.
867 (setq local-abbrev-table text-mode-abbrev-table)
868 (set-syntax-table text-mode-syntax-table)
869 (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
870 ; customize the mode with a hook.
872 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
873 Interaction mode) have more features than Text mode and the code is
874 correspondingly more complicated. Here are excerpts from
875 `lisp-mode.el' that illustrate how these modes are written.
877 ;; Create mode-specific table variables.
878 (defvar lisp-mode-syntax-table nil "")
879 (defvar emacs-lisp-mode-syntax-table nil "")
880 (defvar lisp-mode-abbrev-table nil "")
882 (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
883 ; if it is already set.
885 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
887 ;; Set syntax of chars up to 0 to class of chars that are
888 ;; part of symbol names but not words.
889 ;; (The number 0 is `48' in the ASCII character set.)
891 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
894 ;; Set the syntax for other characters.
895 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
896 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
898 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
899 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
901 ;; Create an abbrev table for lisp-mode.
902 (define-abbrev-table 'lisp-mode-abbrev-table ())
904 Much code is shared among the three Lisp modes. The following
905 function sets various variables; it is called by each of the major Lisp
908 (defun lisp-mode-variables (lisp-syntax)
909 ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
910 ;; and `t' in the other two Lisp modes.
912 (if (not lisp-mode-syntax-table)
913 ;; The Emacs Lisp mode syntax table always exists, but
914 ;; the Lisp Mode syntax table is created the first time a
915 ;; mode that needs it is called. This is to save space.
916 (progn (setq lisp-mode-syntax-table
917 (copy-syntax-table emacs-lisp-mode-syntax-table))
918 ;; Change some entries for Lisp mode.
919 (modify-syntax-entry ?\| "\" "
920 lisp-mode-syntax-table)
921 (modify-syntax-entry ?\[ "_ "
922 lisp-mode-syntax-table)
923 (modify-syntax-entry ?\] "_ "
924 lisp-mode-syntax-table)))
925 (set-syntax-table lisp-mode-syntax-table)))
926 (setq local-abbrev-table lisp-mode-abbrev-table)
929 Functions such as `forward-paragraph' use the value of the
930 `paragraph-start' variable. Since Lisp code is different from ordinary
931 text, the `paragraph-start' variable needs to be set specially to
932 handle Lisp. Also, comments are indented in a special fashion in Lisp
933 and the Lisp modes need their own mode-specific
934 `comment-indent-function'. The code to set these variables is the rest
935 of `lisp-mode-variables'.
937 (make-local-variable 'paragraph-start)
938 ;; Having `^' is not clean, but `page-delimiter'
939 ;; has them too, and removing those is a pain.
940 (setq paragraph-start (concat "^$\\|" page-delimiter))
942 (make-local-variable 'comment-indent-function)
943 (setq comment-indent-function 'lisp-comment-indent))
945 Each of the different Lisp modes has a slightly different keymap.
946 For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
947 Lisp modes do not. However, all Lisp modes have some commands in
948 common. The following function adds these common commands to a given
951 (defun lisp-mode-commands (map)
952 (define-key map "\e\C-q" 'indent-sexp)
953 (define-key map "\177" 'backward-delete-char-untabify)
954 (define-key map "\t" 'lisp-indent-line))
956 Here is an example of using `lisp-mode-commands' to initialize a
957 keymap, as part of the code for Emacs Lisp mode. First we declare a
958 variable with `defvar' to hold the mode-specific keymap. When this
959 `defvar' executes, it sets the variable to `nil' if it was void. Then
960 we set up the keymap if the variable is `nil'.
962 This code avoids changing the keymap or the variable if it is already
963 set up. This lets the user customize the keymap.
965 (defvar emacs-lisp-mode-map () "")
966 (if emacs-lisp-mode-map
968 (setq emacs-lisp-mode-map (make-sparse-keymap))
969 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
970 (lisp-mode-commands emacs-lisp-mode-map))
972 Finally, here is the complete major mode function definition for
975 (defun emacs-lisp-mode ()
976 "Major mode for editing Lisp code to run in XEmacs.
978 Delete converts tabs to spaces as it moves back.
979 Blank lines separate paragraphs. Semicolons start comments.
980 \\{emacs-lisp-mode-map}
981 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
983 (kill-all-local-variables)
984 (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
985 (set-syntax-table emacs-lisp-mode-syntax-table)
986 (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
987 ; finds out what to describe.
988 (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
989 (lisp-mode-variables nil) ; This defines various variables.
990 (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
991 ; hook to customize the mode.
994 File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
996 How XEmacs Chooses a Major Mode
997 -------------------------------
999 Based on information in the file name or in the file itself, XEmacs
1000 automatically selects a major mode for the new buffer when a file is
1003 - Command: fundamental-mode
1004 Fundamental mode is a major mode that is not specialized for
1005 anything in particular. Other major modes are defined in effect
1006 by comparison with this one--their definitions say what to change,
1007 starting from Fundamental mode. The `fundamental-mode' function
1008 does _not_ run any hooks; you're not supposed to customize it.
1009 (If you want Emacs to behave differently in Fundamental mode,
1010 change the _global_ state of Emacs.)
1012 - Command: normal-mode &optional find-file
1013 This function establishes the proper major mode and local variable
1014 bindings for the current buffer. First it calls `set-auto-mode',
1015 then it runs `hack-local-variables' to parse, and bind or evaluate
1016 as appropriate, any local variables.
1018 If the FIND-FILE argument to `normal-mode' is non-`nil',
1019 `normal-mode' assumes that the `find-file' function is calling it.
1020 In this case, it may process a local variables list at the end of
1021 the file and in the `-*-' line. The variable
1022 `enable-local-variables' controls whether to do so.
1024 If you run `normal-mode' interactively, the argument FIND-FILE is
1025 normally `nil'. In this case, `normal-mode' unconditionally
1026 processes any local variables list. *Note Local Variables in
1027 Files: (emacs)File variables, for the syntax of the local
1028 variables section of a file.
1030 `normal-mode' uses `condition-case' around the call to the major
1031 mode function, so errors are caught and reported as a `File mode
1032 specification error', followed by the original error message.
1034 - User Option: enable-local-variables
1035 This variable controls processing of local variables lists in files
1036 being visited. A value of `t' means process the local variables
1037 lists unconditionally; `nil' means ignore them; anything else means
1038 ask the user what to do for each file. The default value is `t'.
1040 - Variable: ignored-local-variables
1041 This variable holds a list of variables that should not be set by
1042 a local variables list. Any value specified for one of these
1043 variables is ignored.
1045 In addition to this list, any variable whose name has a non-`nil'
1046 `risky-local-variable' property is also ignored.
1048 - User Option: enable-local-eval
1049 This variable controls processing of `Eval:' in local variables
1050 lists in files being visited. A value of `t' means process them
1051 unconditionally; `nil' means ignore them; anything else means ask
1052 the user what to do for each file. The default value is `maybe'.
1054 - Function: set-auto-mode
1055 This function selects the major mode that is appropriate for the
1056 current buffer. It may base its decision on the value of the `-*-'
1057 line, on the visited file name (using `auto-mode-alist'), or on the
1058 value of a local variable. However, this function does not look
1059 for the `mode:' local variable near the end of a file; the
1060 `hack-local-variables' function does that. *Note How Major Modes
1061 are Chosen: (emacs)Choosing Modes.
1063 - User Option: default-major-mode
1064 This variable holds the default major mode for new buffers. The
1065 standard value is `fundamental-mode'.
1067 If the value of `default-major-mode' is `nil', XEmacs uses the
1068 (previously) current buffer's major mode for the major mode of a
1069 new buffer. However, if the major mode symbol has a `mode-class'
1070 property with value `special', then it is not used for new buffers;
1071 Fundamental mode is used instead. The modes that have this
1072 property are those such as Dired and Rmail that are useful only
1073 with text that has been specially prepared.
1075 - Function: set-buffer-major-mode buffer
1076 This function sets the major mode of BUFFER to the value of
1077 `default-major-mode'. If that variable is `nil', it uses the
1078 current buffer's major mode (if that is suitable).
1080 The low-level primitives for creating buffers do not use this
1081 function, but medium-level commands such as `switch-to-buffer' and
1082 `find-file-noselect' use it whenever they create buffers.
1084 - Variable: initial-major-mode
1085 The value of this variable determines the major mode of the initial
1086 `*scratch*' buffer. The value should be a symbol that is a major
1087 mode command name. The default value is `lisp-interaction-mode'.
1089 - Variable: auto-mode-alist
1090 This variable contains an association list of file name patterns
1091 (regular expressions; *note Regular Expressions::) and
1092 corresponding major mode functions. Usually, the file name
1093 patterns test for suffixes, such as `.el' and `.c', but this need
1094 not be the case. An ordinary element of the alist looks like
1095 `(REGEXP . MODE-FUNCTION)'.
1099 (("^/tmp/fol/" . text-mode)
1100 ("\\.texinfo\\'" . texinfo-mode)
1101 ("\\.texi\\'" . texinfo-mode)
1102 ("\\.el\\'" . emacs-lisp-mode)
1103 ("\\.c\\'" . c-mode)
1104 ("\\.h\\'" . c-mode)
1107 When you visit a file whose expanded file name (*note File Name
1108 Expansion::) matches a REGEXP, `set-auto-mode' calls the
1109 corresponding MODE-FUNCTION. This feature enables XEmacs to select
1110 the proper major mode for most files.
1112 If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
1113 t)', then after calling FUNCTION, XEmacs searches
1114 `auto-mode-alist' again for a match against the portion of the file
1115 name that did not match before.
1117 This match-again feature is useful for uncompression packages: an
1118 entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
1119 and then put the uncompressed file in the proper mode according to
1120 the name sans `.gz'.
1122 Here is an example of how to prepend several pattern pairs to
1123 `auto-mode-alist'. (You might use this sort of expression in your
1126 (setq auto-mode-alist
1128 ;; File name starts with a dot.
1129 '(("/\\.[^/]*\\'" . fundamental-mode)
1130 ;; File name has no dot.
1131 ("[^\\./]*\\'" . fundamental-mode)
1132 ;; File name ends in `.C'.
1133 ("\\.C\\'" . c++-mode))
1136 - Variable: interpreter-mode-alist
1137 This variable specifies major modes to use for scripts that
1138 specify a command interpreter in an `#!' line. Its value is a
1139 list of elements of the form `(INTERPRETER . MODE)'; for example,
1140 `("perl" . perl-mode)' is one element present by default. The
1141 element says to use mode MODE if the file specifies INTERPRETER.
1143 This variable is applicable only when the `auto-mode-alist' does
1144 not indicate which major mode to use.
1146 - Function: hack-local-variables &optional force
1147 This function parses, and binds or evaluates as appropriate, any
1148 local variables for the current buffer.
1150 The handling of `enable-local-variables' documented for
1151 `normal-mode' actually takes place here. The argument FORCE
1152 usually comes from the argument FIND-FILE given to `normal-mode'.
projects / chise / xemacs-chise.git- / blob