Epoch 4.1

Introduction

Epoch is a modified version of GNU Emacs with several major enhancements:

Some minor enhancements include various bug fixes and improved option handling.

As much compatability as possible with previous versions of GNU Emacs has been maintained. Existing Elisp code should run under Epoch, although it will not automatically use the new features of Epoch, and the behavior may not be as expected when running with proportional fonts. Almost all the X Window System support code in GNU Emacs was removed because of incompatibilities. Almost all features except the X menu code were reproduced; we believe that the window manager should provide menus (See section Menus).

Epoch requires the X Window System to function. Support for editing on non-graphic terminals is provided but is equivalent to running an ASCII version of GNU Emacs with no Epoch functionality. The mode of operation is determined as with GNU Emacs: if the "-nw" command-line flag is specified or if the environment variable $DISPLAY is unset, then Epoch will run in ASCII mode; otherwise it will run under X with full functionality provided. Note: Please refer to the file `INSTALL' to ensure appropriate ASCII support.

Most of this manual is intended for the "Emacs guru" who wants to play with and extend Epoch's functionality. Information intended for "ordinary Emacs users" is found in See section General Information. There is now a list of frequently asked questions; refer to the file `etc/EPOCH-FAQ'.

Support and Mailing List

For sharing ideas about applications of Epoch, code, and bug reports, there is now a Usenet newsgroup: gnu.epoch.misc. Articles posted to this newsgroup are gatewayed to and from the Epoch mailing list for those without news access.

To post to the mailing list send mail to one of these addresses:

epoch@cs.uiuc.edu
uunet!uiucdcs!epoch
epoch%cs.uiuc.edu@uiucvmd.bitnet

For administrative messages (joining the mailing list, etc.), substitute `epoch' with `epoch-request' in the above addresses.

Getting Epoch

Epoch is available by anonymous ftp on cs.uiuc.edu. We are negotiating to have it available through other sites, and through uucp mail request. Send mail to epoch-request@cs.uiuc.edu to find out the current status with this if you do not have anonymous ftp.

Epoch is available on tape: The cost at the time of creating version 4.0 was $175.00 for cartridge tapes. We can currently make 1600 BPI reel tapes and cartridge tapes for SUN and HP 9000 series machines. The price covers the cost of purchasing, making and shipping the tapes. You should contact epoch-request@cs.uiuc.edu to confirm these rates. Payment should be by check, made payable to the University of Illinois, and sent to:

Epoch Distribution, attn: R. Canaday
Department of Computer Science
University of Illinois at Urbana-Champaign
1304 W. Springfield Avenue, Urbana
Illinois 61801, USA.

Announcements regarding official (i.e., supported) patches and subsequent releases will be made to gnu.epoch.misc; patches will be available via ftp and email upon request.

Acknowledgements

Simon would like to thank the Computer Science Department at the University of Illinois, AT&T and the National Science Foundation for their support of parts of this work, and also Philippa and Ronan for putting up with him.

Dan would like to thank Simon and Alan for their fine work, and Clare and Carey for putting him up.

Chris would like to thank Simon and Alan for valuable contributions to the design of Epoch 4.0, and members of the ConversationBuilder research group for serving as "pre-Alpha" guinea pigs.

Susan Hinrichs, Alan's lovely wife, provided emotional, intellectual, and code support.

We would all like to thank Richard Stallman and the Free Software Foundation for GNU Emacs, and Colas Nahaboo and Bull for the GWM window manager.

We would also like to thank all those who have provided invaluable advice, assistance, and contributions in getting Epoch to this stage of development through Alpha and Beta testing, including members of the epoch-design mailing list.

General Information

Getting Started

We assume you are reasonably familiar with GNU Emacs. You can essentially use Epoch just like GNU Emacs.

Epoch is started just like GNU Emacs: type epoch on the command line. Epoch opens its own X window(s), so it can be run as a background job.

Depending on its mode of operation, Epoch will create one or two windows by default. The first will contain the initial edit buffer; if created, the second will contain the minibuffer. More on this below (See section New Features).

If you wish to use Epoch without having to do any Elisp programming while still being able to specify window properties, the following sections are for you.

X Window Program Defaults

Epoch reads the default values associated with X Window System programs, or X defaults, set up by the user. The possible sources of these defaults are listed below in the order in which Epoch will discover them. These values are loaded into an internal database, called the global default-set, which is initially filled in with hard-wired defaults (which are listed below).

The resulting global default-set is stored, and remains constant for the rest of the program execution. It serves as a basis for all screen creation, in order to guarantee a value for every property. (The minibuffer has its own default-set, which is used once, to create the minibuffer screen.) See section Screen Properties for more background on how X defaults are used.

The X default specifications are determined in the following order, with later specifications superceding earlier values for the same options:

  1. Hard-wired X defaults (see below).

  2. <resource-name> or <class-name> in either $XAPPLRESDIR or the appropriate app-defaults directory.

  3. `$HOME/.Xdefaults' if the "-ud" command line flag is used.

  4. File named by the environment variable $XENVIRONMENT.

  5. If $XENVIRONMENT is not set, `$HOME/.Xdefaults-<hostname>'.

  6. Resources database (see `xrdb').

  7. Command line options.

The X default options recognized by Epoch are listed in the table below. The window resource name/class defaults are special; they default to the program resource name/class respectively (See section Command Line Options).

Furthermore, the program resource name/class command line options are special. They are not put into the internal database - they affect how the database is queried for X default values. When searching for names and classes, the leftmost qualifier is the resource name/class name. The default for the name is the name of the program (normally "epoch") and the default for the class is "Emacs". If these are set by command line options, the new values become the X defaults.

Epoch also accepts class defaults (as distinct from resource defaults), which are exactly as below except that the first letter of each field is capitalized.

Option
Default Value, Effect

.screen.background
White, Edit screen background color

.minibuf.background
White, Minibuffer screen background color

.screen.border.color
Black, Edit screen border color

.minibuf.border.color
Black, Minibuffer screen border color

.screen.border.width
2, Edit screen border width

.minibuf.border.width
2, Minibuffer screen border width

.screen.cursor.background
White, Edit screen X cursor background color

.minibuf.cursor.background
White, Minibuffer screen X cursor background color

.screen.cursor.color
Black, Edit screen text cursor color

.minibuf.cursor.color
Black, Minibuffer screen text cursor color

.screen.cursor.foreground
Black, Edit screen X cursor foreground color

.minibuf.cursor.foreground
Black, Minibuffer screen X cursor foreground color

.screen.cursor.glyph
86, Edit screen X cursor glyph

.minibuf.cursor.glyph
86, Minibuffer screen X cursor glyph

.screen.internal.border.width
2, Edit screen internal border width

.minibuf.internal.border.width
2, Minibuffer screen internal border width

.screen.class
<special>, Resource class of the edit screen

.minibuf.class
<special>, Resource class of the minibuffer screen

.nonlocal.minibuf
false, Minibuffer location (local or non-local)

.display
"", X Window display

.motion
Off, Whether motion-hints should come through to Elisp

.screen.font
"fixed", Edit screen font

.minibuf.font
"fixed", Minibuffer screen font

.screen.foreground
Black, Edit screen foreground color

.minibuf.foreground
Black, Minibuffer screen foreground color

.screen.geometry
"80x24", Geometry of the initial edit screen

.minibuf.geometry
"80x1", Geometry of the minibuffer screen

.screen.name
"Edit", Name of the edit screen

.minibuf.name
"Minibuffer", Name of the minibuffer screen

.screen.resource
<special>, Resource name of the edit screen

.minibuf.resource
<special>, Resource name of the minibuffer screen

.screen.reverse
False, Reverse colors for edit screen

.minibuf.reverse
False, Reverse colors for minibuffer screen

.screen.icon.name
"", Icon Name

Command Line Options

Epoch also accepts command line options. These options override values in the X defaults. A complete list is in the table below. Note that the program resource name/class can be overridden by specifying different values on the command line (See section X Window Program Defaults for how the name and class are used).

Option
Resource, Effect

-bg
*background, Sets background colors.

-background
*background, Sets background colors.

-fg
*foreground, Sets foreground color.

-foreground
*foreground, Sets foreground color.

-geometry
*screen.geometry, Sets X window geometry.

-fn
*font, Sets the font.

-font
*font, Sets the font.

-nm
*nonlocal.minibuf, Selects local minibuffer to each edit screen.

-wn
*name, Sets the X window title.

-window
*name, Sets the X window title.

-d
*display, Sets the display to use.

-display
*display, Sets the display to use.

-r
*reverse, Reverses foreground/background colors (no argument).

-rn
NA, Sets the resource name.

-resource
NA, Sets the resource name.

-name
NA, Sets the resource name.

-cn
NA, Sets the resource class.

-class
NA, Sets the resource class.

-ud
NA, Looks at `$HOME/.Xdefaults' for program defaults.

-motion
*motion, Turns on passing of motion events to Elisp for all screens.

-xrm
NA, Overrides a resource manager value.

New Features

This section provides a brief overview of the new features in Epoch. More detail is provided in subsequent chapters.

In this document, the term screen will mean an X window created and managed by Epoch, and window will refer to an Emacs editor window. In most cases, working within a screen is the same as working within a GNU Emacs session.

At any time, there is a single selected screen; this is similar to having a selected window. The selected screen is also called the current screen. Standard window functions work, but only apply to the current screen; e.g., one-window-p returns non-nil if there is only one window on the current screen. Buffers are shared among all screens, so any buffer can be accessed in any window, and will show up in the buffer list. Killing a buffer removes it from all windows and all screens.

Epoch supports two different kinds of minibuffers. The default is a non-local minibuffer, which is displayed in its own distinct screen; this is what Epoch has traditionally done. The alternative is to have minibuffer windows local to each edit screen; this is similar to traditional GNU Emacs. In the case of non-local minibuffers, there will always be exactly one minibuffer screen, and one or more edit screens; a single edit screen and minibuffer screen together act similarly to normal GNU Emacs. For local minibuffers, the real minibuffer will be located at the bottom of the current edit screen.

Zones are regions of text in a buffer that can have data attached to them and be displayed in different styles (background/foreground color, stipple pattern, font, underlining) than surrounding text. Zones provide both the ability to do highlighting and to attach data to text regions that can be retrieved based on buffer location.

Epoch supports the use of either fixed-size or variable-sized (proportional) fonts for display. This includes support for mixtures of fonts (using zones) which feature potentially different attributes (default or quad width, ascent, descent, etc.).

Epoch supports event sending and receiving, including client messages and X Window properties, and asynchronous reception of client and property change events. This allows Epoch to communicate with other X clients and the window manager.

Key Bindings

Epoch provides a large range of useful functions to create, delete and change the attributes of screens (e.g., changing colors, sizes, etc). We provide a default set of key bindings for these functions, shown below.

The basic idea was to take the C-x binding for Emacs window and buffer operations, and provide analogs for screen operations using C-z as the prefix key. (We use C-z because a suspend operator is not all that useful in a multi-window environment, and in any case C-x C-z still provides the same effect as the standard.) We do not believe we have a full set of bindings yet, and we look forward to user contributions.

We supply a standard set of Elisp files (See section Packages). They provide a good introduction to using the primitive Epoch facilities described in this document. The file `epoch.el' installs the basic Epoch key bindings. See below for more information.

Key
Functionality

C-z 4 f
find-file-other-screen Finds a file in another screen. Prompts for a filename. If it is already in a window on a screen, warps the cursor there, otherwise creates a new screen and edits the file in it.

C-z 4 b
find-buffer-other-screen Selects a buffer in another screen. Prompts for a buffer name. If it is already in a window on a screen, warps the cursor there, otherwise creates a new screen with one window for the buffer.

C-z 0
remove-screen Deletes the current screen.

C-z o
switch-screen Circulates through mapped screens in forward direction.

C-z p
prev-switch-screen Circulates through mapped screens in reverse direction.

C-z 2
duplicate-screen Duplicates current screen.

C-z r
raise-current-screen Raises current screen.

C-z l
lower-current-screen Lowers current screen.

C-z m
raise-minibuf Raises minibuffer screen.

C-z i
iconify-screen Iconifies current screen.

C-z e
display-event-status Displays event handler status.

Conventions

Several conventions are used in the following chapters.

Each Epoch primitive has a leading `epoch::' in a fashion reminiscent of Common Lisp packages; e.g., epoch::create-screen. The reason is that we want to build around these functions at the Elisp level, so we deliberately make the primitives uncomfortable to use. The files `wrapper.el' and `epoch.el' provide a full set of wrappers that remove the `epoch::' leading characters and add additional functionality (e.g., there is a function create-screen that provides a higher-level interface to epoch::create-screen). If you are going to write your own Elisp code, you should probably use these wrapper functions, not the raw primitives.

Menus

Unlike GNU Emacs and some other X applications, Epoch provides no internal support for pop-up menus or menu bar facilities. We feel that it is more appropriate for X11 clients to depend on the window manager (or some sort of widget server) for menu support.

Two primary options exist for creating pop-up menus under Epoch: requesting the window manager (e.g., GWM) to supply them, or using an external X client (e.g., XMENU) to provide them. Examples of each method are available in contributed Elisp code (See section Packages).

GWM

GWM (Generic Window Manager) is an Emacs-like window manager in that it provides a basic kernel of window-managing facilities written in C and a Lisp level for extensive user customization. GWM is part of the X11 release (the most recent version is always available via anonymous ftp from export.lcs.mit.edu).

In GWM, one can attach state machines to objects (such as X windows) in GWM, and these can then receive and handle events. GWM can receive and initiate property change events, as can Epoch, so this provides the basis for communication between the two.

GWM also provides the ability to decorate windows with up to four bars (one on each side, top and bottom). Each bar can have "plugs" (icons) which can have specialized state machines attached. This allows one to have title bars, bars with pulldown menus, etc., all maintained by GWM, but with communication to Epoch allowing selections to be communicated.

GWM is easily tailored to emulate other window managers and comes with reasonable emulations of MWM and TWM as well as a "home-grown" look-and-feel, so most users can use it as a replacement for previous managers quite easily.

The interested reader should see the GWM documentation for more details.

XMENU

XMENU is a toolkit program which produces a popup menu taking command-line arguments as menu entries. It is possible to execute XMENU as a process from Epoch (or GNU Emacs) and wait for the process output.

Screens

This chapter describes screen features supported by Epoch, except for the Elisp extensions described in section Miscellaneous.

Screen Basics

In this document, the term screen will mean an X window, and window will refer to an editor window to avoid confusion. In most cases working within a screen will be the same as working in a GNU Emacs session.

Each screen contains its own Emacs window hierarchy. (This terminology is a little confusing: when GNU Emacs uses the term window this refers to the logical structure in which a buffer is displayed. The name "window" was already appropriated, so we had to call our "X windows" something different; they are therefore called screens.) When a screen is first created, it contains a single window with its mode line covering the entire screen. The buffer for this window is set to *scratch* unless a different buffer is specified.

Epoch supports two types of screens: edit screens and minibuffer screens. There will always be at least one edit screen. If Epoch is operating with non-local minibuffers, then there will always be exactly one minibuffer screen; otherwise, a local minibuffer window will appear at the bottom of each edit screen. Epoch assumes there is at least one edit window at all times. A single edit screen and the minibuffer window together act much like normal GNU Emacs.

Variable: epoch::nonlocal-minibuffer

This variable is set to t if there is a distinct minibuffer screen, nil otherwise.

Variable: epoch::synchronize-minibuffers

If Epoch is operating with local minibuffers, and this variable is set to t, then the contents of all local minibuffer windows will be synchronized with the contents of the real minibuffer window. This variable defaults to nil.

At any time there is a single selected screen, analogous to the selected window; this is also called the current screen. Standard window functions work, but they only apply to the current screen; e.g., one-window-p returns non-nil if there is only one window on the current screen. Buffers are shared among all screens, so any buffer can be accessed in any window, and will show up in the buffer list. Killing buffers removes them from all windows. The value of epoch::global-update determines whether Epoch updates non-current screens or not (see See section Screen Updating).

Epoch adds screens as a new Emacs Lisp primitive type. Screens are printed as #<screen n>, where n is the screen ID. This ID is a sequence number attached to a screen when it is created. It serves primarily as a human convenience. Any argument to a primitive listed as screen can be either a screen object or a screen ID. However, when the result of a function is a screen, this means a screen object is returned unless specifically mentioned to do otherwise. Optional screen arguments default to the current screen unless otherwise specified.

A screen that is displayed is said to be mapped; if it is only displayed as an icon, it is said to be unmapped. By X Window System conventions, a screen is mapped if and only if its X window is mapped.

Variable: inhibit-initial-screen-mapping

This variable, when bound and set to t, will inhibit the mapping of the first edit screen when Epoch is starting up. In this case, the only screen which will be mapped initially will be the minibuffer screen. If Epoch is run with local minibuffers, then the first edit screen will be mapped regardless. This variable is not bound by default, but can be set in the user's `.emacs' file.

There is one significant difference between screens and windows: screens are known to external programs (e.g., the X server). This means that the GNU Emacs scheme for window activities is not sufficient for screen activities. In particular, the creation of screens is much more complex than window creation.

Function: epoch::create-screen &optional buffer alist

Creates a new screen (unmapped), and returns it. If the buffer argument is present, that buffer is attached to the single window originally present in the screen, otherwise the *scratch* buffer is used. The alist argument is used to override screen creation defaults. See *create-screen-alist-hook* below.

Function: create-screen &optional buffer alist

Calls epoch::create-screen but does some additional things. The alist passed to epoch::create-screen is a copy of alist appended with a copy of epoch-mode-alist and two additional properties. These additional properties are icon-name and title (which here default to buffer name@system name). Also see *create-screen-alist-hook below.

Variable: *create-screen-alist-hook*

This is a hook variable used by create-screen. Just before the call to epoch::create-screen, each function in the hook is called with the screen property alist create-screen has generated. Each function should return a new version of the alist to be used instead. Normally, the hook function will add or modify some of the entries in the alist. See the code in See section Screen Pools for an example.

Screen Properties

Screens have a large number of properties (or attributes) that can differ between screens, and are externally visible (e.g., colors, cursor shape and color, font, size, title, class). Most of the complexity of screen creation is involved in dealing with these properties. Epoch deals with default-sets which are collections of X window property types and values. When a screen is created, a default-set is used to set the various properties of the screen. For information on default sets See section X Window Program Defaults.

In order to allow more variety in screens, Epoch provides more ways of overriding the global X default set. A global variable epoch::screen-properties contains an alist of screen properties. At screen creation time, a copy of the global default-set is made, and entries are overwritten with values from epoch::screen-properties. After that, the alist given as an argument to create-screen (if any) is used to override any previous values.

The order of determination of the default set for each screen is as follows (in increasing order of precedence):

  1. X program defaults (See section X Window Program Defaults).

  2. Values in epoch::screen-properties.

  3. Alist argument to epoch::create-screen.

  4. Mode-specific values using epoch-mode-alist, if create-screen is used for creation.

  5. Alist argument to create-screen.

Variable: epoch::screen-properties

This variable should contain an alist, the key values being screen property keys. The primitive attempts to bypass bad entries, but if the alist is improperly formed, Epoch may experience bizarre failures.

Variable: epoch-mode-alist

This variable allows you to associate a set of X defaults with an emacs mode. The form is a list, each element of which is a form (mode-name . alist-of-defaults). Whenever create-screen is called, the mode of the buffer argument (or the scratch buffer's mode if buffer is nil) is used to look in the alist.

This feature allows you to set geometry, colors, font, etc by mode. It's useful to allow (for example) 80x60 windows for `.c' and `.h' files, but a regular size window for other file types. See the definition of `epoch-mode-alist' in `epoch.el' for some examples.

Thus you can set up a default mode to epoch upon entry and then override portions of it at the time you call create-screen.

The table below is a list of all screen property keys recognized by the screen creation routines. The defaults listed are the hard-wired defaults, but they may be superceded as described in section X Window Program Defaults. Values listed as flag are false if the value is nil, true for any other value.

As an example, to set screens to have the font `9x15' and the `Gumby' cursor, the following Elisp code would be used:

(setq epoch::screen-properties
  (cons '(font . "9x15") 
         (cons '(cursor-glyph . 56) epoch::screen-properties)))

Name
Type, Default, Description

foreground
String, Black, Screen foreground

background
String, White, Screen background

cursor-color
String, Black, Text cursor color

cursor-foreground
String, White, cursor foreground color

cursor-background
String, Black, cursor background color

border-color
String, White, X border color

in-border-width
Number, 2, Internal border width

ex-border-width
Number, 1, External border width

title
String, "Edit", Screen title

name
String, "epoch", Screen resource name

class
String, "Emacs", Screen class name

update
String, false, Flag to indicate non-local screen updating

geometry
String, 80x24, Geometry specifier. Size units are characters. Screen must be at least 2 lines high.

cursor-glyph
Number, 86, X cursor glyph. Index into the cursor font.

reverse
Flag, False, Reverse foreground / background

font
String, "fixed", Font name

icon-name
String, "", Name of Icon for Screen

motion
Flag, nil, t will cause motion-events to be sent to screen, nil will inhibit this.

parent
X resource, nil; if non-nil, must be an X "resource id". The new screen is created as a child of this resource. Useful to provide clipping-parents, for example when trying to put screen in a form of some kind. This option is extremely dangerous and you should not use it if you don't know what you are doing.

initial-state
Flag, True, Starting state of screen. True means NormalState, false is IconicState.

Controlling Screens

The primitives in this section concern internal manipulations of screens.

Function: epoch::get-screen &optional screen

Coerces a screen or screen ID argument to the corresponding screen object.

Function: epoch::get-screen-id &optional screen

Coerces a screen or screen ID to the corresponding screen ID. Returns nil if the screen is deleted.

Function: epoch::screen-p screen

Returns t if the argument is of type screen, nil otherwise.

Function: epoch::screen-list &optional unmapped

Returns a list of all mapped screens, except the minibuffer which is never in the list. If the argument unmapped is non-nil then unmapped screens are also included.

Function: epoch::next-screen &optional screen unmapped

Returns the next screen in the internal ordering. With no arguments, it is the next screen after the current screen. A screen argument returns the next screen past the argument. Unmapped screens are not returned, unless the second argument unmapped is non-nil. The minibuffer screen is never returned.

Function: epoch::prev-screen &optional screen unmapped

Same as epoch::next-screen except the internal screen list is traversed in the opposite order.

Function: epoch::select-screen &optional screen

Makes the argument screen the current edit screen. The default is the next screen, as defined by epoch::next-screen. The minibuffer screen cannot be selected. Unmapped screens may be selected, but only explicitly or if only unmapped screens are left. Epoch attempts to remember what window was last selected in each screen, and selects that one. The hook *select-screen-hook* is run at this time.

Returns the selected screen, or nil if given a bad argument or if screen has been deleted.

Note: If a window is selected by select-window, an implicit epoch::select-screen is done to select the screen the window is on. This insures that the current window is on the current screen whether epoch::select-screen or select-window was used. In fact, this primitive actually works by selecting a window in the new screen.

Variable: *select-screen-hook*

This hook is run by epoch::select-screen.

Function: epoch::current-screen

Returns the current edit screen. The minibuffer screen is never returned.

Function: epoch::minibuf-screen

Returns the minibuffer screen. If no distinct minibuffer screen exists, then nil is returned.

Function: epoch::delete-screen &optional screen

Deletes a screen. Returns t if successful, nil otherwise. It is an error to delete the sole remaining screen, and Epoch will not allow this.

If you delete a screen and it is the current screen, it first uses epoch::select-screen to select a new screen.

BUG: Window managers can delete the last edit screen. If this happens, Epoch will crash and burn in short order. Window managers should obey the ICCCM standard and send a delete signal to the client; then Epoch can grab this and terminate gracefully.

Screens and Windows

Epoch supports all of the windowing ability of GNU Emacs on each screen. Every window is on a screen, and can never be moved from that screen. Epoch provides some primitives to help in the interaction between screens and windows.

NOTE: The concept of selected-window under Epoch changes slightly from that of GNU Emacs in that asynchronous events (i.e. Focus events) may cause the selected window to change without any user-originated command to do so. This will cause problems for Elisp packages which make the assumption that the selected window cannot change in the midst of their processing.

Function: epoch::get-buffer-window buffer

Searchs for a window displaying buffer on all screens. Returns such a window if successful, nil otherwise. This is effectively an updated version of the normal primitive get-buffer-window, which searches only the current screen and minibuffer.

Note: selecting a window also selects the screen it is on. Remember that the window may be on an unmapped screen. This function has no wrapper since that would collide with the standard function get-buffer-window.

Function: epoch::screens-of-buffer buffer

Returns a list of all screens on which buffer is displayed in a window.

Function: epoch::screen-of-window &optional window

Returns the screen that window is on. Returns the current screen if window is nil.

Function: epoch::first-window &optional screen

Returns the first window in canonical order for screen. Use next-window to find the other windows in the screen.

Function: epoch::selected-window &optional screen

Returns the selected window for screen. This is the window that would be selected if the screen it is on were selected, or equivalently the selected window the last time screen was the current screen.

Note: There is no wrapper for this function, since that would collide with the standard function selected-window.

Variable sized Fonts

Epoch now specifies the dimensions of Emacs windows in pixels. The primitives window-height and window-width now calculate character dimensions based on pixel dimensions and the base font for that window. It is important to realize that only the pixel values are "constant"; character/line values will change based on the presence of any proportional fonts or variable-height lines.

NOTE: The behavior of Epoch with standard GNU Emacs Elisp packages should be as expected if fixed fonts are being used; different behavior may be seen with proportional fonts.

Function: window-pixheight &optional window

Returns the height of window in pixels. Defaults to selected window.

Function: window-pixwidth &optional window

Returns the width of window in pixels. Defaults to selected window.

Function: window-pixedges &optional window

Returns a list of edge coordinates of window in pixels. Defaults to selected window.

Function: window-height &optional window

Returns the height of window in characters. Defaults to selected window.

Function: window-width &optional window

Returns the width of window in characters. Defaults to selected window.

Function: window-edges &optional window

Returns a list of the edge coordinates of the window in characters. (LEFT TOP RIGHT BOTTOM). NOTE: LEFT and TOP will be approximate, according to the base font for the screen; RIGHT will be one more than the rightmost column in the window; and BOTTOM is one more than the bottommost row used by the window and its mode-line.

Epoch now provides pixel-based functions and variables analogous to several character-based functions:

Function: current-pixel

Returns a pixel position corresponding to current location of point. Does not take window dimensions into consideration; may return pixel values past the right edge of the window.

Function: move-to-pixel pixel

Moves point to the character position corresponding to pixel position pixel. Ignores values of pixel which are past the edge of the window.

Variable: fill-pixel

Pixel column beyond which automatic line-wrapping should happen. Automatically becomes local when set in any fashion. If fill-column is set to nil, the value of auto-fill-hook is called if the current pixel position is past this value. The value of line-fill-hook is called if text insertion will cause the current line to extend past fill-pixel.

Function: text-width string &optional font

Return the length of text in string as displayed using font, or the base font of the current screen and window.

Manipulating Screens

These primitives allow control of the windowing system aspects of screens. Most of them correspond directly to X Window System calls.

Each of these functions return the screen, if successful, or nil otherwise.

The screen-or-xwin arguments may be screen objects or X resource object with type window (See section X Resources).

Function: epoch::raise-screen &optional screen-or-xwin

Raises the screen-or-xwin to the top of the display. This is called by epoch::select-screen.

Function: epoch::lower-screen &optional screen-or-xwin

Lowers the screen-or-xwin to the bottom of the display.

Function: epoch::map-screen &optional screen-or-xwin

Maps the screen-or-xwin onto the display. No effect if the screen is already mapped.

Function: epoch::unmap-screen &optional screen-or-xwin

Unmaps the screen-or-xwin. This is for sophisticated users only, as it does not check to see if the screen is the edit screen or the minibuffer. If the unmapped screen is the edit screen, it remains so; you just won't be able to see it.

Function: epoch::mapraised-screen &optional screen-or-xwin

This does a MapRaised call on the screen-or-xwin. This is equivalent to doing a map followed atomically by a raise. If no argument is present, it uses the current screen.

Function: epoch::iconify-screen &optional screen

Sends ICCCM client message requesting iconification of screen (or current screen if no argument is present).

Note:

Function: epoch::screen-mapped-p &optional screen

Returns t if the screen exists and is mapped, nil otherwise.

Function: epoch::screen-height &optional screen

Returns the height (in characters) of the screen. NOTE: there is no Epoch wrapper function for this primitive, as it would conflict with the existing GNU Emacs screen-height primitive. The height returned is calculated according to the base font for that screen.

Function: epoch::screen-width &optional screen

Returns the width (in characters) of the screen. NOTE: there is no Epoch wrapper function for this primitive, as it would conflict with the existing GNU Emacs screen-width primitive. The width returned is calculated according to the base font for that screen.

Function: epoch::change-screen-size &optional width height screen

Attempts to resize the screen, leaving the upper left corner fixed. The width and height are in characters, and default to the current width and height. This uses the XResizeWindow() call, which may be intercepted by the window manager. The width and height values are adjusted be be not more than 150. The height is adjusted to at least 1 for the minibuffer and 2 for edit screens.

Function: epoch::font &optional font screen

If called with nil font argument, this function returns the current font. If called with font argument, it changes screen's font to be that font. It will resize the screen so that it still has the same character geometry. It operates on the current screen if screen is nil. The result is a list of three elements: Font name, character-width, character-height in pixels.

Function: epoch::title &optional name screen

If called with nil name argument, this function returns the X screen name for screen or the current screen. If name is a string, screen's title is changed accordingly.

Function: epoch::icon-name &optional name screen

If called with nil name argument, this function returns the X screen icon name for screen or the current screen. If name is a string, screen's icon name is changed accordingly.

Function: epoch::plane-size

Returns a cons pair. Car is plane width, cdr is plane height in pixels. (A plane is a "minor screen" on a display: on mono screens, there is just one plane, color screens sometimes have several).

Function: epoch::screen-information &optional screen-or-xwin

Returns information about screen-or-xwin, or the current screen if screen-or-xwin is nil. The information is a list with the following elements:

  1. X location of screen in pixels

  2. Y location of screen in pixels

  3. Width of screen in pixels

  4. Height of screen in pixels

  5. External Borderwidth in pixels

  6. Internal Borderwidth; for an xwin, this is always 0.

  7. Map state: t if normal, nil if iconic.

Function: epoch::move-screen x y &optional screen-or-xwin

Sends request to window manager to move upper-left corner of screen-or-xwin (or current screen if no third argument) to given (x,y) coordinates in pixels. Note that some window managers may choose to ignore this request.

Function: epoch::foreground &optional color screen

Set/get the foreground color of the screen. If color is nil then the function returns the current foreground color as an X Resource. Otherwise it attempts to set the foreground color, and returns t on success and nil otherwise.

Function: epoch::background &optional color screen

Set/get the background color of the screen. If color is nil then the function returns the current background color as an X Resource. Otherwise it attempts to set the background color, and returns t on success and nil otherwise.

Function: epoch::cursor-background &optional color screen

Set/get the text cursor background color of the screen. If color is nil then the function returns the current text cursor background color as an X Resource. Otherwise it attempts to set the text cursor background color, and returns t on success and nil otherwise.

Function: cursor-color &optional color screen

Same as epoch::cursor-background.

Function: epoch::cursor-foreground &optional color screen

Set/get the text cursor foreground color of the screen. If color is nil then the function returns the current text cursor foreground color as an X Resource. Otherwise, it attempts to set the text cursor foreground color, and returns t on success and t otherwise.

Function: epoch::cursor-glyph &optional glyph screen

Set/get the X cursor glyph. If glyph is nil, returns the current glyph number, otherwise attempts to set the glyph.

Function: epoch::flash-screen &optional screen-or-xwin

Flash the screen-or-xwin. If the argument is a screen object, the flashing is done by exchanging the foreground and background colors, pausing .25 seconds, and then exchanging them again. For an X resource (even if it is an Epoch screen), the flashing is done by inverting the pixels, pausing, and then inverting again. This is effective on a monochrome display, but is not as effective for color, depending on the foreground and background colors.

Screen Updating

Epoch allows you to control which screens are updated as their contents are changed. The default is to only update the current screen, which is maximally efficient. It is possible, however, to set things up so that all screens or only some subset of the screens are updated. This is useful if you are editing a buffer which is displayed on multiple screens, or if you have a shell or other process running in one buffer and you are working in another. Then you can set things up so that the screen with the shell continues to update as it runs, while you work in another screen. There are several ways to do this, all involving the value of the global variable epoch::global-update.

The functions and variables are:

Variable: epoch::global-update

There are three classes of values for this variable.

Function: epoch::set-update arg &optional screen

Sets update flag to arg for screen, or current screen if nil. arg must be t for update, nil for no update. Returns previous value of flag.

Function: epoch::update-p &optional screen

Returns t if screen's update flag is set, nil otherwise. Uses current screen if screen argument is not present. This function should be epoch::updatep.

In addition you can use the following primitives to help control when screens get updated:

Function: epoch::redisplay-screen &optional screen

Forces a non-premptive redraw of argument screen (current screen if nil).

Function: redraw-display

Clears current screen and redraws what should be there.

Function: recenter &optional line

Center point in window and redisplay screen. If line is non-nil, put point on that line. Operates on current window.

Function: epoch::set-screen-modified &optional screen

Mark the argument screen (current if nil) as modified for update next time Epoch gets around to an update.

Zones

Zone Basics

Epoch supports the notion of zones (a.k.a. buttons), which are regions that are displayed in different styles. Two new data types are used for this: zone and style.

zone
Each zone has the following characteristics:
start
The start of the zone. A marker.
end
The end of the zone. A marker. The zone covers all characters between start and end.
style
Style to be used for displaying the text of the zone.
read-only
If set to non-nil, the text of the zone cannot be directly edited. Attempts to insert or delete any character in the zone will generate an error. (See section Read-only Zones)
data
Not used internally. This field can be any Elisp object, and is provided for the programmer to use to attach data to a zone for later retrieval.
transient
Flag to indicate zone should be ignored by undo operations.
  • style A style is an object that describes how to display characters. It has the following fields:
    foreground
    The text foreground color.
    background
    The text background color.
    cursor-foreground
    The character foreground color when the text cursor is on the character.
    cursor-background
    The character background color when the text cursor is on the character.
    font
    The font to be used for displaying the text in this style.
    stipple
    The stipple pattern to use for the text.
    cursor-stipple
    The stipple to use when the cursor is on the text.
    background-stipple
    The stipple to use for the background. Bits that are set in the stipple are displayed in the screen background color. Cleared bits are displayed in the style background color.
    underline
    The color to use for underlining. If not set, no underlining is done.
    tag
    Not used internally. This can be any Elisp object.
  • Zones were intended as a way of providing "hotbutton" capabilities in hypertext-like applications using Epoch as a front-end. In these cases the data field will hold information for the hotbutton. Zones can also be used for many other applications, of course.

    Each zone is attached to a buffer. All buffer arguments in the Epoch primitives default to the current buffer. Arguments of type zone must be zone objects. A package has been written to store zone information with buffers when they are written to files and then restore zones when the buffer is visisted (See section Saving Zones).

    Note: To maintain compatibility with older Elisp packages, you may do a (require 'button) to get "button" wrapper functions for the zone primitives. Old Elisp code may be converted to require zones by using the file `convert-buttons.el'.

    Functions exist to access and change a zone's start and end positions or even the zone's buffer while maintaining the correct position in the zone list. Note: Elisp code that alters zones by changing the vectors directly will not work correctly.

    Zone Primitives

    Function: epoch::make-zone

    Used to create a new zone. Returns a zone pointing nowhere, in no buffer.

    Function: epoch::zonep object

    Returns t if object is a zone, otherwise nil

    Function: epoch::zone-buffer zone

    Returns the buffer a zone is currently in, or nil.

    Function: epoch::zone-start zone

    Returns the zone's starting position as an integer.

    Function: epoch::zone-end zone

    Returns the zone's end position as an integer.

    Function: epoch::move-zone zone &optional start end buffer

    Moves the specified zone to a new position indicated by start and end in buffer. If either start or end is nil, it will remain unchanged. The zone start and end will be swapped, if necessary, so that the start comes before the end. Moving zones will cause the respective buffer(s) to redisplay, but will not mark the buffer as modified unless epoch::zones-modify-buffer is t. Returns the updated zone.

    start and end may be markers, but only the marker position is used.

    Function: epoch::add-zone start end attribute &optional data buffer

    Add a zone to buffer. start and end must be markers or integers. attribute is a number. data is programmer defined and is not used internally, so it can be anything. Returns the new zone, or nil on failure.

    Function: epoch::zone-at &optional position buffer

    Returns the zone in buffer that contains position, or nil. If position is nil, point is used.

    Function: epoch::zones-at &optional position buffer

    Returns a list of zones in buffer that contain position, or nil. If position is nil, point is used. The zones are ordered by starting position.

    Function: epoch::zones start end &optional partial transient buffer

    Returns a list of zones in buffer that are contained in the region defined by start and end. The optional parameter partial determines if partially-contained zones are included in the list; it defaults to nil. The optional parameter transient is set to t if zones with the transient field are included in the list; it defaults to nil|. The buffer may be specified, or the current buffer will be used.

    Function: epoch::zone-list &optional buffer

    Returns the list of zones for buffer. The list contains the actual zones, not copies. The zones are ordered by starting position.

    Function: epoch::zone-style zone

    Returns zone's current style value.

    Function: epoch::set-zone-style zone value

    Sets zone's style to value.

    Function: epoch::zone-data zone

    Returns zone's current data value.

    Function: epoch::set-zone-data zone value

    Sets zone's data to value.

    Function: epoch::zone-transient-p zone

    Returns t if zone has its transient flag set; else nil.

    Function: epoch::set-zone-transient zone flag

    Sets the zone's transient to flag. This is useful if the zone should be ignored by undo operations.

    Function: zone-text &optional zone

    Returns a string that is the text contained in zone. If zone is omitted, the zone-at point is used, if any. Returns the empty string for an empty zone or no zone.

    Variable: epoch::zones-modify-buffer

    If non-nil, changing any zones with Epoch primitives will cause the associated buffer to be marked as changed. Useful if you want to use write-file-hooks that save zone information.

    Deleting Zones

    Function: epoch::delete-zone zone

    Removes zone from the buffer in which it resides. The argument must be the actual zone itself, not a copy. This can be obtained by saving the result from epoch::make-zone or other zone-returning primitives. Returns the zone if successful, nil otherwise.

    Function: epoch::delete-zone-at position &optional buffer

    Removes the zone (if any) that contains position in buffer. Returns the zone if successful, nil otherwise. This is equivalent to (epoch::delete-zone (epoch::zone-at position buffer) buffer).

    Function: epoch::clear-zones &optional buffer

    Removes all zones from buffer. Returns t if succesful, nil otherwise.

    Style Primitives

    Epoch supports a completely style-based display wherein styles describe the context for displaying normal text, text within zones, text cursors, and modelines. Each style has a number of different fields.

    Foreground and background colors control how normal characters are displayed in the style.

    Cursor foreground and background indicate how a character within the text cursor is displayed. If cursor colors are not set but text colors are, the cursor will use the inverse of the text colors.

    The underline color controls how the characters are underlined. If set to a color, a line of that color is drawn under characters using that style. If set to nil, no line is drawn.

    A stipple pattern must be a X-bitmap resource (See section X Objects). For text, the "on" bits in the stipple are displayed in the text foreground color and the "off" bits in the text background color. The character background is either solid background color, or the "on" bits are displayed in the screen background color and the "off" bits in the text background. For the cursor, the cursor colors are used, and the cursor stipple (if any) is used in place of the background stipple for the cursor background. If the cursor stipple is not set and the background stipple is, the cursor background is not stippled.

    When displaying text within a given buffer, a hierarchy of styles exists for determining display attributes:

    1. Zone styles
    2. Buffer-local styles
    3. Screen based styles

    Note: Screen based styles are changed via primitives such as epoch::foreground epoch::background, epoch::cursor-color, epoch::font. All style fields are guaranteed to be valid at the screen level.

    Function: epoch::make-style

    Creates a style object. Initially all fields are set to nil.

    Function: epoch::stylep object

    Returns t if object is a style, else nil.

    Function: epoch::style-foreground style

    Returns the foreground color of style.

    Function: epoch::set-style-foreground style color

    Sets style to foreground color.

    Function: epoch::style-background style

    Returns the background color of style.

    Function: epoch::set-style-background style color

    Sets style to background color.

    Function: epoch::style-cursor-foreground style

    Returns the cursor foreground color of style.

    Function: epoch::set-style-cursor-foreground style color

    Sets style to cursor foreground color.

    Function: epoch::style-cursor-background style

    Returns the background cursor color of style.

    Function: epoch::set-style-cursor-background style color

    Sets style to cursor background color.

    Function: epoch::style-underline style

    Returns the underline color.

    Function: epoch::set-style-underline style color

    Sets style underline to color.

    Function: epoch::style-stipple style

    Returns the text stipple for the style.

    Function: epoch::set-style-stipple style stipple

    Sets the text stipple pattern for style to stipple.

    Function: epoch::style-background-stipple style

    Returns the background stipple for style.

    Function: epoch::set-style-background-stipple style stipple

    Sets the background stipple pattern for style to stipple.

    Function: epoch::style-cursor-stipple style

    Returns the stipple pattern for the cursor for style.

    Function: epoch::set-style-cursor-stipple style stipple

    Sets the cursor stipple pattern for style to stipple.

    Function: epoch::style-font style

    Returns the font associated with style, or nil if none is specified.

    Function: epoch::set-style-font style font

    Sets the font for style to be font.

    Function: epoch::style-tag style

    Returns the tag value associated with style, or nil if none is specified.

    Function: epoch::set-style-tag style tag

    Sets the tag value associated with style to tag.

    Variable: motion::style

    This style, which defaults to underlining in the foreground color, is the style used by Epoch mouse dragging code found in `motion.el'. Its value is set at runtime, and may be superceded by values in the file `.emacs'.

    The following code is used to set up the default style for mouse dragging, and demonstrates the use of Epoch and style primitives.

    (setq motion::style (make-style))
    (set-style-foreground motion::style (foreground))
    (set-style-background motion::style (background))
    (set-style-underline motion::style (foreground))
    

    Variable: buffer-style

    This variable is set to the style used by Epoch to display text in this buffer. It defaults to nil, and becomes local when set in any fashion.

    The variable buffer-style may also be set using the local variables list in files. The following code would specify a major mode of tex-mode and a buffer style of tex-mode-style (which could select a proportional font):

    In `.emacs':

    (setq tex-mode-style 
      (let ((s (make-style)))
        (set-style-font s "variable")
      )
    )
    

    In TeX file:

    #;;; Local Variables: ***
    #;;; mode: tex ***
    #;;; buffer-style: tex-mode-style ***
    #;;; End: ***
    

    Modelines

    It is also possible to embed styles into the variables that define the modeline format. For details on modeline constructs, see section 20.3 of the Emacs Lisp Reference Manual. Note that modelines being displayed with styles will override the value of mode-line-inverse-video.

    Variable: mode-line-inverse-video

    If this variable is non-nil, the modeline will be displayed in inverse video or another suitable display mode.

    Variable: default-mode-line-format

    This variable holds the default mode-line-format for buffers that do not override it. This is the same as (default-value 'mode-line-format).

    Variable: mode-line-format

    The value of this variable is a modeline construct responsible for the mode line format. This variable is buffer-local.

    The following is an example of Elisp code to embed styles in mode lines.

    ;; Hilight "Epoch" and buffer name in current buffer's modeline.
    ;; s1 -> hilight style
    (setq s1 (make-style))
    (set-style-foreground s1 "red")
    (set-style-background s1 "white")
    (set-style-font s1 "fixed")
    
    ;; s2 -> normal style
    (setq s2 (make-style))
    (set-style-foreground s2 "black")
    (set-style-background s2 "white")
    (set-style-font s2 "variable")
    
    ;; define modeline format
    (setq mode-line-format
      (list
        s2 "" mode-line-modified
        s1 mode-line-buffer-identification s2
        "   " global-mode-string "   %[(" mode-name minor-mode-alist
        "%n" mode-line-process ")%]----" (cons -3 "%p") "-%-"
    ))
    

    Zone Plotting

    When a buffer is plotted, zones are extracted from the buffer zone list and used to change the colors of the text and cursor. If the zones are disjoint, then the choice of a zone to use for a given character is unambiguous. Overlapping zones cause a more complex situation. The algorithm for deciding which style are used when zones overlap is described next.

    The zone plotting algorithm assumes that the zone list is sorted by starting position. If zones overlap, the zone with the largest starting position takes precedence. This allows zones to nest, so that if one zone is entirely inside another, both zones are visible. If two zones overlap without containment, the second zone will be entirely visible, and the first truncated. Whenever there is a reference to the zone "at" a location, that means the zone that was plotted at that location.

    A zone with a non-null style always has precedence over a zone with null style. This means that if a zone with an null style follows and overlaps a zone of non-null style, the preceeding zone will be plotted in the overlap region. Null styles are intended for hidden or non-user zones (such as for tagging a region of text with data), and this rule prevents them from interfering with visible zones.

    Read-only Zones

    In the case of a read-only zone (in which the read-only field is t), most attempts to change text within the zone will result in an error analogous to the error caused by attempting to change a read-only buffer. Two exceptions to this rule exist at zone boundaries.

    1. Attempted changes on the first character of the zone will be allowed, but will be diverted to the left of the zone itself so that the zone is not extended.
    2. Attempted changes to the immediate right of the zone will be permitted, but the zone will not be extended. This is really a change outside of the zone.

    Essentially, this implies that the size of a read-only zone will only change because of explicit commands to change the zone boundaries and not by inserting or deleting text within the zone. Changing the location of a read-only zone by altering text previous to the zone is permitted; this is even possible with adjoining read-only zones (unless they explicitly overlap).

    Function: add-read-only-zone start end attribute &optional data buffer

    This is the same as epoch::add-zone except that the zone is set to be read-only immediately after being created.

    Function: epoch::read-only-region-p start end &optional buffer

    Given a region delimited by start and end in buffer, checks for read-only zones. Returns nil if region contains no read-only zones; otherwise it returns the zone. In cases of overlapping zones, the display rule discussed earlier is obeyed (See section Zone Plotting).

    Note: When checking for insert operation, use the insertion point for both start and end. If this would normally be inside the zone, but because of insertion rules is deflected to the side of the zone, this function will not return the zone.

    Function: epoch::zone-read-only zone

    Returns zone's current read-only value.

    Function: epoch::set-zone-read-only zone flag

    Sets the zone's read-only flag to flag, which must be either t or nil.

    Graphical Zones

    Epoch now supports displaying graphical images (X pixmaps) in zones. This requires the Groupe Bull's XPM version 3 library, which is on the X11R5 contrib tape. The library is also available via anonymous ftp from export.lcs.mit.edu (18.24.0.12) and avahi.inria.fr (192.5.60.47). To enable graphical zones, you must compile Epoch with HAVE_GRAPHIC_ZONES enabled in `config.h'.

    Note: You may need to edit `button.c' to include `xpm.h' appropriately.

    Once Epoch has been built in this manner, several new Elisp primitives become available:

    Function: add-graphic-zone pixmap-name start end &optional offset data buffer read-only

    Adds a graphical zone corresponding to a pixmap named pixmap-name from start to end in buffer (or current buffer if buffer is nil). Zone will have data value data and will be read-only if read-only is non-nil. offset describes the percentage of the graphical image which will appear below the baseline; 0 (default) corresponds to an image totally above the baseline, 100 corresponds to totally below. pixmap-name can also be an X Resource of type pixmap. Returns the zone if successful.

    Function: epoch::define-opaque-font name width height &optional offset

    Defines a psuedo-font for displaying graphical images. Font name will have width width and height height. As above, offset describes the percentage of the font which will appear below the baseline. Returns the name, or nil.

    Function: epoch::read-pixmap-file filename

    Using the Xpm library, reads in filename and create an X pixmap corresponding to it. Return an X Resource of type Pixmap if successful, otherwise nil. filename must correspond to the complete filename (including extensions) of a text file in the X Pixmap Format, or else an X Resource of type Pixmap.

    Function: epoch::query-pixmap pixmap

    Returns a list of the form (width height depth) corresponding to an X pixmap. pixmap should be an X Resource of type Pixmap.

    Function: epoch::set-style-pixmap style pixmap

    Sets style style to reference pixmap. pixmap should be an X Resource of type Pixmap, or nil.

    Function: epoch::style-pixmap style

    Returns the pixmap associated with style.

    Note: If a buffer containing a graphical zone is being displayed in a window which is too small to display the entire graphical image, in most cases no text will be displayed in the window.

    Zones and Undo

    It is possible for undo operations to restore affected zones to their previous positions. This is primarily noticeable for undoing delete operations. This feature is enabled by default, but may be disabled by setting the buffer-local variable undo-restore-zones. Any zones with the transient field set to t will be ignored.

    Variable: undo-restore-zones t

    If set to non-nil, then zone information will be stored with all delete operations so that undo may restore the zones to their previous positions. This variable becomes buffer-local when set in any fashion.

    Events

    Epoch provides the ability to handle X Window System events in Elisp.

    Event Basics

    Events are the mechanism the X Window System uses to communicate with client programs such as Epoch.

    Certain types of X events, listed below, are stored into a queue, the event-queue. Whenever such an event is received by Epoch, it is stored in the event-queue, and an event-key is inserted into the keyboard buffer. Whenever the keyboard is checked for keys, these event keys are read and processed until there are none left or an actual key is encountered. For each of these events, the variable epoch::event is bound to the value of the event, and the event handler epoch::event-handler is called. (See section Basic Event Handling to learn more about that subject.)

    Each event is returned as a vector of four elements. The first is the event type, the second is data associated with the event, the third is the screen on which the event occured, and the fourth is the time-stamp indicating the time the event occured (this will be nil for focus, map, resize, and client-message events).

    Epoch currently captures the events described in the following table:

    Event
    Data

    focus
    t for focus-in, nil for focus-out

    property-change
    If epoch::lazy-events is nil, then a cons pair. Car is name of property (a string), cdr is new value of property. Otherwise, the value is just the X-atom resource of the property. (See section Property Change Events)

    selection-clear
    atom corresponding to selection name (See section Selection Events).

    map
    t for map, nil for unmap.

    move
    Cons pair: x-position, y-position in pixels.

    resize
    List of three elements: new width, new height, outer borderwidth.

    client-message
    A triple of the form (TYPE FROM . DATA). See description of epoch::send-client-message below for an explanation. (See section Client Message Events).

    button
    A 5-tuple of form (Press/Release x-coord y-coord button mod-state). (See section Mouse Events)

    motion
    A triplet of the form (x-coord y-coord mod-state). (See section Motion Events).

    To support asynchronous communication through events, Epoch provides primitives to set and read X Properties (See section X Properties), and a property event handler. Primitives are also provided to send client messages.

    Client messages are sent through the epoch::send-client-message function and received through events of type client-message.

    Variable: epoch::lazy-events

    If this variable is non-nil, then the internal event code will do as little work as possible. Primarily, property events will only report the atom of the property changed, and leave it up to other code to acquire the value if desired. (See section Property Change Events)

    Variable: epoch::mouse-events

    If this variable is non-nil, then mouse events are placed into the Epoch event queue instead of generating fake key strokes.

    Basic Event Handling

    Events are handled by binding the variable epoch::event-handler to a function of no arguments. Whenever an event is dispatched as described above, if epoch::event-handler is non-nil, the value in it is called as a no argument function. This function should then examine the value of epoch::event and take appropriate action.

    If any error occurs while the event handler is being executed, then the behavior depends on the value of the variable epoch::event-handler-abort. If this is t, then the event-handler is aborted by resetting the variable to nil. This action prevents runaway errors on every following event. If the variable epoch::event-handler-abort is nil then this action is not taken.

    In order to make event handling easier, a standard set of event handling functions are provided. These provide a (somewhat) widget-like interface to events. Selected parts of the interface can be replaced without change to the underlying internals. Event handling is organized hierarchially -- the top level handler invokes other handlers to dispatch the final handling routines. The following description is from the top down.

    The basic event handler maintains an internal alist to associate event types with event handlers. An event type is the symbolic name corresponding to a class of X events. An event handler is an Elisp function that may be called when an event occurs.

    For each event type, a stack of event handlers is kept, and when an event of that type occurs, the function at the top of the stack is called with arguments showed below. This allows you to change the event handler behavior in a restorable way. Each basic event type must be installed before any events will be dispatched for it; this allows events to be globally disabled and reenabled. Currently the Epoch Elisp files (See section Packages) install all supported events.

    When the basic handler runs, epoch::event-handler-abort is initially set to t. It then watches for errors during the dispatch of an event, which are detected by checking epoch::event-handler after returning from the dispatch. If epoch::event-handler has been set to nil, an error is presumed to have occured, and ignore-event is called on that event. This provides improvements over the built-in system, in that only a particular type of event is ignored (others continue to dispatch), and service can be restored with a simple (resume-event event), independent of the actual names of the handlers. This also means that handlers can be anonymous, i.e. push-event can be passed a lambda expression instead of the symbol name of a function.

    Event handler functions should be defined as follows:

    (defun my-event-handler (event-type value screen)
      "event-type is the type of the event.  value is the value of
    the event, and screen is the screen that received the event.
    Handlers can call the event handling interface routines, so that a
    one-shot handler (which pops itself) can be set up."
      )
    

    The following functions and variables form the interface to the event handling system.

    Variable: epoch::event-handler

    Variable that contains nil or a function to be called when there are pending property change events. The handler should use the variable epoch::event to retrieve the current event. If epoch::event-handler has been set to nil after an event has been dispatched, an error is presumed to have occured (see above).

    Variable: epoch::event

    Just before the event handler in epoch::event-handler is called, this variable is bound to the value of the event that caused the handler call. It is a vector of size four, consisting of the event type, the event value, the screen where the event occurred, and the event's timestamp (if available).

    Variable: epoch::event-handler-abort

    If this variable is non-nil, then if an error occurs while the event handler is running, epoch::event-handler is set to nil. This prevents an error in some part of the event handler code from causing Epoch to lock up with excessive errors.

    Function: epoch::get-event

    All events are stored in an internal event queue. This primitive returns the oldest event in the event queue as an Elisp vector of size three. The zeroth element is the type of the event, the first element is the value of the event, the second element is the screen on which the event occurred, and the third element is the event's timestamp (if available).

    Function: install-event event

    This puts event into the handler alist. event can be anything, but unless it is eq to an event type, it will never be dispatched; instead it will be ignored.

    Function: remove-event event

    Removes event from the handler alist. All handlers associated with it are lost.

    Function: push-event event handler

    Installs handler for event. Handlers are installed in a stack, and the handler at the top of the stack is dispatched for the event.

    Function: pop-event event

    Removes and returns the top level handler for event.

    Function: ignore-event event

    Pushes a marker onto the handler stack for event so that the event is not dispatched.

    Function: resume-event event

    Pops the ignore marker from the top of the handler stack for event. Note that these two functions are different from remove-event and install-event in that these allow temporary, transparent inhibition of events in a local area, while the latter have global effects.

    Function: display-event-status

    Print the current event handler status into a buffer and display it in a window on the current screen. Normally bound to C-z e. The status keys are H for being handled, I for ignored, and U for uninstalled. If a number follows the letter, that is the depth of the handlers or ignore markers.

    Advanced Event Handling

    In addition to the standard event handling facilities just described, it is occasionally necessary to specially handle certain event types.

    Function: epoch::wait-for-event event-type handler

    This primitive will wait for an event-type type to occur, and then call handler if non nil. handler should be a function defined similarly to other event handler functions See section Basic Event Handling. Any other events which are received during the wait are stored and dispatched in the order of arrival after the desired event has occured. The function will return after this has occured. Note: This function could cause deadlock if the selected event type does not occur.

    Property Change Events

    The Epoch Elisp files set up a handler for the property-change event which then dispatches based on the property, in a manner analagous to the basic event handling. This property event handler uses lazy events (see epoch::lazy-events in See section Basic Event Handling.) This means that a property change event has a value of just the X-atom resource corresponding to the property that changed.

    Implementation note: Property events are passed as lazy events to save the expense of unneeded round-trip server requests. With non-lazy events, all property events would involve two round-trip requests, one for the atom and another for the value. However, most property events are not handled, and so such information is simply thrown away. With this system, only those property events that are actually dispatched invoke this expense, and in many cases the name of the property is unnecessary. (If the handler function is attached to only one property, then it implicitly knows the property name value.) The primitive equal has been extended to provide comparisons for X Resources (See section X Resources).

    Each installed property is stored as the X-atom resource and a stack of handlers. If the top entry is a function, then it is called with the same parameters as for basic event handling. (The event type will always be property-change, but this allows a consistent handler interface for all handler functions.) If the property is not in the alist, or the top entry is not a function, the property change is ignored.

    In contrast to basic event handling, if the property is not installed, pushing the property handler will install it. The inhibition of handling for certain properties is not as useful as for events. Since the number of possible property events is far larger than the number of possible event types, the extra hassle of having to seperately install properties was judged to be too much. The install-property and remove-property should be used seldom, if at all, and are provided primarily for conformity with basic event handling.

    Property change handler functions should be of the same form as the general event handlers. Note that the value of the property change is passed as an X-atom. If the value of the property is desired, the function get-property can be used. If the name of the property is needed, use unintern-atom.

    One way that property change events can be used is to send messages to and receive messages from the window manager. We use this facility extensively to display menus to the user, change window names and decorations, etc. X properties are manipulated and accessed through the epoch::set-property and epoch::get-property functions (See section X Properties).

    Epoch maintains two properties on the screens automatically. These are EPOCH_SCREEN_ID, which is an integer that is the screen ID, and EPOCH_CURRENT, which is a string, either "yes" if that screen is the current edit screen, "no" if it is not, or "minibuf" if it is the minibuffer.

    The following functions are the interface to the property event handling system.

    Function: install-property property

    This puts property into the handler alist. property should be the name of an X Property (i.e. a string or X Atom).

    Function: remove-property property

    Removes property from the handler alist. All handlers associated with it are lost.

    Function: push-property property handler

    Installs handler for property. Handlers are installed in a stack, and the handler at the top of the stack is dispatched for the property. If the property is not already in the handler list, it is added.

    Function: pop-property property

    Removes and returns the top level handler for property.

    Function: ignore-property property

    Pushes a marker onto the handler stack for property so that the property is not dispatched.

    Function: resume-property property

    Pops the ignore marker from the top of the handler stack for property.

    Selection Events

    There are three types of events associated with X11 selections, two of which may be handled in Elisp (See section X Selections). selection-clear events are handled based on selection name with a handler similar to other events. selection-request events are handled internally unless the requested target atom is non-standard.

    Variable: epoch::convert-selection-hook convert-to-target

    The function named by this hook will be called for any selection-requests with non-standard target atoms.

    Function: add-selection-target target function

    Adds target to list of user-defined target atoms. function will be called for conversion requests of this type.

    Function: convert-to-target target

    Called by epoch::convert-selection-hook to call appropriate conversion function based on target. If no function exists, return nil.

    Function: install-selection selection

    Puts selection on handler alist. selection should be the name of an X Selection (i.e. a string or X Atom).

    Function: remove-selection selection

    Removes selection from handler alist. All handlers associated with it are lost.

    Function: push-selection selection handler

    Installs handler for selection. Handlers are installed in a stack, with the handler at the top of the stack is dispatched for the selection. If the selection is not already on the handler list, it is added.

    Function: pop-selection selection

    Removes and returns the top level handler for selection.

    Function: ignore-selection selection

    Pushes a marker onto the handler stack for selection so that the selection is not dispatched.

    Function: resume-selection selection

    Pops the ignore marker from the top of the handler stack for selection.

    Note: If no handler is installed for a given selection, then selection-clear events received will be handled generically, with any data for that selection being deleted from epoch::selection-alist. If a handler has been installed for a selection, it is the responsibility of that handler to remove data from epoch::selection-alist if this behavior is desired.

    Client Message Events

    The Epoch Elisp files set up a handler for the client-message event which then dispatches based on the message type. Each installed property is stored as the X-atom resource and a stack of handlers. If the top entry is a function, then it is called, with the same parameters as for basic event handling. If the message type is not in the alist, or the top entry is not a function, the message is ignored.

    The value of a client message is a list of ( type source . data ) where type is the message type X-atom resource, source is an X-window resource specifying the source window, and data is the data field of the message converted to Elisp data in the same manner as X property values (See section X Properties). To send client mesages, See section Client Messages.

    If the message type is not installed, pushing a handler will install it. install-message and remove-message should be used seldom, if at all, and are provided primarily for conformity with basic event handling.

    The following functions are the interface to the client message event handling system.

    Function: install-message message

    This puts message into the handler alist. message should be either a string or X Atom.

    Function: remove-message message

    Removes message from the handler alist. All handlers associated with it are lost.

    Function: push-message message handler

    Installs handler for message. Handlers are installed in a stack, and the handler at the top of the stack is dispatched for the message. If the message is not already in the handler list, it is added.

    Function: pop-message message

    Removes and returns the top level handler for message.

    Function: ignore-message message

    Pushes an ignore marker onto the handler stack for message so that the message is not dispatched.

    Function: resume-message message

    Pops the ignore marker from the top of the handler stack for message.

    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.

    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:

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

    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.

    X11 Primitives

    Here we describe various primitive X11 facilities.

    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.

    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, See section 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).

    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. See section 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, 0s 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"))
    

    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.

    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.

    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.

    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.

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

    `motion.el'
    Handles mouse motion events. Provides dragging and pasting operations. (See section 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 section 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 section 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:

    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 section 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.

    Index

    $

  • $HOME/.Xdefaults-<hostname>

    *

  • *create-screen-alist-hook*
  • *select-screen-hook*

    a

  • add-graphic-zone
  • add-read-only-zone
  • add-selection-target
  • after-change-function
  • after-movement-function
  • app-defaults
  • ASCII Support
  • asynchronous communication
  • auto-raise-screen

    b

  • background color
  • before-change-function
  • border color
  • buffer-style
  • bug reports
  • button event
  • button events
  • button.el

    c

  • C-z
  • C-z e
  • change hooks
  • client message event
  • client messages
  • CLIPBOARD
  • color vector or string
  • colors
  • command line options
  • convert-buttons.el
  • convert-to-target
  • coordinates-in-window-p
  • copy-mouse-map
  • create screen
  • create-mouse-map
  • create-screen
  • create-screen properties alist
  • ctl-arrow
  • current screen
  • current-pixel
  • cursor background color
  • cursor foreground color
  • cursor glyph
  • cursor-color
  • cut and paste

    d

  • dbx
  • default sets
  • default-mode-line-format
  • defaults in command line options
  • define-mouse
  • DEFINE_CHANGE_FUNCTIONS
  • deleting zones
  • display-event-status

    e

  • edit screens
  • epoch version
  • epoch-mode-alist
  • epoch-mode-alist properties alist
  • epoch-setup-hook
  • epoch-util.el
  • epoch.el
  • epoch::
  • epoch::acquire-selection
  • epoch::add-zone
  • epoch::background
  • epoch::bell-volume
  • epoch::change-screen-size
  • epoch::clear-zones
  • epoch::color-components
  • epoch::convert-selection
  • epoch::convert-selection-alist
  • epoch::convert-selection-hook
  • epoch::coords-to-point
  • epoch::create-screen
  • epoch::create-screen properties alist
  • epoch::current-screen
  • epoch::cursor-background
  • epoch::cursor-foreground
  • epoch::cursor-glyph
  • epoch::define-opaque-font
  • epoch::delete-screen
  • epoch::delete-zone
  • epoch::delete-zone-at
  • epoch::event
  • epoch::event-handler
  • epoch::event-handler-abort
  • epoch::first-window
  • epoch::flash-screen
  • epoch::font
  • epoch::foreground
  • epoch::free-bitmap
  • epoch::free-color
  • epoch::function-key-mapping
  • epoch::get-buffer-window
  • epoch::get-color
  • epoch::get-color-rw
  • epoch::get-default
  • epoch::get-event
  • epoch::get-font
  • epoch::get-property
  • epoch::get-screen
  • epoch::get-screen-id
  • epoch::get-selection-owner
  • epoch::global-update
  • epoch::icon-name
  • epoch::icon-pixmap
  • epoch::iconify-screen
  • epoch::intern-atom
  • epoch::lazy-events
  • epoch::load-bitmap
  • epoch::lower-screen
  • epoch::make-bitmap
  • epoch::make-style
  • epoch::make-zone
  • epoch::map-screen
  • epoch::mapraised-screen
  • epoch::minibuf-screen
  • epoch::mod-to-shiftmask
  • epoch::motion-hints-p
  • epoch::mouse-events
  • epoch::move-screen
  • epoch::move-zone
  • epoch::next-screen
  • epoch::nonlocal-minibuffer
  • epoch::number-of-colors
  • epoch::plane-size
  • epoch::prev-screen
  • epoch::query-cursor
  • epoch::query-cursor-pixels
  • epoch::query-mouse
  • epoch::query-pixmap
  • epoch::query-pointer
  • epoch::query-tree
  • epoch::raise-screen
  • epoch::read-only-region-p
  • epoch::read-pixmap-file
  • epoch::rebind-key
  • epoch::redisplay-screen
  • epoch::resource-to-string
  • epoch::resource-to-type
  • epoch::resourcep
  • epoch::screen-height
  • epoch::screen-information
  • epoch::screen-list
  • epoch::screen-mapped-p
  • epoch::screen-of-window
  • epoch::screen-p
  • epoch::screen-properties
  • epoch::screen-properties alist
  • epoch::screen-width
  • epoch::screenp
  • epoch::screens-of-buffer
  • epoch::select-screen
  • epoch::selected-window
  • epoch::selection-alist
  • epoch::selection-timeout
  • epoch::send-client-message
  • epoch::set-bell
  • epoch::set-color-rw
  • epoch::set-motion-hints
  • epoch::set-property
  • epoch::set-resource-type
  • epoch::set-screen-modified
  • epoch::set-style-background
  • epoch::set-style-background-stipple
  • epoch::set-style-cursor-background
  • epoch::set-style-cursor-foreground
  • epoch::set-style-cursor-stipple
  • epoch::set-style-font
  • epoch::set-style-foreground
  • epoch::set-style-pixmap
  • epoch::set-style-stipple
  • epoch::set-style-tag
  • epoch::set-style-underline
  • epoch::set-update
  • epoch::set-zone-data
  • epoch::set-zone-read-only
  • epoch::set-zone-style
  • epoch::set-zone-transient
  • epoch::string-to-resource
  • epoch::style-background
  • epoch::style-background-stipple
  • epoch::style-cursor-background
  • epoch::style-cursor-foreground
  • epoch::style-cursor-stipple
  • epoch::style-font
  • epoch::style-foreground
  • epoch::style-pixmap
  • epoch::style-stipple
  • epoch::style-tag
  • epoch::style-underline
  • epoch::stylep
  • epoch::synchronize-minibuffers
  • epoch::title
  • epoch::ungrab-pointer
  • epoch::unintern-atom
  • epoch::unmap-screen
  • epoch::update-p
  • epoch::version
  • epoch::wait-for-event
  • epoch::warp-mouse
  • epoch::warp-pointer
  • epoch::xid-of-screen
  • epoch::zone-at
  • epoch::zone-buffer
  • epoch::zone-data
  • epoch::zone-end
  • epoch::zone-list
  • epoch::zone-read-only
  • epoch::zone-start
  • epoch::zone-style
  • epoch::zone-transient-p
  • epoch::zonep
  • epoch::zones
  • epoch::zones-at
  • epoch::zones-modify-buffer
  • equal
  • event handler errors
  • event inhibition
  • event key
  • event queue
  • event screen
  • event types
  • event value
  • event.el
  • external and internal borderwidth of screen
  • external border width

    f

  • fill mode extensions
  • fill-pixel
  • find-style-hook
  • font
  • foreground color
  • Frequently Asked Questions

    g

  • generic window manager
  • global-set-mouse
  • GNU Emacs compatibility
  • Graphical zones
  • GWM

    h

  • hooks
  • horizontal-drag-inc
  • hypertext

    i

  • ICCCM compatability for deletion
  • ICCCM compatibilty for iconify
  • icon name
  • IconicState
  • ignore-event
  • ignore-message
  • ignore-property
  • ignore-selection
  • include-system-name
  • inhibit-initial-screen-mapping
  • install-event
  • install-message
  • install-property
  • install-selection
  • internal border width
  • internal event queue

    k

  • key bindings
  • keyboard queue
  • kill-local-mouse-map

    l

  • line-fill-hook
  • lisp packages
  • local-set-mouse

    m

  • mailing list support
  • make-id
  • make-screen
  • map and unmap events
  • mapped screen
  • menu::popup
  • menus
  • message.el
  • mini-cl.el
  • minibuffer background
  • minibuffer border color
  • minibuffer border width
  • minibuffer class
  • minibuffer cursor background
  • minibuffer cursor color
  • minibuffer cursor foreground
  • minibuffer cursor glyph
  • minibuffer font
  • minibuffer foreground
  • minibuffer geometry
  • minibuffer internal border width
  • minibuffer modes
  • minibuffer name
  • minibuffer resource name
  • minibuffer reverse
  • minibuffer screens
  • minibuffer title
  • minor screens
  • mode-line-format
  • mode-line-inverse-video
  • Modeline format
  • motion event
  • motion events
  • motion.el
  • motion::style
  • mouse dragging
  • mouse events
  • mouse.el
  • mouse::clicks
  • mouse::interval
  • mouse::last-spot
  • mouse::selection-atom
  • mouse::set-point
  • mouse::time-stamp
  • mouse::x
  • mouse::y
  • move event
  • move-to-pixel
  • multiple mouse clicks
  • multiple screen updates

    n

  • NormalState
  • null zone styles

    o

  • on event handling
  • on-map-do
  • on-move-do
  • on-resize-do
  • on-unmap-do
  • one-shot event handlers
  • Openwindows
  • overlapping zones

    p

  • pool:create
  • pool:delete
  • pool:get-screen
  • pool:get-screen-with-buffer
  • pool:get-shrink-wrapped-screen
  • pool:mark-screen
  • pool:unmark-screen
  • pop-event
  • pop-message
  • pop-property
  • pop-selection
  • PRIMARY
  • property X-atom
  • property-change event
  • property-change events
  • property.el
  • push-event
  • push-message
  • push-property
  • push-selection

    r

  • read-only zones
  • recenter
  • red green blue components
  • redraw-display
  • remove-event
  • remove-message
  • remove-property
  • remove-selection
  • resize event
  • resource class
  • resource manager
  • resource name
  • resume-event
  • resume-message
  • resume-property
  • resume-selection
  • reverse
  • reverse colors

    s

  • Saving Zones
  • scr-pool.el
  • screen autoraise
  • screen background
  • screen border color
  • screen border width
  • screen class
  • screen class name
  • screen cursor background
  • screen cursor color
  • screen cursor foreground
  • screen cursor glyph
  • screen default-sets
  • screen font
  • screen foreground
  • screen geometry
  • screen icon name
  • screen ID or screen object
  • screen initial state
  • screen internal border width
  • screen mapped state
  • screen name
  • screen naming
  • screen object
  • screen pools
  • screen properties or attributes
  • screen resource name
  • screen reverse
  • screen title
  • screen updating
  • screens
  • scrolling drag
  • selected screen
  • selected-window
  • selection-clear event
  • selection.el
  • standard extensions
  • Style hierarchy
  • Style Primitives
  • styles
  • symbol-buffer-value

    t

  • text cursor color
  • text-width

    u

  • undo-restore-zones
  • unmapped screen
  • unmapped screens list
  • use-local-mouse-map

    v

  • vertical-drag-inc

    w

  • waiting for events
  • width and height of screen
  • window configuration
  • window title
  • window-edges
  • window-height
  • window-pixedges
  • window-pixheight
  • window-pixwidth
  • window-width
  • windowing system controls
  • WM_DELETE_WINDOW
  • WM_ICON_NAME
  • wrapper.el

    x

  • X and Y location of screen
  • X class defaults
  • X cursor
  • X objects
  • X parent resource id
  • X program or window class name
  • X program or window resource name
  • X properties
  • X resources
  • X resources database
  • X window display
  • X Window display
  • X Window program defaults
  • X windows and GNU Emacs windows
  • X Windows required
  • XAPPLRESDIR
  • XENVIRONMENT
  • xmenu
  • Xpm
  • xrdb

    z

  • zone creation
  • zone display
  • zone object
  • zone plotting
  • zone-text
  • zone.el
  • zones
  • Zones and Undo