Info file ../info/epoch, produced by Makeinfo, -*- Text -*- from input file epoch.texinfo. This file documents Epoch 4.1, a modified version of GNU Emacs. Copyright (C) 1989, 1990, 1991, 1992 by The Epoch Development Team: Simon Kaplan (`kaplan@cs.uicu.edu'); Leadership, design, manual Christopher Love (`love@cs.uiuc.edu'); Implementation, design, manual, support Alan M. Carroll (`carroll@cs.uiuc.edu'); Implementation, design, manual Daniel M. LaLiberte (`liberte@cs.uiuc.edu'); Manual support Marc Andreessen (`marca@cs.uiuc.edu'); Epoch 4.0+ support Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: epoch, Node: Mouse Events, Next: Motion Events, Prev: Client Message Events, Up: Events Mouse Events ============ Mouse events go into the event queue with event type `button' and event value the 5-tuple `(PRESS/RELEASE X-COORD Y-COORD BUTTON MOD-STATE)'. PRESS/RELEASE indicates if the event was a button press or release; the coordinates are character coordinates within the screen; BUTTON indicates which button; and the MOD-STATE is a bitmask indicating the state of the button modifiers. Note: Mouse events are only received on the keyboard queue when `epoch::mouse-events' is `nil'. This is the default value, but the Epoch Elisp files set it to `t'. The Epoch Elisp files install a handler for the `button' events, which in turn dispatches functions for each different mouse event. Mouse event dispatching uses two tables, one global and the other local to each buffer. When a mouse event is dispatched, the local table is checked first. If the table is missing or the entry is `nil', then the global table is used. If a function is found, then it is dispatched. The mouse event handler should be defined as follows: (defun my-mouse-handler (MOUSE-DATA) "MOUSE-DATA is a list of `( POINT BUFFER WINDOW SCREEN )'. These all refer to the character location at which the button on the mouse was pressed or released. Note that at the time the handler is called, no change to point, current buffer, current window or current screen has been made. It is entirely up to the handler how much to change such information.") When specifying a particular mouse event, both the mouse button and keyboard "modifier" states must be specified, e.g., the middle button with Control. Note that separate mouse button codes exist for button presses in the window, mode line, and minibuffer. These values are specified as numbers, but for ease of programming, constants are defined for them, listed below. These are the predefined constants for specifying the mouse button: Note that these match codes in `mouse::event-data'. `Name' Value `mouse-left' 1 `mouse-middle' 2 `mouse-right' 3 `mouse-mode-left' 4 `mouse-mode-middle' 5 `mouse-mode-right' 6 `mouse-minibuf-left' 7 `mouse-minibuf-middle' 8 `mouse-minibuf-right' 9 These are the predefined constants for specifying the keyboard modifier state. Names without a trailing `-up' signify the down button event. `Name' Value `mouse-down' 0 `mouse-up' 1 `mouse-shift' 2 `mouse-shift-up' 3 `mouse-control' 4 `mouse-control-up' 5 `mouse-control-shift' 6 `mouse-control-shift-up' 7 `mouse-meta' 8 `mouse-meta-up' 9 `mouse-meta-shift' 10 `mouse-meta-shift-up' 11 `mouse-meta-control' 12 `mouse-meta-control-up' 13 `mouse-meta-control-shift' 14 `mouse-meta-control-shift-up' 15 Note: In that version, the passed argument was a list of the form `(X Y SCREEN)' of the mouse event. This data was not particularly useful, and had to be converted into more useful data by actually setting point with the `x-mouse-set-point' call. A look through the mouse handling code indicated that, in fact, every function went ahead and did this in order to calculate the point. The following functions are modeled after keymaps. * Function: create-mouse-map &optional SOURCE-MAP Creates a mouse map for use in dispatching. If SOURCE-MAP is non-`nil', then the contents of that map are copied into the new map. * Function: copy-mouse-map SOURCE-MAP DEST-MAP Copies a mouse map from SOURCE-MAP to DEST-MAP. * Function: use-local-mouse-map MOUSE-MAP &optional BUFFER Sets MOUSE-MAP to be the local mouse map in BUFFER. * Function: kill-local-mouse-map &optional BUFFER Removes the local mouse map from BUFFER. * Function: define-mouse MOUSE-MAP BUTTON MODIFIER FUNCTION Sets the entry in MOUSE-MAP for the mouse BUTTON with MODIFIER to be FUNCTION. BUTTON should be one of the mouse button constants, and MODIFIER should be one of the button modifiers. * Function: local-set-mouse BUTTON MODIFIER FUNCTION Sets the entry in the local mouse map for BUTTON and MODIFIER to FUNCTION. * Function: global-set-mouse BUTTON MODIFIER FUNCTION Sets the entry in the global mouse map for BUTTON and MODIFIER to FUNCTION. * Function: mouse::set-point MOUSE-DATA Sets the point to the value specified in MOUSE-DATA, which should be the same form as the list passed to mouse handler functions, (`point' `buffer' `window' `screen') * Function: coordinates-in-window-p POSITION WINDOW Returns `t' if position described by POSITION is in WINDOW. POSITION is a list of the form (screen-x screen-y). * Function: epoch::coords-to-point X Y SCREEN Converts a pixel (X, Y) location on a given SCREEN into a list of the form `(point buffer window screen)' or `nil' if the location is not on the SCREEN. POINT is returned as `nil' if location is in window's modeline. Data pertaining to the most recent button press event is available in the following variables. Note that this enables the detection of multiple mouse clicks. * Variable: mouse::interval 200 The number of milliseconds allowed between multiple mouse clicks. Interval is clocked between down-click and the previous up-click. * Variable: mouse::x X screen position of last mouse button press, in pixels. * Variable: mouse::y Y screen position of last mouse button press, in pixels. * Variable: mouse::last-spot Mouse data of the last event (point buffer window screen). * Variable: mouse::time-stamp Millisecond time of the last up-click. * Variable: mouse::clicks The number of times mouse button was pressed and released.  File: epoch, Node: Motion Events, Next: On Event Handling, Prev: Mouse Events, Up: Events Motion Events ============= Epoch allows the user to receive motion events, which occur when the mouse moves. By default this feature is turned off. It can be enabled in a number of ways: * By using command line option `-motion': makes motion events appear for all screens. * By using `*motion' in resources: makes motion events appear for all screens. * By using `motion' in the property alist; `t' turns on motion events at screen creation time, `nil' disables them. * By using primitive `epoch::set-motion-hints': turns motion events on or off by screen. Note that motion events go into the event-queue but must be specifically solicited by functions rather than being automatically provided. Each time you execute a function affecting the mouse (for example, `epoch::query-pointer'), the next motion event (if any) is sent to the primitive. This prevents motion events from coming so fast that Epoch would thrash to death. The relevant primitives are: * Function: epoch::motion-hints-p &optional SCREEN Returns `t' or `nil' for SCREEN (default: current screen) depending if motion events are enabled or disabled for that screen. * Function: epoch::set-motion-hints FLAG &optional SCREEN Flag must be `t' or `nil'; enables or disables motion hints for SCREEN (default: current screen).  File: epoch, Node: On Event Handling, Prev: Motion Events, Up: Events On Event Handling ================= As part of the standard event handling, a facility to install one-shot handlers for events on particular screens is provided. After the action function has been called for the particular event, it is removed. * Function: on-map-do SCREEN ACTION On the next map event for SCREEN, call ACTION with a single argument that is the screen of the event. * Function: on-unmap-do SCREEN ACTION On the next unmap event for SCREEN, call ACTION with a single argument that is the screen of the event. * Function: on-move-do SCREEN ACTION On the next move event for SCREEN, call ACTION with two arguments, the screen and the move event value. * Function: on-resize-do SCREEN ACTION On the next resize event for SCREEN, call ACTION with two arguments, the screen and the resize event value.  File: epoch, Node: X11 Primitives, Next: Miscellaneous, Prev: Events, Up: top X11 Primitives ************** * Menu: * X Resources:: X Resources * X Objects:: Creating X objects * Client Messages:: Sending client messages * X Properties:: Getting/Setting X window properties * X Selections:: Using X selections * X Cursor:: Manipulating the X Cursor * Other X Stuff:: Other Stuff Here we describe various primitive X11 facilities.  File: epoch, Node: X Resources, Next: X Objects, Prev: X11 Primitives, Up: X11 Primitives X Resources =========== Epoch X Resources give the ability to work with raw ``X resources'', such as the X server's internal ID numbers for screens (X ``windows''). These numbers are too big to fit into the standard GNU Emacs number size, so they are made into a special opaque type called an "X-resource". X-resources contain X id information (a 32 bit quantity) and a type (an X atom). When the type of an Epoch X Resource is a predefined value (such as "X-Atom"), then it is referred to by that type, (e.g., X-atom resource). Currently recognized types are `Arc', `Atom', `Bitmap', `Cardinal', `Cursor', `Drawable', `Font', `Integer', `Pixmap', `Point', `Rectangle', `String', `Window', `WMHints', `WM Size Hints' or `Resource' (untyped). * Function: epoch::intern-atom NAME Interns the string NAME as an X-atom resource (as opposed to an Elisp atom). NAME should be a string. X-atom resources are 32-bit numbers that represent strings in the X Window System. They are used for typing information on X data objects. * Function: epoch::unintern-atom NAME Converts the X-atom Resource NAME into an Elisp string. Note that the atom is not removed from the X server. * Function: epoch::resourcep ARG Returns `t' if ARG is an X resource, `nil' otherwise. In addition, the primitive `equal' has been extended to accept X resources. Two resources are `equal' if their values are the same, regardless of type. * Function: epoch::string-to-resource STRING TYPE Converts an Elisp STRING to an X resource (raw window id, for example) of given TYPE. STRING is assumed to represent a 32-bit numeric value in the C language numeric literal format. TYPE must be an X-atom resource. * Function: epoch::resource-to-type RESOURCE Returns an X resource whose type is `atom' and whose value is the type of RESOURCE. * Function: epoch::resource-to-string RESOURCE &optional BASE Convert the id of RESOURCE to a numeric string. Optional BASE specifies the base for the conversion (may be 2 through 36 inclusive). Note that no special notation is used to signify the base. * Function: epoch::xid-of-screen &optional SCREEN Returns the X resource value for SCREEN (default is the current screen). * Function: epoch::set-resource-type RESOURCE TYPE Sets the type field of RESOURCE to the value of TYPE. TYPE must be an X-atom resource. Returns RESOURCE if it was successfully modified, nil otherwise.  File: epoch, Node: X Objects, Next: Client Messages, Prev: X Resources, Up: X11 Primitives X Objects ========= Several types of X objects can be encapsulated into Elisp. Each is stored in Epoch as its X resource ID, in an X-resource data object. When a function claims that it returns the X object, this should be taken to mean that it returns an X-resource with the resource ID and type stored in it. These resources can be manipulated with various functions, *Note X Resources::. * Function: epoch::get-font NAME Loads the font into the server, and returns the X Resource associated with it, or `nil' if NAME isn't a valid font. * Function: epoch::get-color COLOR Allocates a slot in the X server default colormap for the COLOR. Returns an X Resource of type Cardinal, which is the pixel value for the COLOR. COLOR can be a color name, a vector of length 3 specifying the red, green, blue components, or an X Resource of type Cardinal. If the last, it is simply returned (this is so the function can be called on any representation without generating an error). * Function: epoch::free-color COLOR Releases the X server colormap slot corresponding to the COLOR. COLOR must be an X Resource of type Cardinal. No checking is done to verify that the color was allocated by Epoch, or is available for release. Once released, the pixel value can be reused for a different color, so that anything still displayed in the color may change at any time (through the action of another X client, or Epoch). * Function: epoch::color-components COLOR Return a 3-vector containing the red, green and blue components of COLOR, which should be an X Resource of type Cardinal. * Function: epoch::get-color-rw COLOR Allocates a read-write color cell for COLOR. Returns an X Resource of type Cardinal if successful; otherwise `nil'. * Function: epoch::set-color-rw CELL NAME Set read-write color cell CELL to NAME. CELL must be an X Resource of type Cardinal; NAME may be a string, vector, or color name. * Function: epoch::make-bitmap WIDTH HEIGHT BYTE-STRING Creates a bitmap, and returns it. The WIDTH and HEIGHT should be positive integers, specifying the size of the bitmap. There is no way to change the size once the bitmap has been created. The BYTE-STRING should be a string, which will be interpreted as an array of bytes, not characters per se. The format corresponds directly to the standard X11 bitmap format. Each row of the bitmap is in integral number of bytes, floor(WIDTH+7 / 8) long, and should consist of HEIGHT rows. * Function: epoch::load-bitmap FILE Creates a bitmap, based on the information in FILE. FILE should include the absolute pathname as well as filename of a standard X bitmap file. * Function: epoch::free-bitmap BITMAP Releases a bitmap from the X server. The bitmap should *not* be used again, even indirectly (e.g., in a style).  File: epoch, Node: Client Messages, Next: X Properties, Prev: X Objects, Up: X11 Primitives Client Messages --------------- * Function: epoch::send-client-message TO &optional FROM DATA TYPE FORMAT Sends a client message of TYPE with DATA to the destination TO using FORMAT and DATA. The parameters have the following meaning: TO A screen or an X Resource of type Window. *Note X11 Primitives:: for more information. FROM A screen or an X Resource of type Window that serves as the source of the message. This defaults to the current screen. DATA The message data may be `nil' if there is no data, integer, string, or a list or vector of integers or X-resources. If it is simply a string, the first 20 characters are transmitted, and interpreted as 1, 2 or 4-byte data on the other end according to the FORMAT parameter. If DATA is `nil', `0's are sent. TYPE This is an X-atom (as opposed to an Elisp atom) and can be created by `intern-atom'. Usually something which conveys the meaning of the message, e.g., `WM_CHANGE_STATE'. FORMAT The data for a client message is always 20 bytes long. The format statement tells how to interpret this. The value must be one of the following: `nil' The format defaults to a value appropriate for the data, as determined by Epoch. `8' for 20 1-byte data objects. `16' for 10 2-byte objects. `32' for 5 4-byte objects. ;; Fake an iconify message (setq xroot (car (query-tree))) ; get the root window ;; IconicState is 3 ;; Send to the root window, from the current screen, ;; with data 3 of type WM_CHANGE_STATE. (send-client-message xroot nil 3 (intern-atom "WM_CHANGE_STATE"))  File: epoch, Node: X Properties, Next: X Selections, Prev: Client Messages, Up: X11 Primitives X Properties ------------ * Function: epoch::get-property NAME &optional SCREEN Returns the X-Property NAME on the SCREEN. SCREEN can be an X resource. NAME can be an X-atom resource or a string. The property value is returned in the most (in Epoch's opinion) convenient form. If the property is an array of items (e.g., the count return value is more than 1) then it is returned as a list. Strings are converted to Elisp strings, integers into Elisp integers (with a possible loss of precision, since Elisp integers are less than 32 bits), and other 32-bit types into X-resources. Strings are handled specially - if nulls are found in the returned byte array, they are assumed to represent string seperators, and that the property is an array of these null-seperated substrings. If there is a failure (bad screen, no property, bad type, etc.), then `nil' is returned. * Function: epoch::set-property NAME VALUE &optional SCREEN Sets the X-property NAME to VALUE on the X SCREEN. SCREEN can be an X resource. NAME can be an X-Atom resource or a string. VALUE must be a string, an integer, an X-resource, or an vector or list of these types. If it is a vector or list, the types of all the sequence elements must be the same, and for X-resources the X-resource types must also be the same.  File: epoch, Node: X Selections, Next: X Cursor, Prev: X Properties, Up: X11 Primitives X Selections ------------ * Function: epoch::get-selection-owner SELECTION Returns an X Resource of type Window corresponding to the X11 client owning SELECTION. SELECTION may be an X-Atom Resource or a string. If SELECTION is not owned by any client, NIL is returned. * Function: epoch::acquire-selection SELECTION &optional SCREEN Asserts ownership of SELECTION for the X SCREEN. SCREEN can be an X resource. Uses current screen if no SCREEN is given. If SCREEN is `t', set SELECTION owner to `None', and send Epoch a `selection-clear' event. Note that SELECTION's data should be stored in `epoch::selection-alist' so that Epoch can internally handle conversion requests and possible loss of ownership to other X11 clients. * Function: epoch::convert-selection SELECTION TARGET PROPERTY &optional SCREEN Requests owner of SELECTION to convert selection's data to type TARGET and store result in PROPERTY. Property will be hung on SCREEN, or current screen if no SCREEN argument is given. This function will wait internally for the selection value to be available, and will return this value if the selection is owned by a client and no timeout occurs waiting for the client response. * Variable: epoch::selection-timeout 2 This variable describes the amount of time (in seconds) for the `epoch::convert-selection' function to wait for a response before returning `nil'. This pause will not occur in the event the selection is unowned. * Variable: epoch::selection-alist This variable will hold an alist of (`atom' . `value') for all selections owned by Epoch X windows. It is the responsibility of the Elisp code under Epoch to store data in this alist upon asserting ownership of any selections. When `selection-clear' events are processed, the corresponding entry is deleted from the alist. When `selection-request' events are processed internally, Epoch looks in this alist for selection data to be converted. Currently, selection data must be of type `String'; the selection-notify event structure is set to `None' for invalid requests or requests of selections with `null' data. * Variable: epoch::convert-selection-alist This variable will hold an alist of (`atom' `function') for any user-supplied target atoms. FUNCTION will be called with no arguments, and should return either a string or `nil'.  File: epoch, Node: X Cursor, Next: Other X Stuff, Prev: X Selections, Up: X11 Primitives X Cursor -------- * Function: epoch::query-pointer &optional SCREEN-OR-XWIN Returns a list containing x-coordinate, y-coordinate (in pixels) and state of mouse. Uses current screen if no SCREEN argument is given. * Function: epoch::warp-pointer X Y &optional SCREEN-OR-XWIN Warps cursor to (X,Y) location (in pixels) on SCREEN relative to the upper-left corner. Uses current screen if no SCREEN argument is given. * Function: epoch::ungrab-pointer Ungrabs the pointer. This is useful after a mouse down event, so that another X client can act before the mouse up event. * Function: epoch::query-mouse &optional SCREEN Returns a list containing x-coordinate, y-coordinate (in character position) and state of mouse. Uses current screen if no SCREEN argument is given. * Function: epoch::warp-mouse X Y &optional SCREEN Warps cursor to (X,Y) location (in character position) on SCREEN. Uses current screen if no SCREEN argument is given. * Function: epoch::query-cursor &optional SCREEN Returns a list (X . Y) corresponding to the cursor position in characters. Uses current screen if no SCREEN argument is given. * Function: epoch::query-cursor-pixels &optional SCREEN Returns a list (X . Y) corresponding to the cursor position in pixels (Upperleft corner of cursor). Uses current screen if no SCREEN argument is given.  File: epoch, Node: Other X Stuff, Prev: X Cursor, Up: X11 Primitives Other X Stuff ============= * Function: epoch::get-default NAME &optional CLASS Does a lookup into X Resources database for NAME and CLASS (if specified). Returns a string for the definition, or `nil' if lookup request failed. * Function: epoch::rebind-key KEYSYM SHIFTMASK STRING Rebinds a raw X key. Takes as arguments the KEYSYM to rebind, the SHIFTMASK for the rebinding, and a STRING to send when that key is pressed. KEYSYM should be a string, naming the keysym. SHIFTMASK should be one of the following: `integer' This is a bit-mask, with a bit for every modifier, just like an X shift state. `symbol' The symbol should be one of `'shift', `'lock', `'control', `'meta', `'mod1' ... `'mod5'. `'meta' and `'mod1' are equivalent. `list' A list of symbols, indicating multiple modifiers. This function does not affect keybindings for other X clients, but does affect all Epoch screens. * Function: epoch::mod-to-shiftmask INDEX Input is an X modifier INDEX, output a shiftmask that can be passed to `epoch::rebind-key'. This function is OBSOLETE. * Function: epoch::query-tree &optional SCREEN-OR-XWIN Returns a list of the form `(root parent . children)' where all the elements are X resources. `root' is the X root window, `parent' is the X parent window of SCREEN-OR-XWIN (`nil' if SCREEN-OR-XWIN is the X root window), and `children' is a list of the X child windows of SCREEN-OR-XWIN. * Function: epoch::set-bell ARG If ARG is `nil', Epoch will use an audible bell. If non-`nil', then a visual bell will be used. * Variable: epoch::bell-volume Controls the X bell volume. If a number from -100 to 100, then the value is used as the bell volume, otherwise it is ignored and 50 is used. Note that on many systems, the hardware does not support different bell volumes, and so this may not be effective.  File: epoch, Node: Miscellaneous, Next: Index, Prev: X11 Primitives, Up: top Miscellaneous ************* Several unrelated features of Epoch are described here. * Menu: * Standard Extensions:: Standard Extensions * Epoch Version:: Epoch Version * Packages:: Packages * Mouse Dragging:: Mouse Dragging * Screen Naming:: Screen Naming * Autoraise:: Autoraise * Multiple Screen Updates:: Multiple Screen Updates * Display of Control Characters:: Display of Control Characters * Screen Pools:: Screen Pools * Saving Zones:: Saving Zones * Popup Menus:: Popup Menus * Colors:: Colors * Change Hooks:: Change Hooks * Icons:: Icons * dbx:: dbx  File: epoch, Node: Standard Extensions, Next: Epoch Version, Prev: Miscellaneous, Up: Miscellaneous Standard Extensions =================== Epoch contains some extensions to GNU Emacs that are not specifically related to the X Window System. * Function: symbol-buffer-value SYMBOL BUFFER Returns the value of SYMBOL in BUFFER, without the expense of using `set-buffer'. * Variable: epoch::function-key-mapping T If this variable is non-`nil', then functions keys will be mapped into an extended form starting with `ESC [', as is done in normal GNU Emacs. If this variable is set to `nil', then no mapping will be done, and the key will be ignored. Keys rebound (*Note Other X Stuff::, `epoch::rebind-key') to a non-empty string will not be affected by this value. If set to `t' then keys which have not been rebound will be mapped to various escape strings. * Function: equal OBJECT1 OBJECT2 This function returns `t' if OBJECT1 and OBJECT2 have equal components; `nil' otherwise. If OBJECT1 and OBJECT2 are both X Resources, *Note X Resources::, then `t' is returned if their xid's are equal, regardless of type.  File: epoch, Node: Epoch Version, Next: Packages, Prev: Standard Extensions, Up: Miscellaneous Epoch Version ============= * Variable: epoch::version This built-in variable will contain the version number of Epoch. Thus, `(boundp 'epoch::version)' will be `t' on Epoch and `nil' on any other version of GNU Emacs. You can use this to customize your Elisp code conditionally. The value of this variable will of the form "Epoch 4.1" and will indicate the current major and minor version of Epoch.  File: epoch, Node: Packages, Next: Mouse Dragging, Prev: Epoch Version, Up: Miscellaneous Packages ======== Epoch comes with several Elisp files that provide a set of standard functionality to the user. A majority of the standard files are loaded when Epoch is built. See `ymakefile' and `loadup.el' for which files are loaded. Any code which can not be executed except at runtime may be loaded from `.emacs', or run via a hook: * Variable: epoch-setup-hook NIL Functions to be executed at runtime, before `.emacs' is loaded and before `term-setup-hook' and `window-setup-hook' are run. The following files are included in this version of the Epoch distribution, in the `epoch-lisp' directory: `epoch.el' Installs standard keybindings, variables that you can set to change things, and so on. This file also defines the default event handler code. `epoch-util.el' Some utility functions used throughout Epoch lisp code. `mini-cl.el' Provides some Common Lisp primitives to Emacs Lisp. This is a subset of the Common Lisp package provided by `cl.el'. `wrapper.el' Every primitive function introduced into GNU Emacs to support Epoch is of the form `epoch::NAME'. For each function we provide a form without the leading `epoch::'. These are the forms you should use; this way, you can add additional functionality to the primitives very easily. For example, the definition of `create-screen' determines what to take from the `epoch-mode-alist' before creating the screen with `epoch::x-create-screen'. `zone.el' Extensions to zone primitives; primitives for style manipulation. `event.el' Standard event-handling code. `mouse.el' Mouse event handling for epoch. (*Note Mouse Dragging::.) `motion.el' Handles mouse motion events. Provides dragging and pasting operations. (*Note Mouse Dragging::) `message.el' Provides a client message handler. Provides a handler for the `WM_DELETE_WINDOW' client message from the window manager. `property.el' Provides the basic property handlers. `selection.el' Provides support code for selections. `button.el' Provides wrappers for zone functions to maintain compatibility with older Elisp packages. `convert-buttons.el' Provides a function to convert old Elisp code using buttons to use zones instead. Additional Epoch Elisp code can be found in the file `contrib-4.0.tar.Z' at the standard Epoch FTP site (*Note Getting Epoch::). This code has been verified to be minimally compatible with Epoch versions 4.0 and later, but is not considered to be part of the standard distribution. Also see the Epoch FAQ file (`etc/EPOCH-FAQ' in the Epoch distribution) for additional information on Epoch Elisp code.  File: epoch, Node: Mouse Dragging, Next: Screen Naming, Prev: Packages, Up: Miscellaneous Mouse Dragging -------------- We have implemented drag, scrolling drag, and cut and paste with the mouse. The files `mouse.el' and `motion.el' contain the Elisp code that provides this functionality. The functionality provided by the mouse buttons is shown in following table. Button Action left-down Clear drag region, set point. shift left-down Display line number and buffer name at mouse pointer. left-down and drag Drag out a region. Highlight (buffer-local), place in PRIMARY selection and kill-ring. Set point and mark around highlighted region. middle-down Paste at the mouse location. (Use `yank' to paste at the current point.) right-down Extend highlighted region from a left-down and drag. right-down and drag Extend highlighted region initially, then adjust by drag. "Scrolling Drag" means that when the mouse moves out of the window with a button down, the text in the window scrolls until the mouse button is released. The speed of the drag can be controlled by setting the following variables: * Variable: horizontal-drag-inc 5 The number of characters the buffer is scrolled horizontally in a single step. * Variable: vertical-drag-inc 2 The number of lines the buffer is scrolled vertically in a single step. The dragged region is global; you can have only one dragged region among all Epoch buffers. The dragged region will no longer be highlighted if some other X11 client asserts ownership of the `PRIMARY' selection. (This is the standard behavior for xterms, etc.) Because point and mark are set around drags, you can use a combination of mouse drag and Epoch keystrokes to do editing. NOTE: When cutting and pasting, Epoch will first request data from the selection indicated by `mouse::selection', and subsequently look to the X cutbuffer. This is to maintain compatibility with older xterm clients which do not support selections and/or do not use the standard selection for cutting and pasting. * Variable: mouse::selection-atom `(INTERN-ATOM "PRIMARY")' This variable indicates the name of the selection to use. This defaults to the atom `XA_PRIMARY', but may need to be set differently for xterms that don't use this selection. NOTE: Under some instances, clients use the `CLIPBOARD' (or other) selection. The following code may be executed to cut and paste with these clients: ;; Use CLIPBOARD selection (setq mouse::selection-atom (intern-atom "CLIPBOARD")) ;; Install handler for selection-clear on this selection (push-selection mouse::selection-atom 'mouse-clear)  File: epoch, Node: Screen Naming, Next: Autoraise, Prev: Mouse Dragging, Up: Miscellaneous Screen Naming ------------- * Variable: include-system-name Set the variable `include-system-name' to `t' if you would like screen names to include the name of the system they are running on; for example, the name of the screen with buffer `foo' selected on machine `bar' would appear `foo @ bar'.  File: epoch, Node: Autoraise, Next: Multiple Screen Updates, Prev: Screen Naming, Up: Miscellaneous Autoraise --------- * Variable: auto-raise-screen The variable `auto-raise-screen' is a flag to indicate which (if any) screens will be raised when a new edit screen is selected with `select-screen'. When set to `t', both the edit screen and minibuffer screen (if distinct) will be raised. If set to `'screen', only the edit screen will be raised; if set to `'minibuf', only the minibuffer screen (if distinct) is raised. Finally, if set to `nil', no screens are raised.  File: epoch, Node: Multiple Screen Updates, Next: Display of Control Characters, Prev: Autoraise, Up: Miscellaneous Multiple Screen Updates ----------------------- The `epoch.el' file sets things up so all screens are updated automatically. You will have to change this if you would like a different convention. For example, you could use the `epoch-mode-alist' to set things up so that only screens created for buffers with mode `shell-mode' would be updated. *Note Screen Updating:: for more information.  File: epoch, Node: Display of Control Characters, Next: Screen Pools, Prev: Multiple Screen Updates, Up: Miscellaneous Display of Control Characters ----------------------------- Epoch 4.0 includes the well-known patches to support full 8-bit character sets (e.g., ISO Latin-1). Epoch 4.1 supports additional 8-bit capabilities. * Variable: ctl-arrow This buffer-local variable will display control characters with uparrow if set to `t', as backslash and octal digits if set to `nil', and as regular characters if set to any other values. This behavior may be selected for all buffers by using this code: (setq-default ctl-arrow 'foo)  File: epoch, Node: Screen Pools, Next: Saving Zones, Prev: Display of Control Characters, Up: Miscellaneous Screen Pools ============ The package in `scr-pool.el', which is not dumped or loaded by default, provides a set of functions for creating pools of screens. This is a set of screens of a fixed size that are used in a package. Screens pools are useful when a package wants to use multiple screens, but also wants a limit on the number of screens in use to prevent excessive clutter or resource consumption. * Menu: * Screen Pool Basics:: Basic Description of Screen Pools * Screen Pool Functions:: Functional Interface to Screen Pools  File: epoch, Node: Screen Pool Basics, Next: Screen Pool Functions, Prev: Screen Pools, Up: Screen Pools Screen Pool Basics ------------------ A screen pool consists of SIZE The maximum number of screens allowed in the pool. When this number of screens are in the pool and another is requested, one of the screens already in the pool is recycled and returned instead of a new screen. CREATE-FUNCTION This is a function that is used to create a new screen when needed, either because there are less than SIZE screens in the pool, or because one of the screens in the pool is dead. This function is optional and if it's missing then `create-screen' is used. No arguments are passed to this function. CLEANUP-FUNCTION This function is called on a screen just before it is recycled, with the screen as its single argument. If missing, no function is called. This is useful, for example, when buffers displayed in a screen should be killed when the screen is recycled. The screen pool attempts to keep track of the least recently used screen and will recycle that screen first. A screen is marked as used whenever it is returned as a requested screen. In addition, there are functions to explicitly mark screens as either most or least recently used. These function should not be called on screens not in the pool, since this will cause the screen to be added to the pool.  File: epoch, Node: Screen Pool Functions, Prev: Screen Pool Basics, Up: Screen Pools Screen Pool Functions --------------------- These are the functions provided by the Screen Pool package. * Function: pool:create SIZE &optional CREATE-FUNCTION CLEANUP-FUNCTION Creates and returns a screen pool with no screens in it. * Function: pool:delete POOL Deletes all the screens in the POOL using `delete-screen'. The cleanup-function, if any, is called on each screen first. * Function: pool:get-screen POOL Returns a screen from the POOL. If there are fewer screens than the maximum size, a new screen is created, otherwise an existing screen is recycled. If a screen is recycled, the cleanup-function (if any) is called on the screen. * Function: pool:get-screen-with-buffer POOL BUFFER Similar to `pool:get-screen', except that if one of the screens in the pool is already displaying BUFFER, it is returned instead of creating a new screen or recycling another screen, and the cleanup-function is not called. * Function: pool:get-shrink-wrapped-screen POOL BUFFER LIMITS Similar to `pool:get-screen'. If BUFFER is displayed on any screen in the POOL, then that screen is used, otherwise a screen selected as in `pool:get-screen' is used. This screen is selected, all but one window is deleted, and that window is set to display BUFFER. The screen is then shrunk to fit the buffer, in height and width, up to LIMITS. LIMITS should be a list of 4 numbers, of the form `(min-width, max-width, min-height, max-height)'. * Function: pool:mark-screen POOL SCREEN Mark SCREEN as being the most recently used SCREEN in the POOL. This means it will be the last to be recycled. * Function: pool:unmark-screen POOL SCREEN Mark SCREEN as being the least recently used SCREEN in the POOL. This means it will be the first screen to be recycled.  File: epoch, Node: Saving Zones, Next: Popup Menus, Prev: Screen Pools, Up: Miscellaneous Saving Zones ============ The package in `save-zones.el', which is not dumped or loaded by default, provides the basis for saving a buffer's zone information when it is saved for restoration later. Zone information is stored at the end of the buffer, commented out appropriately according to the buffer's mode. The information is interpreted and deleted when the buffer is loaded, and is recreated and inserted when the file is stored. The following zone information is archived: * zone start * zone end * zone data * zone style tag (or `nil') When recreating zones for a buffer, the style tag information is used to determine the appropriate style to assign to the zone. If the style tag is non-`nil', then the value of FIND-STYLE-HOOK is called with the style tag as an argument. It is expected that this function will return either a style object, or `nil'. The code provides one possible scheme for using style tags, in which the tag is assumed to be an Elisp symbol whose value is the appropriate style. The hook can be made buffer local if necessary. Any zones with their TRANSIENT field set to `t' will be ignored. * Variable: find-style-hook NIL The function called to find a style corresponding to a STYLE-TAG.  File: epoch, Node: Popup Menus, Next: Colors, Prev: Saving Zones, Up: Miscellaneous Menus ===== The package in `contrib/wm-menu' `menu.el', which is not dumped or loaded by default, provides the basis for doing popup menus between Epoch and GWM 1.6. A second file, `emenu.el', gives an example of using the menu package to implement a menu for various options which call Elisp functions, and binds this menu to an event in the mouse map (`control-right-up'). Menu lists passed to this function should be of the following form: ("menu title" option 1 option 2 ... option N ) Each `option' should be a list `(return-symbol "option name")', and in the case of submenu options, should contain a menu list structure of the same format corresponding to that submenu. * Function: menu::popup MENU This function will produce a popup menu containing options described in the MENU list. It will then wait until the user has selected an option and then return the `return-symbol' defined in the menu list.  File: epoch, Node: Colors, Next: Change Hooks, Prev: Popup Menus, Up: Miscellaneous Colors ====== Colors can be specified as either a string, which is used for lookup in the X color database, or a vector with three components, the red, green, and blue components. Vector values are such that `65535' `(==2^16-1)' is the maximum for the display device, and 0 is off. Epoch stores colors as X Resources of type X-Cardinal *Note X Resources::. * Function: epoch::number-of-colors Returns the number of color cells on the display. This function is used to distinguish between monochrome and color systems. A result of `2' indicates monochrome; a larger number indicates a grey-scale or color display. * Function: epoch::get-color NAME Given a color name, this function converts the name into an X-Cardinal Resource (a pixel value).  File: epoch, Node: Change Hooks, Next: Icons, Prev: Colors, Up: Miscellaneous Change Hooks ============ Two variables were added to Epoch that hold functions to call before and after, respectively, each change is made to a buffer. These variables are not buffer-local, so if you wish to have your change function called only for specific buffers, first make the variables buffer-local, then assign the name of the function to be called. These variables are only defined if you compile Epoch with `DEFINE_CHANGE_FUNCTIONS' defined in the `config.h' file. * Variable: before-change-function Function to call before each text change. Two arguments are passed to the function: the position of the change and the position of end of the region deleted. If the two positions are equal, then the change is an insertion. While executing the `before-change-function', changes to any buffers do not cause calls to any `before-change-function', `after-change-function', or `after-movement-function'. * Variable: after-movement-function Function to call after cursor (point) movement which was not due to buffer changes. One argument is passed to the function: the previous value of point. * Variable: after-change-function Function to call after each text change. Three arguments are passed to the function: the position of the change, the position of the end of the inserted text, and the length of the deletion, or `0' if none. While executing the `after-change-function', changes to any buffers do not cause calls to any `before-change-function', `after-change-function', or `after-movement-function'. While executing the `after-movement-function', changes to any buffers will not cause calls to any `before-change-function', `after-change-function', or `after-movement-function'. (defun after-change (pos inspos dellen) "Called after each change" (condition-case err (progn (cond ((= dellen 0) (message "insertion: (%s %s)" pos inspos)) ((= dellen (- inspos pos)) (message "replacement: (%s %s)" pos inspos)) ((= pos inspos) (message "deletion: %s of length %s" pos dellen)) (t (message "other change at %s: ins %s, del %s" pos inspos dellen)) ) ) (error (setq after-change-function nil) (message "*Change error: %s" (prin1-to-string err))) ) ) ;; first evaluate the above function ;; then eval the next two lines to activate the function (make-local-variable 'after-change-function) (setq after-change-function 'after-change)  File: epoch, Node: Icons, Next: dbx, Prev: Change Hooks, Up: Miscellaneous Icons ===== You can set the names of icons for screens (accessible through the property `WM_ICON_NAME' using the global `.Xdefaults', the screen property list, or the function `epoch::icon-name'.) NOTE: Behavior when iconifying screens is largely dependent on the window manager. This dependence includes the window manager's treatment of window groups (in which the minibuffer screen is group leader of all Epoch screens), as well as whether to respect hints for icon name, placement, icon-pixmap, etc. * Function: epoch::icon-name &optional VALUE SCREEN If VALUE is `nil', return current icon name. Otherwise set icon name to value. If SCREEN is `nil', use current screen. * Function: epoch::icon-pixmap PIXMAP-NAME &optional SCREEN Sets SCREEN to use PIXMAP-NAME as a bitmap image when screen is iconified. PIXMAP-NAME may be a string (absolute path to a bitmap file), or an X Resource of type Bitmap.  File: epoch, Node: dbx, Prev: Icons, Up: Miscellaneous dbx === * Function: dbx Calls a C function named DEBUG which does nothing. This serves as an entry into a debugger if a breakpoint was set upon entry to this function.