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 * Creating Toolbar:: How to create a toolbar.
354 * Toolbar Descriptor Format:: Accessing and modifying a toolbar's
356 * Specifying the Toolbar:: Setting a toolbar's contents.
357 * Other Toolbar Variables:: Controlling the size of toolbars.
360 File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar
365 A "toolbar" is a bar of icons displayed along one edge of a frame.
366 You can view a toolbar as a series of menu shortcuts--the most common
367 menu options can be accessed with a single click rather than a series
368 of clicks and/or drags to select the option from a menu. Consistent
369 with this, a help string (called the "help-echo") describing what an
370 icon in the toolbar (called a "toolbar button") does, is displayed in
371 the minibuffer when the mouse is over the button.
373 In XEmacs, a toolbar can be displayed along any of the four edges of
374 the frame, and two or more different edges can be displaying toolbars
375 simultaneously. The contents, thickness, and visibility of the
376 toolbars can be controlled separately, and the values can be
377 per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
379 Normally, there is one toolbar displayed in a frame. Usually, this
380 is the standard toolbar, but certain modes will override this and
381 substitute their own toolbar. In some cases (e.g. the VM package), a
382 package will supply its own toolbar along a different edge from the
383 standard toolbar, so that both can be visible at once. This standard
384 toolbar is usually positioned along the top of the frame, but this can
385 be changed using `set-default-toolbar-position'.
387 Note that, for each of the toolbar properties (contents, thickness,
388 and visibility), there is a separate specifier for each of the four
389 toolbar positions (top, bottom, left, and right), and an additional
390 specifier for the "default" toolbar, i.e. the toolbar whose position is
391 controlled by `set-default-toolbar-position'. The way this works is
392 that `set-default-toolbar-position' arranges things so that the
393 appropriate position-specific specifiers for the default position
394 inherit from the corresponding default specifiers. That way, if the
395 position-specific specifier does not give a value (which it usually
396 doesn't), then the value from the default specifier applies. If you
397 want to control the default toolbar, you just change the default
398 specifiers, and everything works. A package such as VM that wants to
399 put its own toolbar in a different location from the default just sets
400 the position-specific specifiers, and if the user sets the default
401 toolbar to the same position, it will just not be visible.
404 File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar
409 - Function: make-toolbar-specifier spec-list
410 Return a new `toolbar' specifier object with the given
411 specification list. SPEC-LIST can be a list of specifications
412 (each of which is a cons of a locale and a list of instantiators),
413 a single instantiator, or a list of instantiators. *Note
414 Specifiers::, for more information about specifiers.
416 Toolbar specifiers are used to specify the format of a toolbar.
417 The values of the variables `default-toolbar', `top-toolbar',
418 `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
421 Valid toolbar instantiators are called "toolbar descriptors" and
422 are lists of vectors. See `default-toolbar' for a description of
426 File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
428 Toolbar Descriptor Format
429 =========================
431 The contents of a toolbar are specified using a "toolbar descriptor".
432 The format of a toolbar descriptor is a list of "toolbar button
433 descriptors". Each toolbar button descriptor is a vector in one of the
436 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
438 * `[:style 2D-OR-3D]'
440 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
442 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
444 Optionally, one of the toolbar button descriptors may be `nil'
445 instead of a vector; this signifies the division between the toolbar
446 buttons that are to be displayed flush-left, and the buttons to be
447 displayed flush-right.
449 The first vector format above specifies a normal toolbar button; the
450 others specify blank areas in the toolbar.
452 For the first vector format:
454 * GLYPH-LIST should be a list of one to six glyphs (as created by
455 `make-glyph') or a symbol whose value is such a list. The first
456 glyph, which must be provided, is the glyph used to display the
457 toolbar button when it is in the "up" (not pressed) state. The
458 optional second glyph is for displaying the button when it is in
459 the "down" (pressed) state. The optional third glyph is for when
460 the button is disabled. The last three glyphs are for displaying
461 the button in the "up", "down", and "disabled" states,
462 respectively, but are used when the user has called for captioned
463 toolbar buttons (using `toolbar-buttons-captioned-p'). The
464 function `toolbar-make-button-list' is useful in creating these
467 * Even if you do not provide separate down-state and disabled-state
468 glyphs, the user will still get visual feedback to indicate which
469 state the button is in. Buttons in the up-state are displayed
470 with a shadowed border that gives a raised appearance to the
471 button. Buttons in the down-state are displayed with shadows that
472 give a recessed appearance. Buttons in the disabled state are
473 displayed with no shadows, giving a 2-d effect.
475 * If some of the toolbar glyphs are not provided, they inherit as
480 DISABLED: disabled -> up
482 CAP-DOWN: cap-down -> cap-up -> down -> up
483 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
485 * The second element FUNCTION is a function to be called when the
486 toolbar button is activated (i.e. when the mouse is released over
487 the toolbar button, if the press occurred in the toolbar). It can
488 be any form accepted by `call-interactively', since this is how it
491 * The third element ENABLED-P specifies whether the toolbar button
492 is enabled (disabled buttons do nothing when they are activated,
493 and are displayed differently; see above). It should be either a
494 boolean or a form that evaluates to a boolean.
496 * The fourth element HELP, if non-`nil', should be a string. This
497 string is displayed in the echo area when the mouse passes over the
500 For the other vector formats (specifying blank areas of the toolbar):
502 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
503 whether the area is displayed with shadows (giving it a raised,
504 3-d appearance) or without shadows (giving it a flat appearance).
506 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
507 area. If omitted, it defaults to a device-specific value (8
508 pixels for X devices).
510 - Function: toolbar-make-button-list up &optional down disabled cap-up
511 cap-down cap-disabled
512 This function calls `make-glyph' on each arg and returns a list of
513 the results. This is useful for setting the first argument of a
514 toolbar button descriptor (typically, the result of this function
515 is assigned to a symbol, which is specified as the first argument
516 of the toolbar button descriptor).
518 - Function: check-toolbar-button-syntax button &optional noerror
519 Verify the syntax of entry BUTTON in a toolbar description list.
520 If you want to verify the syntax of a toolbar description list as a
521 whole, use `check-valid-instantiator' with a specifier type of
525 File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
527 Specifying the Toolbar
528 ======================
530 In order to specify the contents of a toolbar, set one of the
531 specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
532 `left-toolbar', or `right-toolbar'. These are specifiers, which means
533 you set them with `set-specifier' and query them with `specifier-specs'
534 or `specifier-instance'. You will get an error if you try to set them
535 using `setq'. The valid instantiators for these specifiers are toolbar
536 descriptors, as described above. *Note Specifiers::, for more
539 Most of the time, you will set `default-toolbar', which allows the
540 user to choose where the toolbar should go.
542 - Specifier: default-toolbar
543 The position of this toolbar is specified in the function
544 `default-toolbar-position'. If the corresponding
545 position-specific toolbar (e.g. `top-toolbar' if
546 `default-toolbar-position' is `top') does not specify a toolbar in
547 a particular domain, then the value of `default-toolbar' in that
548 domain, of any, will be used instead.
550 Note that the toolbar at any particular position will not be
551 displayed unless its thickness (width or height, depending on
552 orientation) is non-zero and its visibility status is true. The
553 thickness is controlled by the specifiers `top-toolbar-height',
554 `bottom-toolbar-height', `left-toolbar-width', and
555 `right-toolbar-width', and the visibility status is controlled by the
556 specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
557 `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
558 Toolbar Variables::).
560 - Function: set-default-toolbar-position position
561 This function sets the position that the `default-toolbar' will be
562 displayed at. Valid positions are the symbols `top', `bottom',
563 `left' and `right'. What this actually does is set the fallback
564 specifier for the position-specific specifier corresponding to the
565 given position to `default-toolbar', and set the fallbacks for the
566 other position-specific specifiers to `nil'. It also does the
567 same thing for the position-specific thickness and visibility
568 specifiers, which inherit from one of `default-toolbar-height' or
569 `default-toolbar-width', and from `default-toolbar-visible-p',
570 respectively (*note Other Toolbar Variables::).
572 - Function: default-toolbar-position
573 This function returns the position that the `default-toolbar' will
576 You can also explicitly set a toolbar at a particular position. When
577 redisplay determines what to display at a particular position in a
578 particular domain (i.e. window), it first consults the position-specific
579 toolbar. If that does not yield a toolbar descriptor, the
580 `default-toolbar' is consulted if `default-toolbar-position' indicates
583 - Specifier: top-toolbar
584 Specifier for the toolbar at the top of the frame.
586 - Specifier: bottom-toolbar
587 Specifier for the toolbar at the bottom of the frame.
589 - Specifier: left-toolbar
590 Specifier for the toolbar at the left edge of the frame.
592 - Specifier: right-toolbar
593 Specifier for the toolbar at the right edge of the frame.
595 - Function: toolbar-specifier-p object
596 This function returns non-nil if OBJECT is a toolbar specifier.
597 Toolbar specifiers are the actual objects contained in the toolbar
598 variables described above, and their valid instantiators are
599 toolbar descriptors (*note Toolbar Descriptor Format::).
602 File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
604 Other Toolbar Variables
605 =======================
607 The variables to control the toolbar thickness, visibility status,
608 and captioned status are all specifiers. *Note Specifiers::.
610 - Specifier: default-toolbar-height
611 This specifies the height of the default toolbar, if it's oriented
612 horizontally. The position of the default toolbar is specified by
613 the function `set-default-toolbar-position'. If the corresponding
614 position-specific toolbar thickness specifier (e.g.
615 `top-toolbar-height' if `default-toolbar-position' is `top') does
616 not specify a thickness in a particular domain (a window or a
617 frame), then the value of `default-toolbar-height' or
618 `default-toolbar-width' (depending on the toolbar orientation) in
619 that domain, if any, will be used instead.
621 - Specifier: default-toolbar-width
622 This specifies the width of the default toolbar, if it's oriented
623 vertically. This behaves like `default-toolbar-height'.
625 Note that `default-toolbar-height' is only used when
626 `default-toolbar-position' is `top' or `bottom', and
627 `default-toolbar-width' is only used when `default-toolbar-position' is
630 - Specifier: top-toolbar-height
631 This specifies the height of the top toolbar.
633 - Specifier: bottom-toolbar-height
634 This specifies the height of the bottom toolbar.
636 - Specifier: left-toolbar-width
637 This specifies the width of the left toolbar.
639 - Specifier: right-toolbar-width
640 This specifies the width of the right toolbar.
642 Note that all of the position-specific toolbar thickness specifiers
643 have a fallback value of zero when they do not correspond to the
644 default toolbar. Therefore, you will have to set a non-zero thickness
645 value if you want a position-specific toolbar to be displayed.
647 - Specifier: default-toolbar-visible-p
648 This specifies whether the default toolbar is visible. The
649 position of the default toolbar is specified by the function
650 `set-default-toolbar-position'. If the corresponding
651 position-specific toolbar visibility specifier (e.g.
652 `top-toolbar-visible-p' if `default-toolbar-position' is `top')
653 does not specify a visible-p value in a particular domain (a
654 window or a frame), then the value of `default-toolbar-visible-p'
655 in that domain, if any, will be used instead.
657 - Specifier: top-toolbar-visible-p
658 This specifies whether the top toolbar is visible.
660 - Specifier: bottom-toolbar-visible-p
661 This specifies whether the bottom toolbar is visible.
663 - Specifier: left-toolbar-visible-p
664 This specifies whether the left toolbar is visible.
666 - Specifier: right-toolbar-visible-p
667 This specifies whether the right toolbar is visible.
669 `default-toolbar-visible-p' and all of the position-specific toolbar
670 visibility specifiers have a fallback value of true.
672 Internally, toolbar thickness and visibility specifiers are
673 instantiated in both window and frame domains, for different purposes.
674 The value in the domain of a frame's selected window specifies the
675 actual toolbar thickness or visibility that you will see in that frame.
676 The value in the domain of a frame itself specifies the toolbar
677 thickness or visibility that is used in frame geometry calculations.
679 Thus, for example, if you set the frame width to 80 characters and
680 the left toolbar width for that frame to 68 pixels, then the frame will
681 be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
682 set the left toolbar width to 0 for a particular buffer (or if that
683 buffer does not specify a left toolbar or has a nil value specified for
684 `left-toolbar-visible-p'), you will find that, when that buffer is
685 displayed in the selected window, the window will have a width of 86 or
686 87 characters--the frame is sized for a 68-pixel left toolbar but the
687 selected window specifies that the left toolbar is not visible, so it is
688 expanded to take up the slack.
690 - Specifier: toolbar-buttons-captioned-p
691 Whether toolbar buttons are captioned. This affects which glyphs
692 from a toolbar button descriptor are chosen. *Note Toolbar
695 You can also reset the toolbar to what it was when XEmacs started up.
697 - Constant: initial-toolbar-spec
698 The toolbar descriptor used to initialize `default-toolbar' at
702 File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
707 A gutter is a rectangle displayed along one edge of a frame. It can
708 contain arbitrary text or graphics.
712 * Gutter Intro:: An introduction.
713 * Creating Gutter:: How to create a gutter.
714 * Gutter Descriptor Format:: Accessing and modifying a gutter's
716 * Specifying a Gutter:: Setting a gutter's contents.
717 * Other Gutter Variables:: Controlling the size of gutters.
718 * Common Gutter Widgets:: Things to put in gutters.
721 File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter
726 A "gutter" is a rectangle displayed along one edge of a frame. It
727 can contain arbitrary text or graphics. It could be considered a
728 generalization of a toolbar, although toolbars are not currently
729 implemented using gutters.
731 In XEmacs, a gutter can be displayed along any of the four edges of
732 the frame, and two or more different edges can be displaying gutters
733 simultaneously. The contents, thickness, and visibility of the gutters
734 can be controlled separately, and the values can be per-buffer,
735 per-frame, etc., using specifiers (*note Specifiers::).
737 Normally, there is one gutter displayed in a frame. Usually, this is
738 the default gutter, containing buffer tabs, but modes cab override this
739 and substitute their own gutter. This default gutter is usually
740 positioned along the top of the frame, but this can be changed using
741 `set-default-gutter-position'.
743 Note that, for each of the gutter properties (contents, thickness,
744 and visibility), there is a separate specifier for each of the four
745 gutter positions (top, bottom, left, and right), and an additional
746 specifier for the "default" gutter, i.e. the gutter whose position is
747 controlled by `set-default-gutter-position'. The way this works is
748 that `set-default-gutter-position' arranges things so that the
749 appropriate position-specific specifiers for the default position
750 inherit from the corresponding default specifiers. That way, if the
751 position-specific specifier does not give a value (which it usually
752 doesn't), then the value from the default specifier applies. If you
753 want to control the default gutter, you just change the default
754 specifiers, and everything works. A package such as VM that wants to
755 put its own gutter in a different location from the default just sets
756 the position-specific specifiers, and if the user sets the default
757 gutter to the same position, it will just not be visible.
760 File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter
765 - Function: make-gutter-specifier spec-list
766 Return a new `gutter' specifier object with the given specification
767 list. SPEC-LIST can be a list of specifications (each of which is
768 a cons of a locale and a list of instantiators), a single
769 instantiator, or a list of instantiators. *Note Specifiers::, for
770 more information about specifiers.
772 Gutter specifiers are used to specify the format of a gutter. The
773 values of the variables `default-gutter', `top-gutter',
774 `left-gutter', `right-gutter', and `bottom-gutter' are always
777 Valid gutter instantiators are called "gutter descriptors" and are
778 either strings or property-lists of strings. See `default-gutter'
779 for a description of the exact format.
781 - Function: make-gutter-size-specifier spec-list
782 Return a new `gutter-size' specifier object with the given spec
783 list. SPEC-LIST can be a list of specifications (each of which is
784 a cons of a locale and a list of instantiators), a single
785 instantiator, or a list of instantiators. *Note Specifiers::, for
786 more information about specifiers.
788 Gutter-size specifiers are used to specify the size of a gutter.
789 The values of the variables `default-gutter-size',
790 `top-gutter-size', `left-gutter-size', `right-gutter-size', and
791 `bottom-gutter-size' are always gutter-size specifiers.
793 Valid gutter-size instantiators are either integers or the special
794 symbol `autodetect'. If a gutter-size is set to `autodetect' them
795 the size of the gutter will be adjusted to just accommodate the
796 gutters contents. `autodetect' only works for top and bottom
799 - Function: make-gutter-visible-specifier spec-list
800 Return a new `gutter-visible' specifier object with the given spec
801 list. SPEC-LIST can be a list of specifications (each of which is
802 a cons of a locale and a list of instantiators), a single
803 instantiator, or a list of instantiators. *Note Specifiers::, for
804 more information about specifiers.
806 Gutter-visible specifiers are used to specify the visibility of a
807 gutter. The values of the variables `default-gutter-visible-p',
808 `top-gutter-visible-p', `left-gutter-visible-p',
809 `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
810 gutter-visible specifiers.
812 Valid gutter-visible instantiators are t, nil or a list of
813 symbols. If a gutter-visible instantiator is set to a list of
814 symbols, and the corresponding gutter specification is a
815 property-list strings, then elements of the gutter specification
816 will only be visible if the corresponding symbol occurs in the
817 gutter-visible instantiator.
820 File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter
822 Gutter Descriptor Format
823 ========================
825 The contents of a gutter are specified using a "gutter descriptor".
826 The format of a gutter descriptor is a list of "gutter button
827 descriptors". Each gutter button descriptor is a vector in one of the
830 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
832 * `[:style 2D-OR-3D]'
834 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
836 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
838 Optionally, one of the gutter button descriptors may be `nil'
839 instead of a vector; this signifies the division between the gutter
840 buttons that are to be displayed flush-left, and the buttons to be
841 displayed flush-right.
843 The first vector format above specifies a normal gutter button; the
844 others specify blank areas in the gutter.
846 For the first vector format:
848 * GLYPH-LIST should be a list of one to six glyphs (as created by
849 `make-glyph') or a symbol whose value is such a list. The first
850 glyph, which must be provided, is the glyph used to display the
851 gutter button when it is in the "up" (not pressed) state. The
852 optional second glyph is for displaying the button when it is in
853 the "down" (pressed) state. The optional third glyph is for when
854 the button is disabled. The last three glyphs are for displaying
855 the button in the "up", "down", and "disabled" states,
856 respectively, but are used when the user has called for captioned
857 gutter buttons (using `gutter-buttons-captioned-p'). The function
858 `gutter-make-button-list' is useful in creating these glyph lists.
860 * Even if you do not provide separate down-state and disabled-state
861 glyphs, the user will still get visual feedback to indicate which
862 state the button is in. Buttons in the up-state are displayed
863 with a shadowed border that gives a raised appearance to the
864 button. Buttons in the down-state are displayed with shadows that
865 give a recessed appearance. Buttons in the disabled state are
866 displayed with no shadows, giving a 2-d effect.
868 * If some of the gutter glyphs are not provided, they inherit as
873 DISABLED: disabled -> up
875 CAP-DOWN: cap-down -> cap-up -> down -> up
876 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
878 * The second element FUNCTION is a function to be called when the
879 gutter button is activated (i.e. when the mouse is released over
880 the gutter button, if the press occurred in the gutter). It can
881 be any form accepted by `call-interactively', since this is how it
884 * The third element ENABLED-P specifies whether the gutter button is
885 enabled (disabled buttons do nothing when they are activated, and
886 are displayed differently; see above). It should be either a
887 boolean or a form that evaluates to a boolean.
889 * The fourth element HELP, if non-`nil', should be a string. This
890 string is displayed in the echo area when the mouse passes over the
893 For the other vector formats (specifying blank areas of the gutter):
895 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
896 whether the area is displayed with shadows (giving it a raised,
897 3-d appearance) or without shadows (giving it a flat appearance).
899 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
900 area. If omitted, it defaults to a device-specific value (8
901 pixels for X devices).
903 - Function: gutter-make-button-list up &optional down disabled cap-up
904 cap-down cap-disabled
905 This function calls `make-glyph' on each arg and returns a list of
906 the results. This is useful for setting the first argument of a
907 gutter button descriptor (typically, the result of this function
908 is assigned to a symbol, which is specified as the first argument
909 of the gutter button descriptor).
911 - Function: check-gutter-button-syntax button &optional noerror
912 Verify the syntax of entry BUTTON in a gutter description list.
913 If you want to verify the syntax of a gutter description list as a
914 whole, use `check-valid-instantiator' with a specifier type of
918 File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
923 In order to specify the contents of a gutter, set one of the
924 specifier variables `default-gutter', `top-gutter', `bottom-gutter',
925 `left-gutter', or `right-gutter'. These are specifiers, which means
926 you set them with `set-specifier' and query them with `specifier-specs'
927 or `specifier-instance'. You will get an error if you try to set them
928 using `setq'. The valid instantiators for these specifiers are gutter
929 descriptors, as described above. *Note Specifiers::, for more
932 Most of the time, you will set `default-gutter', which allows the
933 user to choose where the gutter should go.
935 - Specifier: default-gutter
936 The position of this gutter is specified in the function
937 `default-gutter-position'. If the corresponding position-specific
938 gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
939 does not specify a gutter in a particular domain, then the value
940 of `default-gutter' in that domain, of any, will be used instead.
942 Note that the gutter at any particular position will not be displayed
943 unless its thickness (width or height, depending on orientation) is
944 non-zero and its visibility status is true. The thickness is controlled
945 by the specifiers `top-gutter-height', `bottom-gutter-height',
946 `left-gutter-width', and `right-gutter-width', and the visibility
947 status is controlled by the specifiers `top-gutter-visible-p',
948 `bottom-gutter-visible-p', `left-gutter-visible-p', and
949 `right-gutter-visible-p' (*note Other Gutter Variables::).
951 - Function: set-default-gutter-position position
952 This function sets the position that the `default-gutter' will be
953 displayed at. Valid positions are the symbols `top', `bottom',
954 `left' and `right'. What this actually does is set the fallback
955 specifier for the position-specific specifier corresponding to the
956 given position to `default-gutter', and set the fallbacks for the
957 other position-specific specifiers to `nil'. It also does the
958 same thing for the position-specific thickness and visibility
959 specifiers, which inherit from one of `default-gutter-height' or
960 `default-gutter-width', and from `default-gutter-visible-p',
961 respectively (*note Other Gutter Variables::).
963 - Function: default-gutter-position
964 This function returns the position that the `default-gutter' will
967 You can also explicitly set a gutter at a particular position. When
968 redisplay determines what to display at a particular position in a
969 particular domain (i.e. window), it first consults the position-specific
970 gutter. If that does not yield a gutter descriptor, the
971 `default-gutter' is consulted if `default-gutter-position' indicates
974 - Specifier: top-gutter
975 Specifier for the gutter at the top of the frame.
977 - Specifier: bottom-gutter
978 Specifier for the gutter at the bottom of the frame.
980 - Specifier: left-gutter
981 Specifier for the gutter at the left edge of the frame.
983 - Specifier: right-gutter
984 Specifier for the gutter at the right edge of the frame.
986 - Function: gutter-specifier-p object
987 This function returns non-nil if OBJECT is a gutter specifier.
988 Gutter specifiers are the actual objects contained in the gutter
989 variables described above, and their valid instantiators are
990 gutter descriptors (*note Gutter Descriptor Format::).
993 File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
995 Other Gutter Variables
996 ======================
998 The variables to control the gutter thickness, visibility status, and
999 captioned status are all specifiers. *Note Specifiers::.
1001 - Specifier: default-gutter-height
1002 This specifies the height of the default gutter, if it's oriented
1003 horizontally. The position of the default gutter is specified by
1004 the function `set-default-gutter-position'. If the corresponding
1005 position-specific gutter thickness specifier (e.g.
1006 `top-gutter-height' if `default-gutter-position' is `top') does
1007 not specify a thickness in a particular domain (a window or a
1008 frame), then the value of `default-gutter-height' or
1009 `default-gutter-width' (depending on the gutter orientation) in
1010 that domain, if any, will be used instead.
1012 - Specifier: default-gutter-width
1013 This specifies the width of the default gutter, if it's oriented
1014 vertically. This behaves like `default-gutter-height'.
1016 Note that `default-gutter-height' is only used when
1017 `default-gutter-position' is `top' or `bottom', and
1018 `default-gutter-width' is only used when `default-gutter-position' is
1021 - Specifier: top-gutter-height
1022 This specifies the height of the top gutter.
1024 - Specifier: bottom-gutter-height
1025 This specifies the height of the bottom gutter.
1027 - Specifier: left-gutter-width
1028 This specifies the width of the left gutter.
1030 - Specifier: right-gutter-width
1031 This specifies the width of the right gutter.
1033 Note that all of the position-specific gutter thickness specifiers
1034 have a fallback value of zero when they do not correspond to the
1035 default gutter. Therefore, you will have to set a non-zero thickness
1036 value if you want a position-specific gutter to be displayed.
1038 - Specifier: default-gutter-visible-p
1039 This specifies whether the default gutter is visible. The
1040 position of the default gutter is specified by the function
1041 `set-default-gutter-position'. If the corresponding
1042 position-specific gutter visibility specifier (e.g.
1043 `top-gutter-visible-p' if `default-gutter-position' is `top') does
1044 not specify a visible-p value in a particular domain (a window or
1045 a frame), then the value of `default-gutter-visible-p' in that
1046 domain, if any, will be used instead.
1048 - Specifier: top-gutter-visible-p
1049 This specifies whether the top gutter is visible.
1051 - Specifier: bottom-gutter-visible-p
1052 This specifies whether the bottom gutter is visible.
1054 - Specifier: left-gutter-visible-p
1055 This specifies whether the left gutter is visible.
1057 - Specifier: right-gutter-visible-p
1058 This specifies whether the right gutter is visible.
1060 `default-gutter-visible-p' and all of the position-specific gutter
1061 visibility specifiers have a fallback value of true.
1063 Internally, gutter thickness and visibility specifiers are
1064 instantiated in both window and frame domains, for different purposes.
1065 The value in the domain of a frame's selected window specifies the
1066 actual gutter thickness or visibility that you will see in that frame.
1067 The value in the domain of a frame itself specifies the gutter
1068 thickness or visibility that is used in frame geometry calculations.
1070 Thus, for example, if you set the frame width to 80 characters and
1071 the left gutter width for that frame to 68 pixels, then the frame will
1072 be sized to fit 80 characters plus a 68-pixel left gutter. If you then
1073 set the left gutter width to 0 for a particular buffer (or if that
1074 buffer does not specify a left gutter or has a nil value specified for
1075 `left-gutter-visible-p'), you will find that, when that buffer is
1076 displayed in the selected window, the window will have a width of 86 or
1077 87 characters - the frame is sized for a 68-pixel left gutter but the
1078 selected window specifies that the left gutter is not visible, so it is
1079 expanded to take up the slack.
1081 - Specifier: gutter-buttons-captioned-p
1082 Whether gutter buttons are captioned. This affects which glyphs
1083 from a gutter button descriptor are chosen. *Note Gutter
1084 Descriptor Format::.
1086 You can also reset the gutter to what it was when XEmacs started up.
1088 - Constant: initial-gutter-spec
1089 The gutter descriptor used to initialize `default-gutter' at
1093 File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
1095 Common Gutter Widgets
1096 =====================
1098 A gutter can contain arbitrary text. So, for example, in an Info
1099 buffer you could put the title of the current node in the top gutter,
1100 and it would not scroll out of view in a long node. (This is an
1101 artificial example, since usually the node name is sufficiently
1102 descriptive, and Info puts that in the mode line.)
1104 A more common use for the gutter is to hold some kind of active
1105 widget. The buffer-tab facility, available in all XEmacs frames,
1106 creates an array of file-folder-like tabs, which the user can click with
1107 the mouse to switch buffers. W3 uses a progress-bar widget in the
1108 bottom gutter to give a visual indication of the progress of
1109 time-consuming operations like downloading.
1113 * Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
1114 * Progress Bars:: Visual indication of operation progress.
1117 File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
1125 File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
1133 File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
1141 File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
1146 _WARNING_: the Drag'n'Drop API is still under development and the
1147 interface may change! The current implementation is considered
1150 Drag'n'drop is a way to transfer information between multiple
1151 applications. To do this several GUIs define their own protocols.
1152 Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
1153 To catch all these protocols, XEmacs provides a generic API.
1155 One prime idea behind the API is to use a data interface that is
1156 transparent for all systems. The author thinks that this is best
1157 archived by using URL and MIME data, cause any internet enabled system
1158 must support these for email already. XEmacs also already provides
1159 powerful interfaces to support these types of data (tm and w3).
1163 * Supported Protocols:: Which low-level protocols are supported.
1164 * Drop Interface:: How XEmacs handles a drop from another application.
1165 * Drag Interface:: Calls to initiate a drag from XEmacs.
1168 File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
1173 The current release of XEmacs only support a small set of Drag'n'drop
1174 protocols. Some of these only support limited options available in the
1179 * OffiX DND:: A generic X based protocol.
1180 * CDE dt:: Common Desktop Environment used on suns.
1181 * MSWindows OLE:: Mr. Gates way of live.
1182 * Loose ends:: The other protocols.
1185 File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
1190 _WARNING_: If you compile in OffiX, you may not be able to use
1191 multiple X displays successfully. If the two servers are from
1192 different vendors, the results may be unpredictable.
1194 The OffiX Drag'n'Drop protocol is part of a X API/Widget library
1195 created by Cesar Crusius. It is based on X-Atoms and ClientMessage
1196 events, and works with any X platform supporting them.
1198 OffiX is supported if 'offix is member of the variable
1199 dragdrop-protocols, or the feature 'offix is defined.
1201 Unfortunately it uses it's own data types. Examples are: File, Files,
1202 Exe, Link, URL, MIME. The API tries to choose the right type for the
1203 data that is dragged from XEmacs (well, not yet...).
1205 XEmacs supports both MIME and URL drags and drops using this API. No
1206 application interaction is possible while dragging is in progress.
1208 For information about the OffiX project have a look at
1209 http://leb.net/~offix/
projects / chise / xemacs-chise.git- / blob