1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus
58 - Function: popup-menu MENU-DESC
59 This function pops up a menu specified by MENU-DESC, which is a
60 menu description (*note Menu Format::.). The menu is displayed at
61 the current mouse position.
63 - Function: popup-menu-up-p
64 This function returns `t' if a pop-up menu is up, `nil' otherwise.
66 - Variable: popup-menu-titles
67 If true (the default), pop-up menus will have title bars at the
70 Some machinery is provided that attempts to provide a higher-level
71 mechanism onto pop-up menus. This only works if you do not redefine
72 the binding for button3.
74 - Command: popup-mode-menu
75 This function pops up a menu of global and mode-specific commands.
76 The menu is computed by combining `global-popup-menu' and
77 `mode-popup-menu'. This is the default binding for button3. You
78 should generally not change this binding.
80 - Variable: global-popup-menu
81 This holds the global popup menu. This is present in all modes.
82 (This is `nil' by default.)
84 - Variable: mode-popup-menu
85 The mode-specific popup menu. Automatically buffer local. This
86 is appended to the default items in `global-popup-menu'.
88 - Constant: default-popup-menu
89 This holds the default value of `mode-popup-menu'.
91 - Variable: activate-popup-menu-hook
92 Function or functions run before a mode-specific popup menu is made
93 visible. These functions are called with no arguments, and should
94 interrogate and modify the value of `global-popup-menu' or
95 `mode-popup-menu' as desired. Note: this hook is only run if you
96 use `popup-mode-menu' for activating the global and mode-specific
97 commands; if you have your own binding for button3, this hook
100 The following convenience functions are provided for displaying
103 - Function: popup-buffer-menu EVENT
104 This function pops up a copy of the `Buffers' menu (from the
105 menubar) where the mouse is clicked.
107 - Function: popup-menubar-menu EVENT
108 This function pops up a copy of menu that also appears in the
112 File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
117 Menu accelerators are keyboard shortcuts for accessing the menubar.
118 Accelerator keys can be specified for menus as well as for menu items.
119 An accelerator key for a menu is used to activate that menu when it
120 appears as a submenu of another menu. An accelerator key for a menu
121 item is used to activate that item.
125 * Creating Menu Accelerators:: How to add accelerator keys to a menu.
126 * Keyboard Menu Traversal:: How to use and modify the keys which are used
127 to traverse the menu structure.
128 * Menu Accelerator Functions:: Functions for working with menu accelerators.
131 File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators
133 Creating Menu Accelerators
134 --------------------------
136 Menu accelerators are specified as part of the menubar format using
137 the :accelerator tag to specify a key or by placing "%_" in the menu or
138 menu item name prior to the letter which is to be used as the
139 accelerator key. The advantage of the second method is that the menu
140 rendering code then knows to draw an underline under that character,
141 which is the canonical way of indicating an accelerator key to a user.
143 For example, the command
145 (add-submenu nil '("%_Test"
146 ["One" (insert "1") :accelerator ?1 :active t]
147 ["%_Two" (insert "2")]
148 ["%_3" (insert "3")]))
150 will add a new menu to the top level menubar. The new menu can be
151 reached by pressing "t" while the top level menubar is active. When
152 the menu is active, pressing "1" will activate the first item and
153 insert the character "1" into the buffer. Pressing "2" will activate
154 the second item and insert the character "2" into the buffer. Pressing
155 "3" will activate the third item and insert the character "3" into the
158 It is possible to activate the top level menubar itself using
159 accelerator keys. *Note Menu Accelerator Functions::.
162 File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators
164 Keyboard Menu Traversal
165 -----------------------
167 In addition to immediately activating a menu or menu item, the
168 keyboard can be used to traverse the menus without activating items.
169 The keyboard arrow keys, the return key and the escape key are defined
170 to traverse the menus in a way that should be familiar to users of any
171 of a certain family of popular PC operating systems.
173 This behavior can be changed by modifying the bindings in
174 menu-accelerator-map. At this point, the online help is your best bet
175 for more information about how to modify the menu traversal keys.
178 File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators
180 Menu Accelerator Functions
181 --------------------------
183 - Function: accelerate-menu
184 Make the menubar immediately active and place the cursor on the
185 left most entry in the top level menu. Menu items can be selected
188 - Variable: menu-accelerator-enabled
189 Whether menu accelerator keys can cause the menubar to become
192 If `menu-force' or `menu-fallback', then menu accelerator keys can
193 be used to activate the top level menu. Once the menubar becomes
194 active, the accelerator keys can be used regardless of the value
197 `menu-force' is used to indicate that the menu accelerator key
198 takes precedence over bindings in the current keymap(s).
199 `menu-fallback' means that bindings in the current keymap take
200 precedence over menu accelerator keys. Thus a top level menu with
201 an accelerator of "T" would be activated on a keypress of Meta-t
202 if MENU-ACCELERATOR-ENABLED is `menu-force'. However, if
203 MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
204 activate the menubar and will instead run the function
205 transpose-words, to which it is normally bound.
207 The default value is `nil'.
209 See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
211 - Variable: menu-accelerator-map
212 Keymap consulted to determine the commands to run in response to
213 keypresses occurring while the menubar is active. *Note Keyboard
216 - Variable: menu-accelerator-modifiers
217 A list of modifier keys which must be pressed in addition to a
218 valid menu accelerator in order for the top level menu to be
219 activated in response to a keystroke. The default value of
220 `(meta)' mirrors the usage of the alt key as a menu accelerator in
221 popular PC operating systems.
223 The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
224 the modifiers present in the keypress. The only exception is that
225 the shift modifier is accepted in conjunction with alphabetic keys
226 even if it is not a menu accelerator modifier.
228 See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
230 - Variable: menu-accelerator-prefix
231 Prefix key(s) that must be typed before menu accelerators will be
232 activated. Must be a valid key descriptor.
234 The default value is `nil'.
236 (setq menu-accelerator-prefix ?\C-x)
237 (setq menu-accelerator-modifiers '(meta control))
238 (setq menu-accelerator-enabled 'menu-force)
239 (add-submenu nil '("%_Test"
240 ["One" (insert "1") :accelerator ?1 :active t]
241 ["%_Two" (insert "2")]
242 ["%_3" (insert "3")]))
244 will add the menu "Test" to the top level menubar. Pressing C-x
245 followed by C-M-T will activate the menubar and display the "Test"
246 menu. Pressing C-M-T by itself will not activate the menubar. Neither
247 will pressing C-x followed by anything else.
250 File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus
255 The following options control how the `Buffers' menu is displayed.
256 This is a list of all (or a subset of) the buffers currently in
257 existence, and is updated dynamically.
259 - User Option: buffers-menu-max-size
260 This user option holds the maximum number of entries which may
261 appear on the `Buffers' menu. If this is 10, then only the ten
262 most-recently-selected buffers will be shown. If this is `nil',
263 then all buffers will be shown. Setting this to a large number or
264 `nil' will slow down menu responsiveness.
266 - Function: format-buffers-menu-line BUFFER
267 This function returns a string to represent BUFFER in the
268 `Buffers' menu. `nil' means the buffer shouldn't be listed. You
271 - User Option: complex-buffers-menu-p
272 If true, the `Buffers' menu will contain several commands, as
273 submenus of each buffer line. If this is false, then there will
274 be only one command: select that buffer.
276 - User Option: buffers-menu-switch-to-buffer-function
277 This user option holds the function to call to select a buffer
278 from the `Buffers' menu. `switch-to-buffer' is a good choice, as
282 File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top
289 * Dialog Box Format::
290 * Dialog Box Functions::
293 File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
298 A dialog box description is a list.
300 * The first element of the list is a string to display in the dialog
303 * The rest of the elements are descriptions of the dialog box's
304 buttons. Each one is a vector of three elements:
305 - The first element is the text of the button.
307 - The second element is the "callback".
309 - The third element is `t' or `nil', whether this button is
312 If the callback of a button is a symbol, then it must name a command.
313 It will be invoked with `call-interactively'. If it is a list, then it
314 is evaluated with `eval'.
316 One (and only one) of the buttons may be `nil'. This marker means
317 that all following buttons should be flushright instead of flushleft.
319 The syntax, more precisely:
321 form := <something to pass to `eval'>
322 command := <a symbol or string, to pass to `call-interactively'>
323 callback := command | form
324 active-p := <t, nil, or a form to evaluate to decide whether this
325 button should be selectable>
328 button := '[' name callback active-p ']'
329 dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'
332 File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes
337 - Function: popup-dialog-box DBOX-DESC
338 This function pops up a dialog box. DBOX-DESC describes how the
339 dialog box will appear (*note Dialog Box Format::.).
341 *Note Yes-or-No Queries::, for functions to ask a yes/no question
345 File: lispref.info, Node: Toolbar, Next: Scrollbars, Prev: Dialog Boxes, Up: Top
352 * Toolbar Intro:: An introduction.
353 * Toolbar Descriptor Format:: How to create a toolbar.
354 * Specifying the Toolbar:: Setting a toolbar's contents.
355 * Other Toolbar Variables:: Controlling the size of toolbars.
358 File: lispref.info, Node: Toolbar Intro, Next: Toolbar Descriptor Format, Up: Toolbar
363 A "toolbar" is a bar of icons displayed along one edge of a frame.
364 You can view a toolbar as a series of menu shortcuts - the most common
365 menu options can be accessed with a single click rather than a series
366 of clicks and/or drags to select the option from a menu. Consistent
367 with this, a help string (called the "help-echo") describing what an
368 icon in the toolbar (called a "toolbar button") does, is displayed in
369 the minibuffer when the mouse is over the button.
371 In XEmacs, a toolbar can be displayed along any of the four edges of
372 the frame, and two or more different edges can be displaying toolbars
373 simultaneously. The contents, thickness, and visibility of the
374 toolbars can be controlled separately, and the values can be
375 per-buffer, per-frame, etc., using specifiers (*note Specifiers::.).
377 Normally, there is one toolbar displayed in a frame. Usually, this
378 is the standard toolbar, but certain modes will override this and
379 substitute their own toolbar. In some cases (e.g. the VM package), a
380 package will supply its own toolbar along a different edge from the
381 standard toolbar, so that both can be visible at once. This standard
382 toolbar is usually positioned along the top of the frame, but this can
383 be changed using `set-default-toolbar-position'.
385 Note that, for each of the toolbar properties (contents, thickness,
386 and visibility), there is a separate specifier for each of the four
387 toolbar positions (top, bottom, left, and right), and an additional
388 specifier for the "default" toolbar, i.e. the toolbar whose position is
389 controlled by `set-default-toolbar-position'. The way this works is
390 that `set-default-toolbar-position' arranges things so that the
391 appropriate position-specific specifiers for the default position
392 inherit from the corresponding default specifiers. That way, if the
393 position-specific specifier does not give a value (which it usually
394 doesn't), then the value from the default specifier applies. If you
395 want to control the default toolbar, you just change the default
396 specifiers, and everything works. A package such as VM that wants to
397 put its own toolbar in a different location from the default just sets
398 the position-specific specifiers, and if the user sets the default
399 toolbar to the same position, it will just not be visible.
402 File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Toolbar Intro, Up: Toolbar
404 Toolbar Descriptor Format
405 =========================
407 The contents of a toolbar are specified using a "toolbar descriptor".
408 The format of a toolbar descriptor is a list of "toolbar button
409 descriptors". Each toolbar button descriptor is a vector in one of the
412 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
414 * `[:style 2D-OR-3D]'
416 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
418 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
420 Optionally, one of the toolbar button descriptors may be `nil'
421 instead of a vector; this signifies the division between the toolbar
422 buttons that are to be displayed flush-left, and the buttons to be
423 displayed flush-right.
425 The first vector format above specifies a normal toolbar button; the
426 others specify blank areas in the toolbar.
428 For the first vector format:
430 * GLYPH-LIST should be a list of one to six glyphs (as created by
431 `make-glyph') or a symbol whose value is such a list. The first
432 glyph, which must be provided, is the glyph used to display the
433 toolbar button when it is in the "up" (not pressed) state. The
434 optional second glyph is for displaying the button when it is in
435 the "down" (pressed) state. The optional third glyph is for when
436 the button is disabled. The last three glyphs are for displaying
437 the button in the "up", "down", and "disabled" states,
438 respectively, but are used when the user has called for captioned
439 toolbar buttons (using `toolbar-buttons-captioned-p'). The
440 function `toolbar-make-button-list' is useful in creating these
443 * Even if you do not provide separate down-state and disabled-state
444 glyphs, the user will still get visual feedback to indicate which
445 state the button is in. Buttons in the up-state are displayed
446 with a shadowed border that gives a raised appearance to the
447 button. Buttons in the down-state are displayed with shadows that
448 give a recessed appearance. Buttons in the disabled state are
449 displayed with no shadows, giving a 2-d effect.
451 * If some of the toolbar glyphs are not provided, they inherit as
456 DISABLED: disabled -> up
458 CAP-DOWN: cap-down -> cap-up -> down -> up
459 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
461 * The second element FUNCTION is a function to be called when the
462 toolbar button is activated (i.e. when the mouse is released over
463 the toolbar button, if the press occurred in the toolbar). It can
464 be any form accepted by `call-interactively', since this is how it
467 * The third element ENABLED-P specifies whether the toolbar button
468 is enabled (disabled buttons do nothing when they are activated,
469 and are displayed differently; see above). It should be either a
470 boolean or a form that evaluates to a boolean.
472 * The fourth element HELP, if non-`nil', should be a string. This
473 string is displayed in the echo area when the mouse passes over the
476 For the other vector formats (specifying blank areas of the toolbar):
478 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
479 whether the area is displayed with shadows (giving it a raised,
480 3-d appearance) or without shadows (giving it a flat appearance).
482 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
483 area. If omitted, it defaults to a device-specific value (8
484 pixels for X devices).
486 - Function: toolbar-make-button-list UP &optional DOWN DISABLED CAP-UP
487 CAP-DOWN CAP-DISABLED
488 This function calls `make-glyph' on each arg and returns a list of
489 the results. This is useful for setting the first argument of a
490 toolbar button descriptor (typically, the result of this function
491 is assigned to a symbol, which is specified as the first argument
492 of the toolbar button descriptor).
494 - Function: check-toolbar-button-syntax BUTTON &optional NOERROR
495 Verify the syntax of entry BUTTON in a toolbar description list.
496 If you want to verify the syntax of a toolbar description list as a
497 whole, use `check-valid-instantiator' with a specifier type of
501 File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
503 Specifying the Toolbar
504 ======================
506 In order to specify the contents of a toolbar, set one of the
507 specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
508 `left-toolbar', or `right-toolbar'. These are specifiers, which means
509 you set them with `set-specifier' and query them with `specifier-specs'
510 or `specifier-instance'. You will get an error if you try to set them
511 using `setq'. The valid instantiators for these specifiers are toolbar
512 descriptors, as described above. *Note Specifiers::, for more
515 Most of the time, you will set `default-toolbar', which allows the
516 user to choose where the toolbar should go.
518 - Specifier: default-toolbar
519 The position of this toolbar is specified in the function
520 `default-toolbar-position'. If the corresponding
521 position-specific toolbar (e.g. `top-toolbar' if
522 `default-toolbar-position' is `top') does not specify a toolbar in
523 a particular domain, then the value of `default-toolbar' in that
524 domain, of any, will be used instead.
526 Note that the toolbar at any particular position will not be
527 displayed unless its thickness (width or height, depending on
528 orientation) is non-zero and its visibility status is true. The
529 thickness is controlled by the specifiers `top-toolbar-height',
530 `bottom-toolbar-height', `left-toolbar-width', and
531 `right-toolbar-width', and the visibility status is controlled by the
532 specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
533 `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
534 Toolbar Variables::.).
536 - Function: set-default-toolbar-position POSITION
537 This function sets the position that the `default-toolbar' will be
538 displayed at. Valid positions are the symbols `top', `bottom',
539 `left' and `right'. What this actually does is set the fallback
540 specifier for the position-specific specifier corresponding to the
541 given position to `default-toolbar', and set the fallbacks for the
542 other position-specific specifiers to `nil'. It also does the
543 same thing for the position-specific thickness and visibility
544 specifiers, which inherit from one of `default-toolbar-height' or
545 `default-toolbar-width', and from `default-toolbar-visible-p',
546 respectively (*note Other Toolbar Variables::.).
548 - Function: default-toolbar-position
549 This function returns the position that the `default-toolbar' will
552 You can also explicitly set a toolbar at a particular position. When
553 redisplay determines what to display at a particular position in a
554 particular domain (i.e. window), it first consults the position-specific
555 toolbar. If that does not yield a toolbar descriptor, the
556 `default-toolbar' is consulted if `default-toolbar-position' indicates
559 - Specifier: top-toolbar
560 Specifier for the toolbar at the top of the frame.
562 - Specifier: bottom-toolbar
563 Specifier for the toolbar at the bottom of the frame.
565 - Specifier: left-toolbar
566 Specifier for the toolbar at the left edge of the frame.
568 - Specifier: right-toolbar
569 Specifier for the toolbar at the right edge of the frame.
571 - Function: toolbar-specifier-p OBJECT
572 This function returns non-nil if OBJECT is a toolbar specifier.
573 Toolbar specifiers are the actual objects contained in the toolbar
574 variables described above, and their valid instantiators are
575 toolbar descriptors (*note Toolbar Descriptor Format::.).
578 File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
580 Other Toolbar Variables
581 =======================
583 The variables to control the toolbar thickness, visibility status,
584 and captioned status are all specifiers. *Note Specifiers::.
586 - Specifier: default-toolbar-height
587 This specifies the height of the default toolbar, if it's oriented
588 horizontally. The position of the default toolbar is specified by
589 the function `set-default-toolbar-position'. If the corresponding
590 position-specific toolbar thickness specifier (e.g.
591 `top-toolbar-height' if `default-toolbar-position' is `top') does
592 not specify a thickness in a particular domain (a window or a
593 frame), then the value of `default-toolbar-height' or
594 `default-toolbar-width' (depending on the toolbar orientation) in
595 that domain, if any, will be used instead.
597 - Specifier: default-toolbar-width
598 This specifies the width of the default toolbar, if it's oriented
599 vertically. This behaves like `default-toolbar-height'.
601 Note that `default-toolbar-height' is only used when
602 `default-toolbar-position' is `top' or `bottom', and
603 `default-toolbar-width' is only used when `default-toolbar-position' is
606 - Specifier: top-toolbar-height
607 This specifies the height of the top toolbar.
609 - Specifier: bottom-toolbar-height
610 This specifies the height of the bottom toolbar.
612 - Specifier: left-toolbar-width
613 This specifies the width of the left toolbar.
615 - Specifier: right-toolbar-width
616 This specifies the width of the right toolbar.
618 Note that all of the position-specific toolbar thickness specifiers
619 have a fallback value of zero when they do not correspond to the
620 default toolbar. Therefore, you will have to set a non-zero thickness
621 value if you want a position-specific toolbar to be displayed.
623 - Specifier: default-toolbar-visible-p
624 This specifies whether the default toolbar is visible. The
625 position of the default toolbar is specified by the function
626 `set-default-toolbar-position'. If the corresponding
627 position-specific toolbar visibility specifier (e.g.
628 `top-toolbar-visible-p' if `default-toolbar-position' is `top')
629 does not specify a visible-p value in a particular domain (a
630 window or a frame), then the value of `default-toolbar-visible-p'
631 in that domain, if any, will be used instead.
633 - Specifier: top-toolbar-visible-p
634 This specifies whether the top toolbar is visible.
636 - Specifier: bottom-toolbar-visible-p
637 This specifies whether the bottom toolbar is visible.
639 - Specifier: left-toolbar-visible-p
640 This specifies whether the left toolbar is visible.
642 - Specifier: right-toolbar-visible-p
643 This specifies whether the right toolbar is visible.
645 `default-toolbar-visible-p' and all of the position-specific toolbar
646 visibility specifiers have a fallback value of true.
648 Internally, toolbar thickness and visibility specifiers are
649 instantiated in both window and frame domains, for different purposes.
650 The value in the domain of a frame's selected window specifies the
651 actual toolbar thickness or visibility that you will see in that frame.
652 The value in the domain of a frame itself specifies the toolbar
653 thickness or visibility that is used in frame geometry calculations.
655 Thus, for example, if you set the frame width to 80 characters and
656 the left toolbar width for that frame to 68 pixels, then the frame will
657 be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
658 set the left toolbar width to 0 for a particular buffer (or if that
659 buffer does not specify a left toolbar or has a nil value specified for
660 `left-toolbar-visible-p'), you will find that, when that buffer is
661 displayed in the selected window, the window will have a width of 86 or
662 87 characters - the frame is sized for a 68-pixel left toolbar but the
663 selected window specifies that the left toolbar is not visible, so it is
664 expanded to take up the slack.
666 - Specifier: toolbar-buttons-captioned-p
667 Whether toolbar buttons are captioned. This affects which glyphs
668 from a toolbar button descriptor are chosen. *Note Toolbar
671 You can also reset the toolbar to what it was when XEmacs started up.
673 - Constant: initial-toolbar-spec
674 The toolbar descriptor used to initialize `default-toolbar' at
678 File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Toolbar, Up: Top
686 File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
691 *WARNING*: the Drag'n'Drop API is still under development and the
692 interface may change! The current implementation is considered
695 Drag'n'drop is a way to transfer information between multiple
696 applications. To do this several GUIs define their own protocols.
697 Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
698 To catch all these protocols, XEmacs provides a generic API.
700 One prime idea behind the API is to use a data interface that is
701 transparent for all systems. The author thinks that this is best
702 archived by using URL and MIME data, cause any internet enabled system
703 must support these for email already. XEmacs also already provides
704 powerful interfaces to support these types of data (tm and w3).
708 * Supported Protocols:: Which low-level protocols are supported.
709 * Drop Interface:: How XEmacs handles a drop from another application.
710 * Drag Interface:: Calls to initiate a drag from XEmacs.
713 File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
718 The current release of XEmacs only support a small set of Drag'n'drop
719 protocols. Some of these only support limited options available in the
724 * OffiX DND:: A generic X based protocol.
725 * CDE dt:: Common Desktop Environment used on suns.
726 * MSWindows OLE:: Mr. Gates way of live.
727 * Loose ends:: The other protocols.
730 File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
735 *WARNING*: If you compile in OffiX, you may not be able to use
736 multiple X displays successfully. If the two servers are from
737 different vendors, the results may be unpredictable.
739 The OffiX Drag'n'Drop protocol is part of a X API/Widget library
740 created by Cesar Crusius. It is based on X-Atoms and ClientMessage
741 events, and works with any X platform supporting them.
743 OffiX is supported if 'offix is member of the variable
744 dragdrop-protocols, or the feature 'offix is defined.
746 Unfortunately it uses it's own data types. Examples are: File, Files,
747 Exe, Link, URL, MIME. The API tries to choose the right type for the
748 data that is dragged from XEmacs (well, not yet...).
750 XEmacs supports both MIME and URL drags and drops using this API. No
751 application interaction is possible while dragging is in progress.
753 For information about the OffiX project have a look at
754 http://leb.net/~offix/
757 File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
762 CDE stands for Common Desktop Environment. It is based on the Motif
763 widget library. It's drag'n'drop protocol is also an abstraction of the
764 Motif protocol (so it might be possible, that XEmacs will also support
765 the Motif protocol soon).
767 CDE has three different types: file, buffer, and text. XEmacs only
768 uses file and buffer drags. The API will disallow full URL drags, only
769 file method URLs are passed through.
771 Buffer drags are always converted to plain text.
774 File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
779 Only allows file drags and drops.
782 File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
787 The following protocols will be supported soon: Xdnd, Motif, Xde (if
788 I get some specs), KDE OffiX (if KDE can find XEmacs windows).
790 In particular Xdnd will be one of the protocols that can benefit from
791 the XEmacs API, cause it also uses MIME types to encode dragged data.
794 File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
799 For each activated low-level protocol, a internal routine will catch
800 incoming drops and convert them to a dragdrop-drop type misc-user-event.
802 This misc-user-event has its function argument set to
803 `dragdrop-drop-dispatch' and the object contains the data of the drop
804 (converted to URL/MIME specific data). This function will search the
805 variable `experimental-dragdrop-drop-functions' for a function that can
806 handle the dropped data.
808 To modify the drop behavior, the user can modify the variable
809 `experimental-dragdrop-drop-functions'. Each element of this list
810 specifies a possible handler for dropped data. The first one that can
811 handle the data will return `t' and exit. Another possibility is to set
812 a extent-property with the same name. Extents are checked prior to the
815 The customization group `drag-n-drop' shows all variables of user
819 File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
824 This describes the drag API (not implemented yet).
827 File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
829 Major and Minor Modes
830 *********************
832 A "mode" is a set of definitions that customize XEmacs and can be
833 turned on and off while you edit. There are two varieties of modes:
834 "major modes", which are mutually exclusive and used for editing
835 particular kinds of text, and "minor modes", which provide features
836 that users can enable individually.
838 This chapter describes how to write both major and minor modes, how
839 to indicate them in the modeline, and how they run hooks supplied by the
840 user. For related topics such as keymaps and syntax tables, see *Note
841 Keymaps::, and *Note Syntax Tables::.
845 * Major Modes:: Defining major modes.
846 * Minor Modes:: Defining minor modes.
847 * Modeline Format:: Customizing the text that appears in the modeline.
848 * Hooks:: How to use hooks; how to write code that provides hooks.
851 File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
856 Major modes specialize XEmacs for editing particular kinds of text.
857 Each buffer has only one major mode at a time.
859 The least specialized major mode is called "Fundamental mode". This
860 mode has no mode-specific definitions or variable settings, so each
861 XEmacs command behaves in its default manner, and each option is in its
862 default state. All other major modes redefine various keys and options.
863 For example, Lisp Interaction mode provides special key bindings for
864 <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
867 When you need to write several editing commands to help you perform a
868 specialized editing task, creating a new major mode is usually a good
869 idea. In practice, writing a major mode is easy (in contrast to
870 writing a minor mode, which is often difficult).
872 If the new mode is similar to an old one, it is often unwise to
873 modify the old one to serve two purposes, since it may become harder to
874 use and maintain. Instead, copy and rename an existing major mode
875 definition and alter the copy--or define a "derived mode" (*note
876 Derived Modes::.). For example, Rmail Edit mode, which is in
877 `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
878 mode except that it provides three additional commands. Its definition
879 is distinct from that of Text mode, but was derived from it.
881 Rmail Edit mode is an example of a case where one piece of text is
882 put temporarily into a different major mode so it can be edited in a
883 different way (with ordinary XEmacs commands rather than Rmail). In
884 such cases, the temporary major mode usually has a command to switch
885 back to the buffer's usual mode (Rmail mode, in this case). You might
886 be tempted to present the temporary redefinitions inside a recursive
887 edit and restore the usual ones when the user exits; but this is a bad
888 idea because it constrains the user's options when it is done in more
889 than one buffer: recursive edits must be exited most-recently-entered
890 first. Using alternative major modes avoids this limitation. *Note
893 The standard XEmacs Lisp library directory contains the code for
894 several major modes, in files including `text-mode.el', `texinfo.el',
895 `lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
896 libraries to see how modes are written. Text mode is perhaps the
897 simplest major mode aside from Fundamental mode. Rmail mode is a
898 complicated and specialized mode.
902 * Major Mode Conventions:: Coding conventions for keymaps, etc.
903 * Example Major Modes:: Text mode and Lisp modes.
904 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
905 * Mode Help:: Finding out how to use a mode.
906 * Derived Modes:: Defining a new major mode based on another major
910 File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
912 Major Mode Conventions
913 ----------------------
915 The code for existing major modes follows various coding conventions,
916 including conventions for local keymap and syntax table initialization,
917 global names, and hooks. Please follow these conventions when you
918 define a new major mode:
920 * Define a command whose name ends in `-mode', with no arguments,
921 that switches to the new mode in the current buffer. This command
922 should set up the keymap, syntax table, and local variables in an
923 existing buffer without changing the buffer's text.
925 * Write a documentation string for this command that describes the
926 special commands available in this mode. `C-h m'
927 (`describe-mode') in your mode will display this string.
929 The documentation string may include the special documentation
930 substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
931 enable the documentation to adapt automatically to the user's own
932 key bindings. *Note Keys in Documentation::.
934 * The major mode command should start by calling
935 `kill-all-local-variables'. This is what gets rid of the local
936 variables of the major mode previously in effect.
938 * The major mode command should set the variable `major-mode' to the
939 major mode command symbol. This is how `describe-mode' discovers
940 which documentation to print.
942 * The major mode command should set the variable `mode-name' to the
943 "pretty" name of the mode, as a string. This appears in the mode
946 * Since all global names are in the same name space, all the global
947 variables, constants, and functions that are part of the mode
948 should have names that start with the major mode name (or with an
949 abbreviation of it if the name is long). *Note Style Tips::.
951 * The major mode should usually have its own keymap, which is used
952 as the local keymap in all buffers in that mode. The major mode
953 function should call `use-local-map' to install this local map.
954 *Note Active Keymaps::, for more information.
956 This keymap should be kept in a global variable named
957 `MODENAME-mode-map'. Normally the library that defines the mode
960 * The mode may have its own syntax table or may share one with other
961 related modes. If it has its own syntax table, it should store
962 this in a variable named `MODENAME-mode-syntax-table'. *Note
965 * The mode may have its own abbrev table or may share one with other
966 related modes. If it has its own abbrev table, it should store
967 this in a variable named `MODENAME-mode-abbrev-table'. *Note
970 * Use `defvar' to set mode-related variables, so that they are not
971 reinitialized if they already have a value. (Such reinitialization
972 could discard customizations made by the user.)
974 * To make a buffer-local binding for an Emacs customization
975 variable, use `make-local-variable' in the major mode command, not
976 `make-variable-buffer-local'. The latter function would make the
977 variable local to every buffer in which it is subsequently set,
978 which would affect buffers that do not use this mode. It is
979 undesirable for a mode to have such global effects. *Note
980 Buffer-Local Variables::.
982 It's ok to use `make-variable-buffer-local', if you wish, for a
983 variable used only within a single Lisp package.
985 * Each major mode should have a "mode hook" named
986 `MODENAME-mode-hook'. The major mode command should run that
987 hook, with `run-hooks', as the very last thing it does. *Note
990 * The major mode command may also run the hooks of some more basic
991 modes. For example, `indented-text-mode' runs `text-mode-hook' as
992 well as `indented-text-mode-hook'. It may run these other hooks
993 immediately before the mode's own hook (that is, after everything
994 else), or it may run them earlier.
996 * If something special should be done if the user switches a buffer
997 from this mode to any other major mode, the mode can set a local
998 value for `change-major-mode-hook'.
1000 * If this mode is appropriate only for specially-prepared text, then
1001 the major mode command symbol should have a property named
1002 `mode-class' with value `special', put on as follows:
1004 (put 'funny-mode 'mode-class 'special)
1006 This tells XEmacs that new buffers created while the current
1007 buffer has Funny mode should not inherit Funny mode. Modes such
1008 as Dired, Rmail, and Buffer List use this feature.
1010 * If you want to make the new mode the default for files with certain
1011 recognizable names, add an element to `auto-mode-alist' to select
1012 the mode for those file names. If you define the mode command to
1013 autoload, you should add this element in the same file that calls
1014 `autoload'. Otherwise, it is sufficient to add the element in the
1015 file that contains the mode definition. *Note Auto Major Mode::.
1017 * In the documentation, you should provide a sample `autoload' form
1018 and an example of how to add to `auto-mode-alist', that users can
1019 include in their `.emacs' files.
1021 * The top-level forms in the file defining the mode should be
1022 written so that they may be evaluated more than once without
1023 adverse consequences. Even if you never load the file more than
1024 once, someone else will.
1026 - Variable: change-major-mode-hook
1027 This normal hook is run by `kill-all-local-variables' before it
1028 does anything else. This gives major modes a way to arrange for
1029 something special to be done if the user switches to a different
1030 major mode. For best results, make this variable buffer-local, so
1031 that it will disappear after doing its job and will not interfere
1032 with the subsequent major mode. *Note Hooks::.
1035 File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
1040 Text mode is perhaps the simplest mode besides Fundamental mode.
1041 Here are excerpts from `text-mode.el' that illustrate many of the
1042 conventions listed above:
1044 ;; Create mode-specific tables.
1045 (defvar text-mode-syntax-table nil
1046 "Syntax table used while in text mode.")
1048 (if text-mode-syntax-table
1049 () ; Do not change the table if it is already set up.
1050 (setq text-mode-syntax-table (make-syntax-table))
1051 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
1052 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
1053 (modify-syntax-entry ?' "w " text-mode-syntax-table))
1055 (defvar text-mode-abbrev-table nil
1056 "Abbrev table used while in text mode.")
1057 (define-abbrev-table 'text-mode-abbrev-table ())
1059 (defvar text-mode-map nil) ; Create a mode-specific keymap.
1062 () ; Do not change the keymap if it is already set up.
1063 (setq text-mode-map (make-sparse-keymap))
1064 (define-key text-mode-map "\t" 'tab-to-tab-stop)
1065 (define-key text-mode-map "\es" 'center-line)
1066 (define-key text-mode-map "\eS" 'center-paragraph))
1068 Here is the complete major mode function definition for Text mode:
1071 "Major mode for editing text intended for humans to read.
1072 Special commands: \\{text-mode-map}
1074 Turning on text-mode runs the hook `text-mode-hook'."
1076 (kill-all-local-variables)
1078 (use-local-map text-mode-map) ; This provides the local keymap.
1079 (setq mode-name "Text") ; This name goes into the modeline.
1080 (setq major-mode 'text-mode) ; This is how `describe-mode'
1081 ; finds the doc string to print.
1082 (setq local-abbrev-table text-mode-abbrev-table)
1083 (set-syntax-table text-mode-syntax-table)
1084 (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
1085 ; customize the mode with a hook.
1087 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
1088 Interaction mode) have more features than Text mode and the code is
1089 correspondingly more complicated. Here are excerpts from
1090 `lisp-mode.el' that illustrate how these modes are written.
1092 ;; Create mode-specific table variables.
1093 (defvar lisp-mode-syntax-table nil "")
1094 (defvar emacs-lisp-mode-syntax-table nil "")
1095 (defvar lisp-mode-abbrev-table nil "")
1097 (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
1098 ; if it is already set.
1100 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
1102 ;; Set syntax of chars up to 0 to class of chars that are
1103 ;; part of symbol names but not words.
1104 ;; (The number 0 is `48' in the ASCII character set.)
1106 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
1110 ;; Set the syntax for other characters.
1111 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
1112 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
1115 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
1116 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
1118 ;; Create an abbrev table for lisp-mode.
1119 (define-abbrev-table 'lisp-mode-abbrev-table ())
1121 Much code is shared among the three Lisp modes. The following
1122 function sets various variables; it is called by each of the major Lisp
1125 (defun lisp-mode-variables (lisp-syntax)
1126 ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
1127 ;; and `t' in the other two Lisp modes.
1129 (if (not lisp-mode-syntax-table)
1130 ;; The Emacs Lisp mode syntax table always exists, but
1131 ;; the Lisp Mode syntax table is created the first time a
1132 ;; mode that needs it is called. This is to save space.
1134 (progn (setq lisp-mode-syntax-table
1135 (copy-syntax-table emacs-lisp-mode-syntax-table))
1136 ;; Change some entries for Lisp mode.
1137 (modify-syntax-entry ?\| "\" "
1138 lisp-mode-syntax-table)
1139 (modify-syntax-entry ?\[ "_ "
1140 lisp-mode-syntax-table)
1141 (modify-syntax-entry ?\] "_ "
1142 lisp-mode-syntax-table)))
1144 (set-syntax-table lisp-mode-syntax-table)))
1145 (setq local-abbrev-table lisp-mode-abbrev-table)
1148 Functions such as `forward-paragraph' use the value of the
1149 `paragraph-start' variable. Since Lisp code is different from ordinary
1150 text, the `paragraph-start' variable needs to be set specially to
1151 handle Lisp. Also, comments are indented in a special fashion in Lisp
1152 and the Lisp modes need their own mode-specific
1153 `comment-indent-function'. The code to set these variables is the rest
1154 of `lisp-mode-variables'.
1156 (make-local-variable 'paragraph-start)
1157 ;; Having `^' is not clean, but `page-delimiter'
1158 ;; has them too, and removing those is a pain.
1159 (setq paragraph-start (concat "^$\\|" page-delimiter))
1162 (make-local-variable 'comment-indent-function)
1163 (setq comment-indent-function 'lisp-comment-indent))
1165 Each of the different Lisp modes has a slightly different keymap.
1166 For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
1167 Lisp modes do not. However, all Lisp modes have some commands in
1168 common. The following function adds these common commands to a given
1171 (defun lisp-mode-commands (map)
1172 (define-key map "\e\C-q" 'indent-sexp)
1173 (define-key map "\177" 'backward-delete-char-untabify)
1174 (define-key map "\t" 'lisp-indent-line))
1176 Here is an example of using `lisp-mode-commands' to initialize a
1177 keymap, as part of the code for Emacs Lisp mode. First we declare a
1178 variable with `defvar' to hold the mode-specific keymap. When this
1179 `defvar' executes, it sets the variable to `nil' if it was void. Then
1180 we set up the keymap if the variable is `nil'.
1182 This code avoids changing the keymap or the variable if it is already
1183 set up. This lets the user customize the keymap.
1185 (defvar emacs-lisp-mode-map () "")
1186 (if emacs-lisp-mode-map
1188 (setq emacs-lisp-mode-map (make-sparse-keymap))
1189 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
1190 (lisp-mode-commands emacs-lisp-mode-map))
1192 Finally, here is the complete major mode function definition for
1195 (defun emacs-lisp-mode ()
1196 "Major mode for editing Lisp code to run in XEmacs.
1198 Delete converts tabs to spaces as it moves back.
1199 Blank lines separate paragraphs. Semicolons start comments.
1200 \\{emacs-lisp-mode-map}
1202 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
1204 (kill-all-local-variables)
1205 (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
1206 (set-syntax-table emacs-lisp-mode-syntax-table)
1208 (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
1209 ; finds out what to describe.
1210 (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
1211 (lisp-mode-variables nil) ; This defines various variables.
1212 (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
1213 ; hook to customize the mode.
projects / chise / xemacs-chise.git.1 / blob