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: 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: Gutter, 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: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
683 A gutter is a rectangle displayed along one edge of a frame. It can
684 contain arbitrary text or graphics.
688 * Gutter Intro:: An introduction.
689 * Gutter Descriptor Format:: How to create a gutter.
690 * Specifying a Gutter:: Setting a gutter's contents.
691 * Other Gutter Variables:: Controlling the size of gutters.
692 * Common Gutter Widgets:: Things to put in gutters.
695 File: lispref.info, Node: Gutter Intro, Next: Gutter Descriptor Format, Up: Gutter
700 A "gutter" is a rectangle displayed along one edge of a frame. It
701 can contain arbitrary text or graphics. It could be considered a
702 generalization of a toolbar, although toolbars are not currently
703 implemented using gutters.
705 In XEmacs, a gutter can be displayed along any of the four edges of
706 the frame, and two or more different edges can be displaying gutters
707 simultaneously. The contents, thickness, and visibility of the gutters
708 can be controlled separately, and the values can be per-buffer,
709 per-frame, etc., using specifiers (*note Specifiers::).
711 Normally, there is one gutter displayed in a frame. Usually, this is
712 the default gutter, containing buffer tabs, but modes cab override this
713 and substitute their own gutter. This default gutter is usually
714 positioned along the top of the frame, but this can be changed using
715 `set-default-gutter-position'.
717 Note that, for each of the gutter properties (contents, thickness,
718 and visibility), there is a separate specifier for each of the four
719 gutter positions (top, bottom, left, and right), and an additional
720 specifier for the "default" gutter, i.e. the gutter whose position is
721 controlled by `set-default-gutter-position'. The way this works is
722 that `set-default-gutter-position' arranges things so that the
723 appropriate position-specific specifiers for the default position
724 inherit from the corresponding default specifiers. That way, if the
725 position-specific specifier does not give a value (which it usually
726 doesn't), then the value from the default specifier applies. If you
727 want to control the default gutter, you just change the default
728 specifiers, and everything works. A package such as VM that wants to
729 put its own gutter in a different location from the default just sets
730 the position-specific specifiers, and if the user sets the default
731 gutter to the same position, it will just not be visible.
734 File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Gutter Intro, Up: Gutter
736 Gutter Descriptor Format
737 ========================
739 The contents of a gutter are specified using a "gutter descriptor".
740 The format of a gutter descriptor is a list of "gutter button
741 descriptors". Each gutter button descriptor is a vector in one of the
744 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
746 * `[:style 2D-OR-3D]'
748 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
750 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
752 Optionally, one of the gutter button descriptors may be `nil'
753 instead of a vector; this signifies the division between the gutter
754 buttons that are to be displayed flush-left, and the buttons to be
755 displayed flush-right.
757 The first vector format above specifies a normal gutter button; the
758 others specify blank areas in the gutter.
760 For the first vector format:
762 * GLYPH-LIST should be a list of one to six glyphs (as created by
763 `make-glyph') or a symbol whose value is such a list. The first
764 glyph, which must be provided, is the glyph used to display the
765 gutter button when it is in the "up" (not pressed) state. The
766 optional second glyph is for displaying the button when it is in
767 the "down" (pressed) state. The optional third glyph is for when
768 the button is disabled. The last three glyphs are for displaying
769 the button in the "up", "down", and "disabled" states,
770 respectively, but are used when the user has called for captioned
771 gutter buttons (using `gutter-buttons-captioned-p'). The function
772 `gutter-make-button-list' is useful in creating these glyph lists.
774 * Even if you do not provide separate down-state and disabled-state
775 glyphs, the user will still get visual feedback to indicate which
776 state the button is in. Buttons in the up-state are displayed
777 with a shadowed border that gives a raised appearance to the
778 button. Buttons in the down-state are displayed with shadows that
779 give a recessed appearance. Buttons in the disabled state are
780 displayed with no shadows, giving a 2-d effect.
782 * If some of the gutter glyphs are not provided, they inherit as
787 DISABLED: disabled -> up
789 CAP-DOWN: cap-down -> cap-up -> down -> up
790 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
792 * The second element FUNCTION is a function to be called when the
793 gutter button is activated (i.e. when the mouse is released over
794 the gutter button, if the press occurred in the gutter). It can
795 be any form accepted by `call-interactively', since this is how it
798 * The third element ENABLED-P specifies whether the gutter button is
799 enabled (disabled buttons do nothing when they are activated, and
800 are displayed differently; see above). It should be either a
801 boolean or a form that evaluates to a boolean.
803 * The fourth element HELP, if non-`nil', should be a string. This
804 string is displayed in the echo area when the mouse passes over the
807 For the other vector formats (specifying blank areas of the gutter):
809 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
810 whether the area is displayed with shadows (giving it a raised,
811 3-d appearance) or without shadows (giving it a flat appearance).
813 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
814 area. If omitted, it defaults to a device-specific value (8
815 pixels for X devices).
817 - Function: gutter-make-button-list up &optional down disabled cap-up
818 cap-down cap-disabled
819 This function calls `make-glyph' on each arg and returns a list of
820 the results. This is useful for setting the first argument of a
821 gutter button descriptor (typically, the result of this function
822 is assigned to a symbol, which is specified as the first argument
823 of the gutter button descriptor).
825 - Function: check-gutter-button-syntax button &optional noerror
826 Verify the syntax of entry BUTTON in a gutter description list.
827 If you want to verify the syntax of a gutter description list as a
828 whole, use `check-valid-instantiator' with a specifier type of
832 File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
837 In order to specify the contents of a gutter, set one of the
838 specifier variables `default-gutter', `top-gutter', `bottom-gutter',
839 `left-gutter', or `right-gutter'. These are specifiers, which means
840 you set them with `set-specifier' and query them with `specifier-specs'
841 or `specifier-instance'. You will get an error if you try to set them
842 using `setq'. The valid instantiators for these specifiers are gutter
843 descriptors, as described above. *Note Specifiers::, for more
846 Most of the time, you will set `default-gutter', which allows the
847 user to choose where the gutter should go.
849 - Specifier: default-gutter
850 The position of this gutter is specified in the function
851 `default-gutter-position'. If the corresponding position-specific
852 gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
853 does not specify a gutter in a particular domain, then the value
854 of `default-gutter' in that domain, of any, will be used instead.
856 Note that the gutter at any particular position will not be displayed
857 unless its thickness (width or height, depending on orientation) is
858 non-zero and its visibility status is true. The thickness is controlled
859 by the specifiers `top-gutter-height', `bottom-gutter-height',
860 `left-gutter-width', and `right-gutter-width', and the visibility
861 status is controlled by the specifiers `top-gutter-visible-p',
862 `bottom-gutter-visible-p', `left-gutter-visible-p', and
863 `right-gutter-visible-p' (*note Other Gutter Variables::).
865 - Function: set-default-gutter-position position
866 This function sets the position that the `default-gutter' will be
867 displayed at. Valid positions are the symbols `top', `bottom',
868 `left' and `right'. What this actually does is set the fallback
869 specifier for the position-specific specifier corresponding to the
870 given position to `default-gutter', and set the fallbacks for the
871 other position-specific specifiers to `nil'. It also does the
872 same thing for the position-specific thickness and visibility
873 specifiers, which inherit from one of `default-gutter-height' or
874 `default-gutter-width', and from `default-gutter-visible-p',
875 respectively (*note Other Gutter Variables::).
877 - Function: default-gutter-position
878 This function returns the position that the `default-gutter' will
881 You can also explicitly set a gutter at a particular position. When
882 redisplay determines what to display at a particular position in a
883 particular domain (i.e. window), it first consults the position-specific
884 gutter. If that does not yield a gutter descriptor, the
885 `default-gutter' is consulted if `default-gutter-position' indicates
888 - Specifier: top-gutter
889 Specifier for the gutter at the top of the frame.
891 - Specifier: bottom-gutter
892 Specifier for the gutter at the bottom of the frame.
894 - Specifier: left-gutter
895 Specifier for the gutter at the left edge of the frame.
897 - Specifier: right-gutter
898 Specifier for the gutter at the right edge of the frame.
900 - Function: gutter-specifier-p object
901 This function returns non-nil if OBJECT is a gutter specifier.
902 Gutter specifiers are the actual objects contained in the gutter
903 variables described above, and their valid instantiators are
904 gutter descriptors (*note Gutter Descriptor Format::).
907 File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
909 Other Gutter Variables
910 ======================
912 The variables to control the gutter thickness, visibility status, and
913 captioned status are all specifiers. *Note Specifiers::.
915 - Specifier: default-gutter-height
916 This specifies the height of the default gutter, if it's oriented
917 horizontally. The position of the default gutter is specified by
918 the function `set-default-gutter-position'. If the corresponding
919 position-specific gutter thickness specifier (e.g.
920 `top-gutter-height' if `default-gutter-position' is `top') does
921 not specify a thickness in a particular domain (a window or a
922 frame), then the value of `default-gutter-height' or
923 `default-gutter-width' (depending on the gutter orientation) in
924 that domain, if any, will be used instead.
926 - Specifier: default-gutter-width
927 This specifies the width of the default gutter, if it's oriented
928 vertically. This behaves like `default-gutter-height'.
930 Note that `default-gutter-height' is only used when
931 `default-gutter-position' is `top' or `bottom', and
932 `default-gutter-width' is only used when `default-gutter-position' is
935 - Specifier: top-gutter-height
936 This specifies the height of the top gutter.
938 - Specifier: bottom-gutter-height
939 This specifies the height of the bottom gutter.
941 - Specifier: left-gutter-width
942 This specifies the width of the left gutter.
944 - Specifier: right-gutter-width
945 This specifies the width of the right gutter.
947 Note that all of the position-specific gutter thickness specifiers
948 have a fallback value of zero when they do not correspond to the
949 default gutter. Therefore, you will have to set a non-zero thickness
950 value if you want a position-specific gutter to be displayed.
952 - Specifier: default-gutter-visible-p
953 This specifies whether the default gutter is visible. The
954 position of the default gutter is specified by the function
955 `set-default-gutter-position'. If the corresponding
956 position-specific gutter visibility specifier (e.g.
957 `top-gutter-visible-p' if `default-gutter-position' is `top') does
958 not specify a visible-p value in a particular domain (a window or
959 a frame), then the value of `default-gutter-visible-p' in that
960 domain, if any, will be used instead.
962 - Specifier: top-gutter-visible-p
963 This specifies whether the top gutter is visible.
965 - Specifier: bottom-gutter-visible-p
966 This specifies whether the bottom gutter is visible.
968 - Specifier: left-gutter-visible-p
969 This specifies whether the left gutter is visible.
971 - Specifier: right-gutter-visible-p
972 This specifies whether the right gutter is visible.
974 `default-gutter-visible-p' and all of the position-specific gutter
975 visibility specifiers have a fallback value of true.
977 Internally, gutter thickness and visibility specifiers are
978 instantiated in both window and frame domains, for different purposes.
979 The value in the domain of a frame's selected window specifies the
980 actual gutter thickness or visibility that you will see in that frame.
981 The value in the domain of a frame itself specifies the gutter
982 thickness or visibility that is used in frame geometry calculations.
984 Thus, for example, if you set the frame width to 80 characters and
985 the left gutter width for that frame to 68 pixels, then the frame will
986 be sized to fit 80 characters plus a 68-pixel left gutter. If you then
987 set the left gutter width to 0 for a particular buffer (or if that
988 buffer does not specify a left gutter or has a nil value specified for
989 `left-gutter-visible-p'), you will find that, when that buffer is
990 displayed in the selected window, the window will have a width of 86 or
991 87 characters - the frame is sized for a 68-pixel left gutter but the
992 selected window specifies that the left gutter is not visible, so it is
993 expanded to take up the slack.
995 - Specifier: gutter-buttons-captioned-p
996 Whether gutter buttons are captioned. This affects which glyphs
997 from a gutter button descriptor are chosen. *Note Gutter
1000 You can also reset the gutter to what it was when XEmacs started up.
1002 - Constant: initial-gutter-spec
1003 The gutter descriptor used to initialize `default-gutter' at
1007 File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
1009 Common Gutter Widgets
1010 =====================
1012 A gutter can contain arbitrary text. So, for example, in an Info
1013 buffer you could put the title of the current node in the top gutter,
1014 and it would not scroll out of view in a long node. (This is an
1015 artificial example, since usually the node name is sufficiently
1016 descriptive, and Info puts that in the mode line.)
1018 A more common use for the gutter is to hold some kind of active
1019 widget. The buffer-tab facility, available in all XEmacs frames,
1020 creates an array of file-folder-like tabs, which the user can click with
1021 the mouse to switch buffers. W3 uses a progress-bar widget in the
1022 bottom gutter to give a visual indication of the progress of
1023 time-consuming operations like downloading.
1027 * Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
1028 * Progress Bars:: Visual indication of operation progress.
1031 File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
1039 File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
1047 File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
1055 File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
1060 _WARNING_: the Drag'n'Drop API is still under development and the
1061 interface may change! The current implementation is considered
1064 Drag'n'drop is a way to transfer information between multiple
1065 applications. To do this several GUIs define their own protocols.
1066 Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
1067 To catch all these protocols, XEmacs provides a generic API.
1069 One prime idea behind the API is to use a data interface that is
1070 transparent for all systems. The author thinks that this is best
1071 archived by using URL and MIME data, cause any internet enabled system
1072 must support these for email already. XEmacs also already provides
1073 powerful interfaces to support these types of data (tm and w3).
1077 * Supported Protocols:: Which low-level protocols are supported.
1078 * Drop Interface:: How XEmacs handles a drop from another application.
1079 * Drag Interface:: Calls to initiate a drag from XEmacs.
1082 File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
1087 The current release of XEmacs only support a small set of Drag'n'drop
1088 protocols. Some of these only support limited options available in the
1093 * OffiX DND:: A generic X based protocol.
1094 * CDE dt:: Common Desktop Environment used on suns.
1095 * MSWindows OLE:: Mr. Gates way of live.
1096 * Loose ends:: The other protocols.
1099 File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
1104 _WARNING_: If you compile in OffiX, you may not be able to use
1105 multiple X displays successfully. If the two servers are from
1106 different vendors, the results may be unpredictable.
1108 The OffiX Drag'n'Drop protocol is part of a X API/Widget library
1109 created by Cesar Crusius. It is based on X-Atoms and ClientMessage
1110 events, and works with any X platform supporting them.
1112 OffiX is supported if 'offix is member of the variable
1113 dragdrop-protocols, or the feature 'offix is defined.
1115 Unfortunately it uses it's own data types. Examples are: File, Files,
1116 Exe, Link, URL, MIME. The API tries to choose the right type for the
1117 data that is dragged from XEmacs (well, not yet...).
1119 XEmacs supports both MIME and URL drags and drops using this API. No
1120 application interaction is possible while dragging is in progress.
1122 For information about the OffiX project have a look at
1123 http://leb.net/~offix/
1126 File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
1131 CDE stands for Common Desktop Environment. It is based on the Motif
1132 widget library. It's drag'n'drop protocol is also an abstraction of the
1133 Motif protocol (so it might be possible, that XEmacs will also support
1134 the Motif protocol soon).
1136 CDE has three different types: file, buffer, and text. XEmacs only
1137 uses file and buffer drags. The API will disallow full URL drags, only
1138 file method URLs are passed through.
1140 Buffer drags are always converted to plain text.
1143 File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
1148 Only allows file drags and drops.
1151 File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
1156 The following protocols will be supported soon: Xdnd, Motif, Xde (if
1157 I get some specs), KDE OffiX (if KDE can find XEmacs windows).
1159 In particular Xdnd will be one of the protocols that can benefit from
1160 the XEmacs API, cause it also uses MIME types to encode dragged data.
1163 File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
1168 For each activated low-level protocol, a internal routine will catch
1169 incoming drops and convert them to a dragdrop-drop type misc-user-event.
1171 This misc-user-event has its function argument set to
1172 `dragdrop-drop-dispatch' and the object contains the data of the drop
1173 (converted to URL/MIME specific data). This function will search the
1174 variable `experimental-dragdrop-drop-functions' for a function that can
1175 handle the dropped data.
1177 To modify the drop behavior, the user can modify the variable
1178 `experimental-dragdrop-drop-functions'. Each element of this list
1179 specifies a possible handler for dropped data. The first one that can
1180 handle the data will return `t' and exit. Another possibility is to set
1181 a extent-property with the same name. Extents are checked prior to the
1184 The customization group `drag-n-drop' shows all variables of user
1188 File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
1193 This describes the drag API (not implemented yet).
1196 File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
1198 Major and Minor Modes
1199 *********************
1201 A "mode" is a set of definitions that customize XEmacs and can be
1202 turned on and off while you edit. There are two varieties of modes:
1203 "major modes", which are mutually exclusive and used for editing
1204 particular kinds of text, and "minor modes", which provide features
1205 that users can enable individually.
1207 This chapter describes how to write both major and minor modes, how
1208 to indicate them in the modeline, and how they run hooks supplied by the
1209 user. For related topics such as keymaps and syntax tables, see *Note
1210 Keymaps::, and *Note Syntax Tables::.
1214 * Major Modes:: Defining major modes.
1215 * Minor Modes:: Defining minor modes.
1216 * Modeline Format:: Customizing the text that appears in the modeline.
1217 * Hooks:: How to use hooks; how to write code that provides hooks.
projects / chise / xemacs-chise.git- / blob