Info file ../info/epoch, produced by Makeinfo, -*- Text -*- from input file epoch.texinfo. This file documents Epoch 4.1, a modified version of GNU Emacs. Copyright (C) 1989, 1990, 1991, 1992 by The Epoch Development Team: Simon Kaplan (`kaplan@cs.uicu.edu'); Leadership, design, manual Christopher Love (`love@cs.uiuc.edu'); Implementation, design, manual, support Alan M. Carroll (`carroll@cs.uiuc.edu'); Implementation, design, manual Daniel M. LaLiberte (`liberte@cs.uiuc.edu'); Manual support Marc Andreessen (`marca@cs.uiuc.edu'); Epoch 4.0+ support Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: epoch, Node: top, Next: Introduction, Prev: (dir), Up: (dir) * Menu: * Introduction:: Introduction * General Information:: General Information * Screens:: Screens * Zones:: Zones * Events:: Events * X11 Primitives:: X11 Primitives * Miscellaneous:: Miscellaneous * Index:: Index  File: epoch, Node: Introduction, Next: General Information, Prev: top, Up: top Introduction ************ Epoch is a modified version of GNU Emacs with several major enhancements: * Multiple X window support. * Marked and styled regions of text. * Support for proportional and variable-sized fonts. * Support for 8-bit clean fonts (ISO, Latin-1, etc.). * Asynchronous communication with other X clients (e.g., the window manager). * Mouse-dragging with highlighting to support mouse-based cut and paste. * Access to raw X-Window objects. 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 (*Note 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 *Note General Information::. There is now a list of frequently asked questions; refer to the file `etc/EPOCH-FAQ'. * Menu: * Support and Mailing List:: Support and the Epoch mailing list. * Getting Epoch:: Getting Epoch. * Acknowledgements:: Acknowledgements.  File: epoch, Node: Support and Mailing List, Next: Getting Epoch, Prev: Introduction, Up: Introduction 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.  File: epoch, Node: Getting Epoch, Next: Acknowledgements, Prev: Support and Mailing List, Up: Introduction 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.  File: epoch, Node: Acknowledgements, Prev: Getting Epoch, Up: Introduction 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.  File: epoch, Node: General Information, Next: Screens, Prev: Introduction, Up: top General Information ******************* * Menu: * Getting Started:: Getting Started with Epoch * New Features:: New Features in Epoch * Key Bindings:: Key Bindings in Epoch * Conventions:: Epoch Conventions * Menus:: Menus  File: epoch, Node: Getting Started, Next: New Features, Prev: General Information, Up: 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 (*Note 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. * Menu: * X Window Program Defaults:: X Window program defaults. * Command Line Options:: Command line options.  File: epoch, Node: X Window Program Defaults, Next: Command Line Options, Prev: Getting Started, Up: Getting Started 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.) *Note 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. or 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-'. 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 (*Note 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' , Resource class of the edit screen `.minibuf.class' , 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' , Resource name of the edit screen `.minibuf.resource' , 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  File: epoch, Node: Command Line Options, Prev: X Window Program Defaults, Up: Getting Started 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 (*Note 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.  File: epoch, Node: New Features, Next: Key Bindings, Prev: Getting Started, Up: General Information 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.  File: epoch, Node: Key Bindings, Next: Conventions, Prev: New Features, Up: General Information 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 (*Note 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.  File: epoch, Node: Conventions, Next: Menus, Prev: Key Bindings, Up: General Information Conventions =========== Several conventions are used in the following chapters. * Functions and variables are described with the format used in the Emacs Lisp Reference Manual. * Any SCREEN argument can be a screen ID or a screen object. Optional screen arguments default to the current screen. * Any COLOR argument can be an X Resource of type X-Cardinal (*Note X Resources::), a vector or a string. Strings and vectors are converted to X-Cardinals internally. 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.  File: epoch, Node: Menus, Prev: Conventions, Up: General Information 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 (*Note 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.  File: epoch, Node: Screens, Next: Zones, Prev: General Information, Up: top Screens ******* This chapter describes screen features supported by Epoch, except for the Elisp extensions described in *Note Miscellaneous::. * Menu: * Screen Basics:: Screen Basics * Screen Properties:: Screen Properties * Controlling Screens:: Controlling Screens * Screens and Windows:: Screens and Windows * Variable sized Fonts:: Variable sized Fonts * Manipulating Screens:: Manipulating Screens * Screen Updating:: Screen Updating * Icons:: Icons  File: epoch, Node: Screen Basics, Next: Screen Properties, Prev: Screens, Up: Screens 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 *Note Screen Updating::). Epoch adds "screens" as a new Emacs Lisp primitive type. Screens are printed as `#', 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 *Note Screen Pools:: for an example.  File: epoch, Node: Screen Properties, Next: Controlling Screens, Prev: Screen Basics, Up: Screens 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 *Note 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 (*Note 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 *Note 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.  File: epoch, Node: Controlling Screens, Next: Screens and Windows, Prev: Screen Properties, Up: Screens 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.  File: epoch, Node: Screens and Windows, Next: Variable sized Fonts, Prev: Controlling Screens, Up: Screens 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'.  File: epoch, Node: Variable sized Fonts, Next: Manipulating Screens, Prev: Screens and Windows, Up: Screens 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.  File: epoch, Node: Manipulating Screens, Next: Screen Updating, Prev: Variable sized Fonts, Up: Screens 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 (*Note 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: * Some window managers are not ICCCM compliant and will not handle this correctly. * ICCCM standard says that to uniconify, an `epoch::map-screen' should be used. This doesn't seem to work for many window managers at present. * 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.