-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
+
+Format of Menus
+===============
+
+ A menu is described using a "menu description", which is a list of
+menu items, keyword-value pairs, strings, and submenus. The menu
+description specifies which items are present in the menu, what function
+each item invokes, and whether the item is selectable or not. Pop-up
+menus are directly described with a menu description, while menubars are
+described slightly differently (see below).
+
+ The first element of a menu must be a string, which is the name of
+the menu. This is the string that will be displayed in the parent menu
+or menubar, if any. This string is not displayed in the menu itself,
+except in the case of the top level pop-up menu, where there is no
+parent. In this case, the string will be displayed at the top of the
+menu if `popup-menu-titles' is non-`nil'.
+
+ Immediately following the first element there may optionally be up
+to four keyword-value pairs, as follows:
+
+`:included FORM'
+ This can be used to control the visibility of a menu. The form is
+ evaluated and the menu will be omitted if the result is `nil'.
+
+`:config SYMBOL'
+ This is an efficient shorthand for `:included (memq SYMBOL
+ menubar-configuration)'. See the variable `menubar-configuration'.
+
+`:filter FUNCTION'
+ A menu filter is used to sensitize or incrementally create a
+ submenu only when it is selected by the user and not every time
+ the menubar is activated. The filter function is passed the list
+ of menu items in the submenu and must return a list of menu items
+ to be used for the menu. It is called only when the menu is about
+ to be displayed, so other menus may already be displayed. Vile
+ and terrible things will happen if a menu filter function changes
+ the current buffer, window, or frame. It also should not raise,
+ lower, or iconify any frames. Basically, the filter function
+ should have no side-effects.
+
+`:accelerator KEY'
+ A menu accelerator is a keystroke which can be pressed while the
+ menu is visible which will immediately activate the item. KEY
+ must be a char or the symbol name of a key. *Note Menu
+ Accelerators::.
+
+ The rest of the menu consists of elements as follows:
+
+ * A "menu item", which is a vector in the following form:
+
+ `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
+
+ NAME is a string, the name of the menu item; it is the string to
+ display on the menu. It is filtered through the resource
+ database, so it is possible for resources to override what string
+ is actually displayed.
+
+ CALLBACK is a form that will be invoked when the menu item is
+ selected. If the callback of a menu item is a symbol, then it
+ must name a command. It will be invoked with
+ `call-interactively'. If it is a list, then it is evaluated with
+ `eval'.
+
+ The valid keywords and their meanings are described below.
+
+ Note that for compatibility purposes, the form
+
+ `[ NAME CALLBACK ACTIVE-P ]'
+
+ is also accepted and is equivalent to
+
+ `[ NAME CALLBACK :active ACTIVE-P ]'
+
+ and the form
+
+ `[ NAME CALLBACK ACTIVE-P SUFFIX]'
+
+ is accepted and is equivalent to
+
+ `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
+
+ However, these older forms are deprecated and should generally not
+ be used.
+
+ * If an element of a menu is a string, then that string will be
+ presented in the menu as unselectable text.
+
+ * If an element of a menu is a string consisting solely of hyphens,
+ then that item will be presented as a solid horizontal line.
+
+ * If an element of a menu is a string beginning with `--:', then a
+ particular sort of horizontal line will be displayed, as follows:
+
+ `"--:singleLine"'
+ A solid horizontal line. This is equivalent to a string
+ consisting solely of hyphens.
+
+ `"--:doubleLine"'
+ A solid double horizontal line.
+
+ `"--:singleDashedLine"'
+ A dashed horizontal line.
+
+ `"--:doubleDashedLine"'
+ A dashed double horizontal line.
+
+ `"--:noLine"'
+ No line (but a small space is left).
+
+ `"--:shadowEtchedIn"'
+ A solid horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowEtchedOut"'
+ A solid horizontal line with a 3-d pushed-out appearance.
+
+ `"--:shadowDoubleEtchedIn"'
+ A solid double horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowDoubleEtchedOut"'
+ A solid double horizontal line with a 3-d pushed-out
+ appearance.
+
+ `"--:shadowEtchedInDash"'
+ A dashed horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowEtchedOutDash"'
+ A dashed horizontal line with a 3-d pushed-out appearance.
+
+ `"--:shadowDoubleEtchedInDash"'
+ A dashed double horizontal line with a 3-d recessed
+ appearance.
+
+ `"--:shadowDoubleEtchedOutDash"'
+ A dashed double horizontal line with a 3-d pushed-out
+ appearance.
+
+ * If an element of a menu is a list, it is treated as a submenu.
+ The name of that submenu (the first element in the list) will be
+ used as the name of the item representing this menu on the parent.
+
+ The possible keywords are as follows:
+
+:active FORM
+ FORM will be evaluated when the menu that this item is a part of
+ is about to be displayed, and the item will be selectable only if
+ the result is non-`nil'. If the item is unselectable, it will
+ usually be displayed grayed-out to indicate this.
+
+:suffix FORM
+ FORM will be evaluated when the menu that this item is a part of
+ is about to be displayed, and the resulting string is appended to
+ the displayed name. This provides a convenient way of adding the
+ name of a command's "argument" to the menu, like `Kill Buffer
+ NAME'.
+
+:keys STRING
+ Normally, the keyboard equivalents of commands in menus are
+ displayed when the "callback" is a symbol. This can be used to
+ specify keys for more complex menu items. It is passed through
+ `substitute-command-keys' first.
+
+:style STYLE
+ Specifies what kind of object this menu item is. STYLE be one of
+ the symbols
+
+ `nil'
+ A normal menu item.
+
+ `toggle'
+ A toggle button.
+
+ `radio'
+ A radio button.
+
+ `button'
+ A menubar button.
+
+ The only difference between toggle and radio buttons is how they
+ are displayed. But for consistency, a toggle button should be
+ used when there is one option whose value can be turned on or off,
+ and radio buttons should be used when there is a set of mutually
+ exclusive options. When using a group of radio buttons, you
+ should arrange for no more than one to be marked as selected at a
+ time.
+
+:selected FORM
+ Meaningful only when STYLE is `toggle', `radio' or `button'. This
+ specifies whether the button will be in the selected or unselected
+ state. FORM is evaluated, as for `:active'.
+
+:included FORM
+ This can be used to control the visibility of a menu item. The
+ form is evaluated and the menu item is only displayed if the
+ result is non-`nil'. Note that this is different from `:active':
+ If `:active' evaluates to `nil', the item will be displayed grayed
+ out, while if `:included' evaluates to `nil', the item will be
+ omitted entirely.
+
+:config SYMBOL
+ This is an efficient shorthand for `:included (memq SYMBOL
+ menubar-configuration)'. See the variable `menubar-configuration'.
+
+:accelerator KEY
+ A menu accelerator is a keystroke which can be pressed while the
+ menu is visible which will immediately activate the item. KEY
+ must be a char or the symbol name of a key. *Note Menu
+ Accelerators::.
+
+ - Variable: menubar-configuration
+ This variable holds a list of symbols, against which the value of
+ the `:config' tag for each menubar item will be compared. If a
+ menubar item has a `:config' tag, then it is omitted from the
+ menubar if that tag is not a member of the `menubar-configuration'
+ list.
+
+ For example:
+
+ ("File"
+ :filter file-menu-filter ; file-menu-filter is a function that takes
+ ; one argument (a list of menu items) and
+ ; returns a list of menu items
+ [ "Save As..." write-file]
+ [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
+ [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ]
+ )
+
+\1f
+File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
+
+Format of the Menubar
+=====================
+
+ A menubar is a list of menus, menu items, and strings. The format is
+similar to that of a menu, except:
+
+ * The first item need not be a string, and is not treated specially.
+
+ * A string consisting solely of hyphens is not treated specially.
+
+ * If an element of a menubar is `nil', then it is used to represent
+ the division between the set of menubar items which are flush-left
+ and those which are flush-right. (Note: this isn't completely
+ implemented yet.)
+
+\1f
+File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
+
+Menubar
+=======
+
+ - Variable: current-menubar
+ This variable holds the description of the current menubar. This
+ may be buffer-local. When the menubar is changed, the function
+ `set-menubar-dirty-flag' has to be called in order for the menubar
+ to be updated on the screen.
+
+ - Constant: default-menubar
+ This variable holds the menubar description of the menubar that is
+ visible at startup. This is the value that `current-menubar' has
+ at startup.
+
+ - Function: set-menubar-dirty-flag
+ This function tells XEmacs that the menubar widget has to be
+ updated. Changes to the menubar will generally not be visible
+ until this function is called.
+
+ The following convenience functions are provided for setting the
+menubar. They are equivalent to doing the appropriate action to change
+`current-menubar', and then calling `set-menubar-dirty-flag'. Note
+that these functions copy their argument using `copy-sequence'.
+
+ - Function: set-menubar menubar
+ This function sets the default menubar to be MENUBAR (*note Menu
+ Format::). This is the menubar that will be visible in buffers
+ that have not defined their own, buffer-local menubar.
+
+ - Function: set-buffer-menubar menubar
+ This function sets the buffer-local menubar to be MENUBAR. This
+ does not change the menubar in any buffers other than the current
+ one.
+
+ Miscellaneous:
+
+ - Variable: menubar-show-keybindings
+ If true, the menubar will display keyboard equivalents. If false,
+ only the command names will be displayed.
+
+ - Variable: activate-menubar-hook
+ Function or functions called before a menubar menu is pulled down.
+ These functions are called with no arguments, and should
+ interrogate and modify the value of `current-menubar' as desired.
+
+ The functions on this hook are invoked after the mouse goes down,
+ but before the menu is mapped, and may be used to activate,
+ deactivate, add, or delete items from the menus. However, using a
+ filter (with the `:filter' keyword in a menu description) is
+ generally a more efficient way of accomplishing the same thing,
+ because the filter is invoked only when the actual menu goes down.
+ With a complex menu, there can be a quite noticeable and
+ sometimes aggravating delay if all menu modification is
+ implemented using the `activate-menubar-hook'. See above.
+
+ These functions may return the symbol `t' to assert that they have
+ made no changes to the menubar. If any other value is returned,
+ the menubar is recomputed. If `t' is returned but the menubar has
+ been changed, then the changes may not show up right away.
+ Returning `nil' when the menubar has not changed is not so bad;
+ more computation will be done, but redisplay of the menubar will
+ still be performed optimally.
+
+ - Variable: menu-no-selection-hook
+ Function or functions to call when a menu or dialog box is
+ dismissed without a selection having been made.
+
+\1f
+File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
+
+Modifying Menus
+===============
+
+ The following functions are provided to modify the menubar of one of
+its submenus. Note that these functions modify the menu in-place,
+rather than copying it and making a new menu.
+
+ Some of these functions take a "menu path", which is a list of
+strings identifying the menu to be modified. For example, `("File")'
+names the top-level "File" menu. `("File" "Foo")' names a hypothetical
+submenu of "File".
+
+ Others take a "menu item path", which is similar to a menu path but
+also specifies a particular item to be modified. For example, `("File"
+"Save")' means the menu item called "Save" under the top-level "File"
+menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
+the "Foo" submenu of "Menu".
+
+ - Function: add-submenu menu-path submenu &optional before in-menu
+ This function adds a menu to the menubar or one of its submenus.
+ If the named menu exists already, it is changed.
+
+ MENU-PATH identifies the menu under which the new menu should be
+ inserted. If MENU-PATH is `nil', then the menu will be added to
+ the menubar itself.
+
+ SUBMENU is the new menu to add (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this menu
+ should be added, if this menu is not on its parent already. If
+ the menu is already present, it will not be moved.
+
+ If IN-MENU is present use that instead of `current-menubar' as the
+ menu to change.
+
+ - Function: add-menu-button menu-path menu-leaf &optional before
+ in-menu
+ This function adds a menu item to some menu, creating the menu
+ first if necessary. If the named item exists already, it is
+ changed.
+
+ MENU-PATH identifies the menu under which the new menu item should
+ be inserted.
+
+ MENU-LEAF is a menubar leaf node (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this item
+ should be added, if this item is not on the menu already. If the
+ item is already present, it will not be moved.
+
+ If IN-MENU is present use that instead of `current-menubar' as the
+ menu to change.
+
+ - Function: delete-menu-item menu-item-path &optional from-menu
+ This function removes the menu item specified by MENU-ITEM-PATH
+ from the menu hierarchy.
+
+ If FROM-MENU is present use that instead of `current-menubar' as
+ the menu to change.
+
+ - Function: enable-menu-item menu-item-path
+ This function makes the menu item specified by MENU-ITEM-PATH be
+ selectable.
+
+ - Function: disable-menu-item menu-item-path
+ This function makes the menu item specified by MENU-ITEM-PATH be
+ unselectable.
+
+ - Function: relabel-menu-item menu-item-path new-name
+ This function changes the string of the menu item specified by
+ MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
+ printed as from now on.
+
+ The following function can be used to search for a particular item in
+a menubar specification, given a path to the item.
+
+ - Function: find-menu-item menubar menu-item-path &optional parent
+ This function searches MENUBAR for the item given by
+ MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
+ of MENUBAR). This function returns `(ITEM . PARENT)', where
+ PARENT is the immediate parent of the item found (a menu
+ description), and ITEM is either a vector, list, or string,
+ depending on the nature of the menu item.
+
+ This function signals an error if the item is not found.
+
+ The following deprecated functions are also documented, so that
+existing code can be understood. You should not use these functions in
+new code.
+
+ - Function: add-menu menu-path menu-name menu-items &optional before
+ This function adds a menu to the menubar or one of its submenus.
+ If the named menu exists already, it is changed. This is
+ obsolete; use `add-submenu' instead.
+
+ MENU-PATH identifies the menu under which the new menu should be
+ inserted. If MENU-PATH is `nil', then the menu will be added to
+ the menubar itself.
+
+ MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
+ a list of menu items, strings, and submenus. These two arguments
+ are the same as the first and following elements of a menu
+ description (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this menu
+ should be added, if this menu is not on its parent already. If the
+ menu is already present, it will not be moved.
+
+ - Function: add-menu-item menu-path item-name function enabled-p
+ &optional before
+ This function adds a menu item to some menu, creating the menu
+ first if necessary. If the named item exists already, it is
+ changed. This is obsolete; use `add-menu-button' instead.
+
+ MENU-PATH identifies the menu under which the new menu item should
+ be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
+ second, and third elements of a menu item vector (*note Menu
+ Format::).
+
+ BEFORE, if provided, is the name of a menu item before which this
+ item should be added, if this item is not on the menu already. If
+ the item is already present, it will not be moved.
+
+\1f
+File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
+
+Menu Filters
+============
+
+ The following filter functions are provided for use in
+`default-menubar'. You may want to use them in your own menubar
+description.
+
+ - Function: file-menu-filter menu-items
+ This function changes the arguments and sensitivity of these File
+ menu items:
+
+ `Delete Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Print Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Pretty-Print Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Save Buffer'
+ Has the name of the current buffer appended to it, and is
+ sensitive only when the current buffer is modified.
+
+ `Revert Buffer'
+ Has the name of the current buffer appended to it, and is
+ sensitive only when the current buffer has a file.
+
+ `Delete Frame'
+ Sensitive only when there is more than one visible frame.
+
+ - Function: edit-menu-filter menu-items
+ This function changes the arguments and sensitivity of these Edit
+ menu items:
+
+ `Cut'
+ Sensitive only when XEmacs owns the primary X Selection (if
+ `zmacs-regions' is `t', this is equivalent to saying that
+ there is a region selected).
+
+ `Copy'
+ Sensitive only when XEmacs owns the primary X Selection.
+
+ `Clear'
+ Sensitive only when XEmacs owns the primary X Selection.
+
+ `Paste'
+ Sensitive only when there is an owner for the X Clipboard
+ Selection.
+
+ `Undo'
+ Sensitive only when there is undo information. While in the
+ midst of an undo, this is changed to `Undo More'.
+
+ - Function: buffers-menu-filter menu-items
+ This function sets up the Buffers menu. *Note Buffers Menu::, for
+ more information.
+
+\1f
File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus
Pop-Up Menus
============
- - Function: popup-menu menu-desc
- This function pops up a menu specified by MENU-DESC, which is a
- menu description (*note Menu Format::). The menu is displayed at
- the current mouse position.
+ - Function: popup-menu menu-description &optional event
+ This function pops up a menu specified by MENU-DESCRIPTION, which
+ is a menu description (*note Menu Format::). The menu is
+ displayed at the current mouse position.
- Function: popup-menu-up-p
This function returns `t' if a pop-up menu is up, `nil' otherwise.
The following convenience functions are provided for displaying
pop-up menus.
- - Function: popup-buffer-menu event
+ - Command: popup-buffer-menu event
This function pops up a copy of the `Buffers' menu (from the
- menubar) where the mouse is clicked.
+ menubar) where the mouse is clicked. It should be bound to a
+ mouse button event.
- - Function: popup-menubar-menu event
+ - Command: popup-menubar-menu event
This function pops up a copy of menu that also appears in the
- menubar.
+ menubar. It should be bound to a mouse button event.
\1f
File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
Menu Accelerator Functions
--------------------------
- - Function: accelerate-menu
+ - Command: accelerate-menu
Make the menubar immediately active and place the cursor on the
left most entry in the top level menu. Menu items can be selected
as usual.
* Menu:
* Toolbar Intro:: An introduction.
-* Toolbar Descriptor Format:: How to create a toolbar.
+* Creating Toolbar:: How to create a toolbar.
+* Toolbar Descriptor Format:: Accessing and modifying a toolbar's
+ properties.
* Specifying the Toolbar:: Setting a toolbar's contents.
* Other Toolbar Variables:: Controlling the size of toolbars.
\1f
-File: lispref.info, Node: Toolbar Intro, Next: Toolbar Descriptor Format, Up: Toolbar
+File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar
Toolbar Intro
=============
toolbar to the same position, it will just not be visible.
\1f
-File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Toolbar Intro, Up: Toolbar
+File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar
+
+Creating Toolbar
+================
+
+ - Function: make-toolbar-specifier spec-list
+ Return a new `toolbar' specifier object with the given
+ specification list. SPEC-LIST can be a list of specifications
+ (each of which is a cons of a locale and a list of instantiators),
+ a single instantiator, or a list of instantiators. *Note
+ Specifiers::, for more information about specifiers.
+
+ Toolbar specifiers are used to specify the format of a toolbar.
+ The values of the variables `default-toolbar', `top-toolbar',
+ `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
+ toolbar specifiers.
+
+ Valid toolbar instantiators are called "toolbar descriptors" and
+ are lists of vectors. See `default-toolbar' for a description of
+ the exact format.
+
+\1f
+File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
Toolbar Descriptor Format
=========================
Specifier for the toolbar at the right edge of the frame.
- Function: toolbar-specifier-p object
- This function returns non-nil if OBJECT is a toolbar specifier.
+ This function returns non-`nil' if OBJECT is a toolbar specifier.
Toolbar specifiers are the actual objects contained in the toolbar
variables described above, and their valid instantiators are
toolbar descriptors (*note Toolbar Descriptor Format::).
the left toolbar width for that frame to 68 pixels, then the frame will
be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
set the left toolbar width to 0 for a particular buffer (or if that
-buffer does not specify a left toolbar or has a nil value specified for
-`left-toolbar-visible-p'), you will find that, when that buffer is
+buffer does not specify a left toolbar or has a `nil' value specified
+for `left-toolbar-visible-p'), you will find that, when that buffer is
displayed in the selected window, the window will have a width of 86 or
87 characters--the frame is sized for a 68-pixel left toolbar but the
selected window specifies that the left toolbar is not visible, so it is
* Menu:
* Gutter Intro:: An introduction.
-* Gutter Descriptor Format:: How to create a gutter.
+* Creating Gutter:: How to create a gutter.
+* Gutter Descriptor Format:: Accessing and modifying a gutter's
+ properties.
* Specifying a Gutter:: Setting a gutter's contents.
* Other Gutter Variables:: Controlling the size of gutters.
* Common Gutter Widgets:: Things to put in gutters.
-\1f
-File: lispref.info, Node: Gutter Intro, Next: Gutter Descriptor Format, Up: Gutter
-
-Gutter Intro
-============
-
- A "gutter" is a rectangle displayed along one edge of a frame. It
-can contain arbitrary text or graphics. It could be considered a
-generalization of a toolbar, although toolbars are not currently
-implemented using gutters.
-
- In XEmacs, a gutter can be displayed along any of the four edges of
-the frame, and two or more different edges can be displaying gutters
-simultaneously. The contents, thickness, and visibility of the gutters
-can be controlled separately, and the values can be per-buffer,
-per-frame, etc., using specifiers (*note Specifiers::).
-
- Normally, there is one gutter displayed in a frame. Usually, this is
-the default gutter, containing buffer tabs, but modes cab override this
-and substitute their own gutter. This default gutter is usually
-positioned along the top of the frame, but this can be changed using
-`set-default-gutter-position'.
-
- Note that, for each of the gutter properties (contents, thickness,
-and visibility), there is a separate specifier for each of the four
-gutter positions (top, bottom, left, and right), and an additional
-specifier for the "default" gutter, i.e. the gutter whose position is
-controlled by `set-default-gutter-position'. The way this works is
-that `set-default-gutter-position' arranges things so that the
-appropriate position-specific specifiers for the default position
-inherit from the corresponding default specifiers. That way, if the
-position-specific specifier does not give a value (which it usually
-doesn't), then the value from the default specifier applies. If you
-want to control the default gutter, you just change the default
-specifiers, and everything works. A package such as VM that wants to
-put its own gutter in a different location from the default just sets
-the position-specific specifiers, and if the user sets the default
-gutter to the same position, it will just not be visible.
-
-\1f
-File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Gutter Intro, Up: Gutter
-
-Gutter Descriptor Format
-========================
-
- The contents of a gutter are specified using a "gutter descriptor".
-The format of a gutter descriptor is a list of "gutter button
-descriptors". Each gutter button descriptor is a vector in one of the
-following formats:
-
- * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
-
- * `[:style 2D-OR-3D]'
-
- * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
-
- * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
-
- Optionally, one of the gutter button descriptors may be `nil'
-instead of a vector; this signifies the division between the gutter
-buttons that are to be displayed flush-left, and the buttons to be
-displayed flush-right.
-
- The first vector format above specifies a normal gutter button; the
-others specify blank areas in the gutter.
-
- For the first vector format:
-
- * GLYPH-LIST should be a list of one to six glyphs (as created by
- `make-glyph') or a symbol whose value is such a list. The first
- glyph, which must be provided, is the glyph used to display the
- gutter button when it is in the "up" (not pressed) state. The
- optional second glyph is for displaying the button when it is in
- the "down" (pressed) state. The optional third glyph is for when
- the button is disabled. The last three glyphs are for displaying
- the button in the "up", "down", and "disabled" states,
- respectively, but are used when the user has called for captioned
- gutter buttons (using `gutter-buttons-captioned-p'). The function
- `gutter-make-button-list' is useful in creating these glyph lists.
-
- * Even if you do not provide separate down-state and disabled-state
- glyphs, the user will still get visual feedback to indicate which
- state the button is in. Buttons in the up-state are displayed
- with a shadowed border that gives a raised appearance to the
- button. Buttons in the down-state are displayed with shadows that
- give a recessed appearance. Buttons in the disabled state are
- displayed with no shadows, giving a 2-d effect.
-
- * If some of the gutter glyphs are not provided, they inherit as
- follows:
-
- UP: up
- DOWN: down -> up
- DISABLED: disabled -> up
- CAP-UP: cap-up -> up
- CAP-DOWN: cap-down -> cap-up -> down -> up
- CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
-
- * The second element FUNCTION is a function to be called when the
- gutter button is activated (i.e. when the mouse is released over
- the gutter button, if the press occurred in the gutter). It can
- be any form accepted by `call-interactively', since this is how it
- is invoked.
-
- * The third element ENABLED-P specifies whether the gutter button is
- enabled (disabled buttons do nothing when they are activated, and
- are displayed differently; see above). It should be either a
- boolean or a form that evaluates to a boolean.
-
- * The fourth element HELP, if non-`nil', should be a string. This
- string is displayed in the echo area when the mouse passes over the
- gutter button.
-
- For the other vector formats (specifying blank areas of the gutter):
-
- * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
- whether the area is displayed with shadows (giving it a raised,
- 3-d appearance) or without shadows (giving it a flat appearance).
-
- * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
- area. If omitted, it defaults to a device-specific value (8
- pixels for X devices).
-
- - Function: gutter-make-button-list up &optional down disabled cap-up
- cap-down cap-disabled
- This function calls `make-glyph' on each arg and returns a list of
- the results. This is useful for setting the first argument of a
- gutter button descriptor (typically, the result of this function
- is assigned to a symbol, which is specified as the first argument
- of the gutter button descriptor).
-
- - Function: check-gutter-button-syntax button &optional noerror
- Verify the syntax of entry BUTTON in a gutter description list.
- If you want to verify the syntax of a gutter description list as a
- whole, use `check-valid-instantiator' with a specifier type of
- `gutter'.
-
-\1f
-File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
-
-Specifying a Gutter
-===================
-
- In order to specify the contents of a gutter, set one of the
-specifier variables `default-gutter', `top-gutter', `bottom-gutter',
-`left-gutter', or `right-gutter'. These are specifiers, which means
-you set them with `set-specifier' and query them with `specifier-specs'
-or `specifier-instance'. You will get an error if you try to set them
-using `setq'. The valid instantiators for these specifiers are gutter
-descriptors, as described above. *Note Specifiers::, for more
-information.
-
- Most of the time, you will set `default-gutter', which allows the
-user to choose where the gutter should go.
-
- - Specifier: default-gutter
- The position of this gutter is specified in the function
- `default-gutter-position'. If the corresponding position-specific
- gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
- does not specify a gutter in a particular domain, then the value
- of `default-gutter' in that domain, of any, will be used instead.
-
- Note that the gutter at any particular position will not be displayed
-unless its thickness (width or height, depending on orientation) is
-non-zero and its visibility status is true. The thickness is controlled
-by the specifiers `top-gutter-height', `bottom-gutter-height',
-`left-gutter-width', and `right-gutter-width', and the visibility
-status is controlled by the specifiers `top-gutter-visible-p',
-`bottom-gutter-visible-p', `left-gutter-visible-p', and
-`right-gutter-visible-p' (*note Other Gutter Variables::).
-
- - Function: set-default-gutter-position position
- This function sets the position that the `default-gutter' will be
- displayed at. Valid positions are the symbols `top', `bottom',
- `left' and `right'. What this actually does is set the fallback
- specifier for the position-specific specifier corresponding to the
- given position to `default-gutter', and set the fallbacks for the
- other position-specific specifiers to `nil'. It also does the
- same thing for the position-specific thickness and visibility
- specifiers, which inherit from one of `default-gutter-height' or
- `default-gutter-width', and from `default-gutter-visible-p',
- respectively (*note Other Gutter Variables::).
-
- - Function: default-gutter-position
- This function returns the position that the `default-gutter' will
- be displayed at.
-
- You can also explicitly set a gutter at a particular position. When
-redisplay determines what to display at a particular position in a
-particular domain (i.e. window), it first consults the position-specific
-gutter. If that does not yield a gutter descriptor, the
-`default-gutter' is consulted if `default-gutter-position' indicates
-this position.
-
- - Specifier: top-gutter
- Specifier for the gutter at the top of the frame.
-
- - Specifier: bottom-gutter
- Specifier for the gutter at the bottom of the frame.
-
- - Specifier: left-gutter
- Specifier for the gutter at the left edge of the frame.
-
- - Specifier: right-gutter
- Specifier for the gutter at the right edge of the frame.
-
- - Function: gutter-specifier-p object
- This function returns non-nil if OBJECT is a gutter specifier.
- Gutter specifiers are the actual objects contained in the gutter
- variables described above, and their valid instantiators are
- gutter descriptors (*note Gutter Descriptor Format::).
-
-\1f
-File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
-
-Other Gutter Variables
-======================
-
- The variables to control the gutter thickness, visibility status, and
-captioned status are all specifiers. *Note Specifiers::.
-
- - Specifier: default-gutter-height
- This specifies the height of the default gutter, if it's oriented
- horizontally. The position of the default gutter is specified by
- the function `set-default-gutter-position'. If the corresponding
- position-specific gutter thickness specifier (e.g.
- `top-gutter-height' if `default-gutter-position' is `top') does
- not specify a thickness in a particular domain (a window or a
- frame), then the value of `default-gutter-height' or
- `default-gutter-width' (depending on the gutter orientation) in
- that domain, if any, will be used instead.
-
- - Specifier: default-gutter-width
- This specifies the width of the default gutter, if it's oriented
- vertically. This behaves like `default-gutter-height'.
-
- Note that `default-gutter-height' is only used when
-`default-gutter-position' is `top' or `bottom', and
-`default-gutter-width' is only used when `default-gutter-position' is
-`left' or `right'.
-
- - Specifier: top-gutter-height
- This specifies the height of the top gutter.
-
- - Specifier: bottom-gutter-height
- This specifies the height of the bottom gutter.
-
- - Specifier: left-gutter-width
- This specifies the width of the left gutter.
-
- - Specifier: right-gutter-width
- This specifies the width of the right gutter.
-
- Note that all of the position-specific gutter thickness specifiers
-have a fallback value of zero when they do not correspond to the
-default gutter. Therefore, you will have to set a non-zero thickness
-value if you want a position-specific gutter to be displayed.
-
- - Specifier: default-gutter-visible-p
- This specifies whether the default gutter is visible. The
- position of the default gutter is specified by the function
- `set-default-gutter-position'. If the corresponding
- position-specific gutter visibility specifier (e.g.
- `top-gutter-visible-p' if `default-gutter-position' is `top') does
- not specify a visible-p value in a particular domain (a window or
- a frame), then the value of `default-gutter-visible-p' in that
- domain, if any, will be used instead.
-
- - Specifier: top-gutter-visible-p
- This specifies whether the top gutter is visible.
-
- - Specifier: bottom-gutter-visible-p
- This specifies whether the bottom gutter is visible.
-
- - Specifier: left-gutter-visible-p
- This specifies whether the left gutter is visible.
-
- - Specifier: right-gutter-visible-p
- This specifies whether the right gutter is visible.
-
- `default-gutter-visible-p' and all of the position-specific gutter
-visibility specifiers have a fallback value of true.
-
- Internally, gutter thickness and visibility specifiers are
-instantiated in both window and frame domains, for different purposes.
-The value in the domain of a frame's selected window specifies the
-actual gutter thickness or visibility that you will see in that frame.
-The value in the domain of a frame itself specifies the gutter
-thickness or visibility that is used in frame geometry calculations.
-
- Thus, for example, if you set the frame width to 80 characters and
-the left gutter width for that frame to 68 pixels, then the frame will
-be sized to fit 80 characters plus a 68-pixel left gutter. If you then
-set the left gutter width to 0 for a particular buffer (or if that
-buffer does not specify a left gutter or has a nil value specified for
-`left-gutter-visible-p'), you will find that, when that buffer is
-displayed in the selected window, the window will have a width of 86 or
-87 characters - the frame is sized for a 68-pixel left gutter but the
-selected window specifies that the left gutter is not visible, so it is
-expanded to take up the slack.
-
- - Specifier: gutter-buttons-captioned-p
- Whether gutter buttons are captioned. This affects which glyphs
- from a gutter button descriptor are chosen. *Note Gutter
- Descriptor Format::.
-
- You can also reset the gutter to what it was when XEmacs started up.
-
- - Constant: initial-gutter-spec
- The gutter descriptor used to initialize `default-gutter' at
- startup.
-
-\1f
-File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
-
-Common Gutter Widgets
-=====================
-
- A gutter can contain arbitrary text. So, for example, in an Info
-buffer you could put the title of the current node in the top gutter,
-and it would not scroll out of view in a long node. (This is an
-artificial example, since usually the node name is sufficiently
-descriptive, and Info puts that in the mode line.)
-
- A more common use for the gutter is to hold some kind of active
-widget. The buffer-tab facility, available in all XEmacs frames,
-creates an array of file-folder-like tabs, which the user can click with
-the mouse to switch buffers. W3 uses a progress-bar widget in the
-bottom gutter to give a visual indication of the progress of
-time-consuming operations like downloading.
-
-* Menu:
-
-* Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
-* Progress Bars:: Visual indication of operation progress.
-
-\1f
-File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
-
-Buffer Tabs
-===========
-
- Not documented yet.
-
-\1f
-File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
-
-Progress Bars
-=============
-
- Not documented yet.
-
-\1f
-File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
-
-Scrollbars
-**********
-
- Not yet documented.
-
-\1f
-File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
-
-Drag and Drop
-*************
-
- _WARNING_: the Drag'n'Drop API is still under development and the
-interface may change! The current implementation is considered
-experimental.
-
- Drag'n'drop is a way to transfer information between multiple
-applications. To do this several GUIs define their own protocols.
-Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
-To catch all these protocols, XEmacs provides a generic API.
-
- One prime idea behind the API is to use a data interface that is
-transparent for all systems. The author thinks that this is best
-archived by using URL and MIME data, cause any internet enabled system
-must support these for email already. XEmacs also already provides
-powerful interfaces to support these types of data (tm and w3).
-
-* Menu:
-
-* Supported Protocols:: Which low-level protocols are supported.
-* Drop Interface:: How XEmacs handles a drop from another application.
-* Drag Interface:: Calls to initiate a drag from XEmacs.
-
-\1f
-File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
-
-Supported Protocols
-===================
-
- The current release of XEmacs only support a small set of Drag'n'drop
-protocols. Some of these only support limited options available in the
-API.
-
-* Menu:
-
-* OffiX DND:: A generic X based protocol.
-* CDE dt:: Common Desktop Environment used on suns.
-* MSWindows OLE:: Mr. Gates way of live.
-* Loose ends:: The other protocols.
-
-\1f
-File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
-
-OffiX DND
----------
-
- _WARNING_: If you compile in OffiX, you may not be able to use
-multiple X displays successfully. If the two servers are from
-different vendors, the results may be unpredictable.
-
- The OffiX Drag'n'Drop protocol is part of a X API/Widget library
-created by Cesar Crusius. It is based on X-Atoms and ClientMessage
-events, and works with any X platform supporting them.
-
- OffiX is supported if 'offix is member of the variable
-dragdrop-protocols, or the feature 'offix is defined.
-
- Unfortunately it uses it's own data types. Examples are: File, Files,
-Exe, Link, URL, MIME. The API tries to choose the right type for the
-data that is dragged from XEmacs (well, not yet...).
-
- XEmacs supports both MIME and URL drags and drops using this API. No
-application interaction is possible while dragging is in progress.
-
- For information about the OffiX project have a look at
-http://leb.net/~offix/
-
-\1f
-File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
-
-CDE dt
-------
-
- CDE stands for Common Desktop Environment. It is based on the Motif
-widget library. It's drag'n'drop protocol is also an abstraction of the
-Motif protocol (so it might be possible, that XEmacs will also support
-the Motif protocol soon).
-
- CDE has three different types: file, buffer, and text. XEmacs only
-uses file and buffer drags. The API will disallow full URL drags, only
-file method URLs are passed through.
-
- Buffer drags are always converted to plain text.
-
-\1f
-File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
-
-MSWindows OLE
--------------
-
- Only allows file drags and drops.
-
-\1f
-File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
-
-Loose ends
-----------
-
- The following protocols will be supported soon: Xdnd, Motif, Xde (if
-I get some specs), KDE OffiX (if KDE can find XEmacs windows).
-
- In particular Xdnd will be one of the protocols that can benefit from
-the XEmacs API, cause it also uses MIME types to encode dragged data.
-
-\1f
-File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
-
-Drop Interface
-==============
-
- For each activated low-level protocol, a internal routine will catch
-incoming drops and convert them to a dragdrop-drop type misc-user-event.
-
- This misc-user-event has its function argument set to
-`dragdrop-drop-dispatch' and the object contains the data of the drop
-(converted to URL/MIME specific data). This function will search the
-variable `experimental-dragdrop-drop-functions' for a function that can
-handle the dropped data.
-
- To modify the drop behavior, the user can modify the variable
-`experimental-dragdrop-drop-functions'. Each element of this list
-specifies a possible handler for dropped data. The first one that can
-handle the data will return `t' and exit. Another possibility is to set
-a extent-property with the same name. Extents are checked prior to the
-variable.
-
- The customization group `drag-n-drop' shows all variables of user
-interest.
-
-\1f
-File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
-
-Drag Interface
-==============
-
- This describes the drag API (not implemented yet).
-
-\1f
-File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
-
-Major and Minor Modes
-*********************
-
- A "mode" is a set of definitions that customize XEmacs and can be
-turned on and off while you edit. There are two varieties of modes:
-"major modes", which are mutually exclusive and used for editing
-particular kinds of text, and "minor modes", which provide features
-that users can enable individually.
-
- This chapter describes how to write both major and minor modes, how
-to indicate them in the modeline, and how they run hooks supplied by the
-user. For related topics such as keymaps and syntax tables, see *Note
-Keymaps::, and *Note Syntax Tables::.
-
-* Menu:
-
-* Major Modes:: Defining major modes.
-* Minor Modes:: Defining minor modes.
-* Modeline Format:: Customizing the text that appears in the modeline.
-* Hooks:: How to use hooks; how to write code that provides hooks.
-