[mcclim-cvs] CVS mcclim/ESA

[rstrandh]

Update of /project/mcclim/cvsroot/mcclim/ESA
In directory clnet:/tmp/cvs-serv9736

Added Files:
	esa.texi 
Log Message:
Embryonic documentation.  Feel free to add to it.




--- /project/mcclim/cvsroot/mcclim/ESA/esa.texi	2007/11/17 14:00:29	NONE
+++ /project/mcclim/cvsroot/mcclim/ESA/esa.texi	2007/11/17 14:00:29	1.1
* Introduction

ESA is a library that makes it easier to write Emacs-Style
Applications on top of McCLIM.  It supplies a command processor that
is different from the one supplied by standard CLIM, making it
practical to use multi-keystroke command invocation, and invocation of
commands with no keyboard binding possible through M-x. 

ESA assumes that an application that displays a certain number of
buffers in a certain number of windows, and that at all times, there
is a current buffer that is being worked on.

* Basic use of ESA

** Mixin classes

For basic use of the ESA library, the application needs to supply
it with certain functionality.  The basic application document should
be a class that inherits from the class esa-buffer:esa-buffer mixin.
This class supplies functionality for associating the buffer with a
file, to determine whether the buffer has been modified since last
saved, and whether the buffer is read-only. 

Application panes should inherit from the class esa:esa-pane-mixin.

Application frames should inherit from the class esa:esa-frame-mixin.
This class supplies a slot that stores a list of the windows used by
the application, and an accessor esa:windows that can be used by
application code to return or to modify the list of windows used.
Notice that the class definition for the application frame must
explicitly inherit not only from esa-frame-mixin, but also from
standard-application-frame, since the latter is automatically supplied
only if the list of superclasses is empty. 

Applications should supply a method on the generic function
esa:buffers which takes a single argument, the application frame.  It
should return a list of all the application documents (buffers) that
the application is currently manipulating.  

Applications should also supply a method on the generic function
esa:frame-current-buffer, which also take a single argument, the
application frame.  The method should return the current buffer,
i.e. the buffer that is currently being manipulated by the user.  This
might be the buffer that is on display in the window with the current
keyboard focus.  This method is called by functions that require the
current buffer, in particular in order to save the current buffer to
file, or to toggle the read-only flag of the current buffer.  

** The info pane

ESA supplies a class esa:info-pane which is typically used to display
something similar to the status line of Emacs.  It supplies a slot
that contains a main application pane.  This slot can be initialized
with the :initarg :master-pane and can be read using the reader
master-pane.  An application typically supplies a CLIM
display-function for an info pane that displays some data about its 
master pane. 

** The minibuffer pane

ESA supplies a class esa:minibuffer-pane that is used to display
messages to the user of the application, and also to acquire arguments
to commands.  Applications should make sure the application frame
contains an instance of this class, or of a subclass of it.  

** Command tables

Typically, an application using the ESA library will need a number of
CLIM command tables.  ESA supplies a number of such command tables
that the application can inherit from.  

  esa:global-esa-table                               [command table]

This command table contains a few basic commands that every
application using the ESA library will need.

  esa:com-quit                                       [command]

This command quits the application by invoking the CLIM function
FRAME-EXIT on the application frame.  It is included in the
global-esa-table, together with the standard key bindings C-x C-c. 

The global-esa-table also contains the keyboard binding M-x which
invokes the command esa:com-extended-command.  This command prompts
the user for the name of a command in the minibuffer, and executes
that command. 

  esa:keyboard-macro-table                           [command table]

This command table contains three commands, com-start-kbd-macro (C-x
(), com-end-kbd-macro (C-x )) and com-call-last-kbd-macro (C-x e).
Applications that want to use Emacs-style keyboard macros should
include this table in the global application command table. 


* Using the ESA input/output functions