@setfilename ../info/misc
@node Miscellaneous, Index, X11 Primitives, top
@chapter Miscellaneous

Several unrelated features of Epoch are described here.

@menu
* Standard Extensions::         Standard Extensions
* Epoch Version::		Epoch Version
* Packages::			Packages
* Mouse Dragging::		Mouse Dragging
* Screen Naming::		Screen Naming
* Autoraise::			Autoraise
* Multiple Screen Updates::	Multiple Screen Updates
* Screen Pools::  		Screen Pools
* Colors::			Colors
* Change Hooks::		Change Hooks
* Icons::			Icons
* dbx::				dbx
@end menu

@node Standard Extensions, Epoch Version, Miscellaneous, Miscellaneous
@section Standard Extensions
@cindex standard extensions

Epoch contains some extensions of GNU Emacs that are not specifically
related to Epoch.

@defun symbol-buffer-value symbol buffer
Returns the value of @var{symbol} in @var{buffer}, without the expense
of using @code{set-buffer}.
@end defun

@defvar epoch::function-key-mapping t
If this variable is non-@code{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 @code{nil}, then no mapping will be done, and the
key will be ignored.  Keys rebound (@pxref{Other X Stuff},
@code{epoch::rebind-key}) to a non-empty string will not be affected by
this mapping.  If set to @code{t} then keys which have not been rebound
will be mapped to various escape strings, which will be inserted into the
current buffer.
@end defvar

@cindex equal
@defun equal object1 object2
This function returns @code{t} if @var{object1} and @var{object2} have
equal components; @code{nil} otherwise.  If @var{object1} and @var{object2}
are both X Resources, @pxref{X Resources}, then @code{t} is returned if they
are equal regardless of type.
@end defun

@node Epoch Version , Packages, Standard Extensions, Miscellaneous
@section Epoch Version
@cindex epoch version

@defvar epoch::version
This built-in variable will contain the version number of Epoch.  Thus,
@code{(boundp 'epoch::version)} will be  @code{t} on epoch and @code{nil} 
on any other version of GNU Emacs.  You can use this to customize your elisp 
code. 
@end defvar

@node Packages, Mouse Dragging, Epoch Version , Miscellaneous
@section Packages
@cindex lisp packages

Epoch comes with a set of standard elisp files, which provide
functionality to the user.  Beginning with version 3.2, a majority of the
standard files are loaded when Epoch is built.  See @file{ymakefile} and
@file{loadup.el} for which files are loaded.  
Any code which can not be executed except at runtime may be loaded from 
@file{.emacs}, or run via a hook:

@defvar epoch-setup-hook nil
Functions to be executed at runtime, prior to @file{.emacs} being loaded and 
@code{term-setup-hook} and @code{window-setup-hook} have been run.
@end defvar

The following files are included in this version of the Epoch
distribution, in the @code{epoch-lisp} directory:

@table @file
@item dot.emacs
@pindex dot.emacs
Things that should go in your @code{.emacs} file, or @code{(load "dot.emacs")}.
Pretty straight-forward; read the code.

@item epoch.el 
@pindex epoch.el
Installs standard keybindings, variables that you can set to change things,
etc.  This file also defines the default event handler code.  

@item epoch-util.el
@pindex epoch-util.el
Some utility functions used throughout Epoch lisp code.

@item mini-cl.el
@pindex mini-cl.el
Provides some common lisp primitives to Emacs lisp.  This is a subset of the
common lisp package provided by @file{cl.el}.

@item wrapper.el
@pindex wrapper.el
@findex epoch::
Every primitive function introduced into GNU Emacs to support Epoch is
of the form @code{epoch::@var{name}}.  This is like common lisp internal
package symbols, and for each we provide a form without the leading
@code{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 @code{create-screen} determines what to take
from the @code{epoch-mode-alist} before creating the screen with
@code{epoch::x-create-screen}.

@item button.el
@pindex button.el
Extensions to button primitives; primitives for style manipulation.

@item event.el
@pindex event.el
Standard event handler code.

@item mouse.el
@pindex mouse.el
Mouse event handling for epoch. (@xref{Mouse Dragging})

@item motion.el
@pindex motion.el
Handles mouse motion events. Provides dragging and pasting operations.
(@xref{Mouse Dragging})

@item message.el
@pindex message.el
@cindex WM_DELETE_WINDOW
Provides a client message handler.  Provides
a handler for the WM_DELETE_WINDOW client message
from the window manager.

@item property.el
@pindex property.el
Provides the basic property handlers.

@item server.el
@pindex server.el
Modified version of the standard @file{server.el}
program, pops a new window when you use Epoch as a server and call it
through @code{emacsclient}.  Works identically to old @file{server.el}
code, with the exception of this new feature, @i{which is conditional on
Epoch running, so you can use it with all versions of GNU Emacs}.  

@end table

Additional lisp code is provided in the @file{contrib} directory, under
the name of the author.  This code has been verified to be minimally 
compatible with Epoch version 3.2, but is not considered to be part of the
standard distribution.

@node Mouse Dragging, Screen Naming, Packages, Miscellaneous
@subsection Mouse Dragging
@cindex cut and paste
@cindex mouse dragging

We have implemented drag, scrolling drag, cut and paste with the mouse.
The files @file{mouse.el} and @file{motion.el} must be loaded to use
this  feature.

The functionality of buttons with this feature loaded is shown in
following table.

@group
@table @asis
@item Button
Action

@item left-down
Clear drag region, set point

@item left-down and drag
Drag out a region.  Highlight (buffer-local),
place in cut-buffer and kill-ring.  
Set point and mark around highlighted region.

@item middle-down
Paste cut-buffer at the mouse location.  (Use @code{yank} to paste at the
current point.)

@item right-down
Extend highlighted region from a left-down and drag.

@item right-down and drag
Extend highlighted region initially, then
adjust by drag.

@end table
@end group

@cindex scrolling drag
@dfn{Scrolling Drag} means that when the mouse moves out of the window 
with a button down, the scroll continues until the mouse button is raised. 
The speed of the drag can be controlled by setting the following variables:

@defvar horizontal-drag-inc 5
The number of characters the buffer is scrolled horizontally in a single
scroll.
@end defvar

@defvar vertical-drag-inc 2
The number of lines the buffer is scrolled vertically in a single scroll.
@end defvar

Dragged regions are buffer-local, so you can have drags in multiple buffers
simultaneously.  Because point and mark are set around drags, you can use a
combination of mouse drag and Epoch keystrokes to do editing.


@node Screen Naming, Autoraise, Mouse Dragging, Miscellaneous
@subsection Screen Naming
@cindex screen naming

@defvar include-system-name
Set the variable @code{include-system-name} to @code{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 @code{foo} selected on machine
@code{bar} would appear @code{foo @@ bar}.
@end defvar


@node Autoraise, Multiple Screen Updates, Screen Naming, Miscellaneous
@subsection Autoraise

@cindex screen autoraise
@defvar auto-raise-screen
Setting the variable @code{auto-raise-screen} to @code{t} causes screens
to raise when they are selected with @code{select-screen}.  Overloading
this variable to a value besides @code{nil} and @code{t} will prevent the
minibuffer from raising on @code{x-select-screen}.
@end defvar


@node Multiple Screen Updates, Screen Pools, Autoraise, Miscellaneous
@subsection Multiple Screen Updates
@cindex multiple screen updates

The @file{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
@code{epoch-mode-alist} to set things up so that only screens created
for buffers with mode @code{shell-mode} would be updated.  @xref{Screen
Updating} for more information.

@node Screen Pools, Colors, Multiple Screen Updates, Miscellaneous
@section Screen Pools

@cindex screen pools
@pindex scr-pool.el
The package in @file{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 wants a limit on the number 
of screens in use to prevent excessive clutter or resource consumption.

@menu
* Screen Pool Basics::          Basic Description of Screen Pools
* Screen Pool Functions::       Functional Interface to Screen Pools
@end menu

@node Screen Pool Basics, Screen Pool Functions, Screen Pools, Screen Pools
@subsection Screen Pool Basics

A screen pool consists of
@table @var
@item Size
The maximum number of screens allowed in the pool. When this many
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.

@item Create-Function
This is a function that is used to create a new screen when needed,
either because there are less than @var{size} screens in the pool, or
one of the screens in the pool is dead. This function is optional, and
if missing @code{create-screen} is used.  No arguments are passed to this
function.

@item 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.  

@end table

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.

@node Screen Pool Functions, , Screen Pool Basics, Screen Pools
@subsection Screen Pool Functions

These are the functions provided by the Screen Pool package.

@defun pool:create size &optional create-function cleanup-function
Creates and returns a screen pool with no screens in it.
@end defun

@defun pool:delete pool
Deletes all the screens in the @var{pool} using @code{delete-screen}. The
cleanup-function, if any, is called on each screen first.
@end defun

@defun pool:get-screen pool
Returns a screen from the @var{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.
@end defun

@defun pool:get-screen-with-buffer pool buffer
Similar to @code{pool:get-screen}, except that if one of the screens in
the pool is already displaying @var{buffer}, it is returned instead of
creating a new screen or recycling another screen, and the
cleanup-function is not called.
@end defun

@defun pool:get-shrink-wrapped-screen pool buffer limits
Similar to @code{pool:get-screen}. If @var{buffer} is displayed on any
screen in the @var{pool}, then that screen is used, otherwise a screen
selected as in @code{pool:get-screen} is used. This screen is selected,
all but one window is deleted, and that window is set to display
@var{buffer}. The screen is then shrunk to fit the buffer, in
height and width, up to @var{limits}. @var{limits} should be a list of 4
numbers, of the form @code{(min-width, max-width, min-height,
max-height)}.
@end defun

@defun pool:mark-screen pool screen
Mark @var{screen} as being the most recently used @var{screen} in the
@var{pool}.  This means it will be the last to be recycled.
@end defun

@defun pool:unmark-screen pool screen
Mark @var{screen} as being the least recently used @var{screen} in the
@var{pool}. This means it will be the first screen to be recycled.
@end defun

@node Colors, Change Hooks, Screen Pools, Miscellaneous
@section Colors
@cindex colors
@cindex red green blue components
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 @code{65535}
@code{(==2^16-1)} is the maximum for the display device, and 0 is off.  Epoch
stores colors as X Resources of type X-Cardinal @xref{X Resources}.

@defun 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
@code{2} indicates monochrome, a larger number indicates a grey-scale or
color display.
@end defun

@defun epoch::get-color name
Given a color name, this function converts the name into an X-Cardinal
resource (a pixel value).
@end defun


@node Change Hooks, Icons, Colors, Miscellaneous
@section Change Hooks
@cindex 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.

@vindex HAVE_LEIF
These variables are only defined if you compile Epoch with
HAVE_LEIF defined in the @file{config.h} file.

@defvar 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 @code{before-change-function}, changes to any buffers do
not cause calls to any @code{before-change-function} or
@code{after-change-function}.
@end defvar

@defvar 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 @code{0} if none.

While executing the @code{after-change-function}, changes to any buffers do
not cause calls to any @code{before-change-function} or
@code{after-change-function}.


@example
(defun after-change (pos inspos dellen) 
  "Called after each change"
  (condition-case err
      (progn
;      (garbage-collect)
       (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)
@end example

@end defvar


@node Icons, dbx, Change Hooks, Miscellaneous
@section Icons
@vindex WM_ICON_NAME
You can set the names of icons for screens (accessible through the property
@code{WM_ICON_NAME} using the global @code{.Xdefaults}, the screen property
list, or the function @code{epoch::icon-name}.)

@defun epoch::icon-name &optional value screen
If value is @code{nil}, return current icon name.  Otherwise set icon name to
value.  If screen is @code{nil}, use current screen.
@end defun

@node dbx,  , Icons, Miscellaneous
@section dbx

@defun 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.
@end defun

