It's difficult to write a document
that adequately introduces a program to new developers. The following
doesn't try to explain all of Seashore but rather aims to give an
overview of how Seashore works.
Seashore classes can be divided into two
categories, document classes and application classes.
The instances of document classes, belong to a particular document. For
example, a particular layer is unique to a particular document so the
SeaLayer class is a document class. The
instances of application classes are shared by all documents. For
example, only one brush selection utility is needed for any number of
documents so the
BrushUtility
class is an application class.
Document classes are associated with the SeaDocument.nib file and
application classes are associated with the MainMenu.nib file.
Document Classes
The most important document class is the
SeaDocument
class. It has a method "contents" which provides access to an
instance of the
SeaContent
class. This class describes all of the document's attributes and keeps
an array of
SeaLayers
- each of which represents a single layer of the document.
To find the width of a particular document you might use the
syntax "[[document contents] width]" and to find the bitmap of the
active layer you might use "[[[document contents] activeLayer] data]".
The various import formats of Seashore are implemented by subclassing
the
SeaContent
and
SeaLayer
classes. See the
CocoaContent
and
CocoaLayer classes for
examples of this.
SeaWhiteboard
takes the contents of the document and with the help of
SeaCompositor
produces a single image representing the document. This image is then
displayed to the user by an instance of the
SeaView
class.
The whiteboard not only composites the layer bitmaps together but also
composites what is known as an overlay on top of the active layer. The
overlay is the same size and has the same samples per pixel as the
active layer. It is what is adjusted when you draw on the canvas with
the paint brush. For example, when you first press the mouse button the
BrushTool
sets the overlay's opacity using "[[document whiteboard]
setOverlayOpacity:255]". As you drag your mouse across the document
BrushTool makes additional changes
directly to the overlay's bitmap (obtained using
"[[document
whiteboard] overlay]") and calls "[[document helpers]
overlayChanged:whichRect]" to ensure the changes are visible to the
user. Finally once the mouse button is released
BrushTool applies the overlay to the
layer and then clears it for reuse by calling "[[document helpers]
applyOverlay]". The advantage of using the overlay is that the process
is largely the
same regardless of what channels are selected. Furthermore, undoing
is much simpler and the overlay allows colours with alpha
channels to be correctly plotted.
In the previous two paragraphs "[document helpers]" was referred to
quite a bit. This syntax returns the document's instance of the
SeaHelpers class. The
SeaHelpers class is a new addition to
Seashore which means rather than
BrushTool
calling several different classes with each update, such calls are
handled by a single method in the
SeaHelpers
class. This makes the code easier to read, use and adjust.
The behaviour of all of Seashore's tools (with the exception of those
built into
SeaView)
are guided by classes which inherit from the
AbstractTool class. They
are all document classes and can be accessed by calling "[document
tools]" which will return the document's instance of the
SeaTools class.
The final set of noteworthy document classes are the exporters. All of
Seashore's exporters inherit from the
AbstractExporter class. To
develop an
understanding of exporters it is best to look at a simple exporter such
as the
TIFFExporter.
Application Classes
If you wish to add a menu item to Seashore then the
SeaProxy
class may be of interest to you. It acts as a mediator between various
menu items and the active document. These menu items are connected to
methods of the
SeaProxy class which
then forwards their requests to the active document.
SeaProxy
also takes on the responsibility of disabling and enabling such menu
items.
Another important application class is the
SeaController class that provides
access to the shared instances of a number of other classes. The most
important of which is the
UtilitiesManager
that allows you to access all of Seashore's utilities.
In Seashore a utility is basically something that sits in a floating
window separate from the document window. The most important utility is
probably the
PegasusUtility
which allows you to select the active layer and channel. There is also
a brush selection utility (called
BrushUtility),
a texture selection
utility (called
TextureUtility)
and even a cursor information utility (called
InfoUtility). The current tool and
currently used colours are typically selected by the
ToolboxUtility and the options of
the current tool are displayed by the
OptionsUtility.
It should be noted, that the
TextureUtility
keeps an array of
SeaTextures,
each of which represents a single Seashore texture. Likewise the
BrushUtility keeps an array of
SeaBrushes. These are passed to the
document as is necessary. The
OptionsUtility
also allows access to the options of any tool each of which inherits
from the
AbstractOptions
class.
Finally a number of operations are implemented by application classes,
specifically scaling (by the
SeaScale
class),
margin adjustment (by the
SeaMargins
class)
and resolution adjustment (by
SeaResolution
class).
For further information please don't
hesitate to post to Seashore's Google Group.