Story Library
Home   Hierarchy   Classes   Files   Functions   Modules   Pages  

Factories and Strategies Overview

 The text engine uses few globals. Instead almost everything is owned by an instance of Story::CRoot. In a sense, CRoot is the engine. As well as the collections of stories and layouts, the root stores the style sheet and similar widely used objects, including the factory Story::CFactory.

Subclassing

You can subclass most of the engine's core classes and make the engine use your class instead of its own. The engine makes new objects by cloning existing ones or by calling a factory method. The most important factory is Story::CFactory. By subclassing CFactory you can control which classes the engine uses for its objects. This is a powerful way of customizing the engine.

For example, to substitute a special version of Story::CSelection, you would:

  1. Implement the customised class as a subclass of CSelection, for example using CPagePlusSelection : public Story::CSelection {.
  2. Write a subclass of Story::CFactory, for example using CPagePlusFactory : public Story::CFactory {
  3. Override the NewSelection() method to return new CPagePlusSelection;.
The engine uses another factory for creating glyphs, Story::CGlyphFactory. A single glyph factory is shared between all roots. You can substitute a new factory using Story::CGlyphFactory::SetInstance() (although you probably won't need to).

The engine uses Story::CImporter and Story::CExporter to handle import and export file formats. You don't need to subclass these but you may want to add your own formats to the ones they know about. Story::CControllerKey is an object that creates many instances of CCmd for user commands.

Client Data

Most container objects will let you associate your own data with them, without you having to subclass them or use factories. They use a protocol declared in Story::CClientData instead. This stores a pointer to an arbitrary application-defined object, which you store by using SetClientData and get back by using GetClientData.

Your client data object must inherit from CObject, so that it has a virtual destructor, MFC's runtime class protocol and its serialization protocol. Other than storing the pointer, and optionally deleting it and serializing it to archives, the engine classes don't use the client data object in any way.

Strategies

Some classes are designed to be used with delegation. They store an application-defined Strategy object and forward key messages to it. Delegation is usually better than inheritance where it can be used, because it results in less coupling between your classes and the engine. Delegation won't let you override methods in the engine class, though, so it can't always be used.

The Story::CObserver interface is used by the engine to notify the application of changes to the story. This is how the application finds out that a story needs to be erased or redrawn, for example. See Change Notifications for more details.

The Story::CFrame interface is used by Story::CColumn to find out about its wider context. It expects to be placed in some application-defined multi-column page or frame, and CFrame represents that object to the engine. See Layout Overview for more details.

The Story::CHyphenator interface is used (by Story::CLayout) to decide where in a word soft hyphens go, when a line is being broken to fit a measure. If you want to use auto-hyphenation you will need to provide a subclass that understands the hyphenation rules of the natural language you are using.

The Story::CSpell interface is used to check words for spelling mistakes. The engine will use it to check spelling interactively and as a background task, and apply a special attribute to mis-spelt words. Your UI can then underline spelling mistakes in red.

The Story::CMailMergeProvider interface is used by the Story::CGlyphMerge powerfield glyph to access fields in a database. These can be inserted into the text. You would provide a subclass of CMailMergeProvider which adapts to the database you want to use.

See also Factory and Strategy Classes, Notifications and Events Overview.

Serif Story Documentation.
This content last built on 30 Oct 2003.