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.

---