Miscellaneous
*************

Several unrelated features of Epoch are described here.

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 (see 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, see X Resources, then t is returned if their xid's are equal, regardless of type.

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.

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. (see Mouse Dragging.)

motion.el
     Handles mouse motion events.  Provides dragging and pasting operations. (see 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 (see 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.

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)

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.

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.

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.  See Screen Updating for more information.

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)

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.

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.

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.

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.

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.

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 see 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).

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)

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.

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.