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