Gwp Internals

Table of Contents

Documents And Slabs

The class WPDocument contains:

Slabs

A slab tree is a tree structure with Slab instances as its nodes.

Every Slab has a size, a parent, a style, and a size policy. Sizes are represented as 4 values (left, up, right, down).

 ---------------------
 |         ^         |
 |        up         |
 |         |         |
 |<--left--X--right->|
 |         |         |
 |       down        |
 |         V         |
 ---------------------

The "X" is the actual location of a slab. The space it takes up within the document is determined by its size variables.

A ContSlab is a slab which keeps track of and arranges other Slabs. A slab's parent is either another slab (a ContSlab) or NULL (in the case of the root slab). The root slab is a ContSlab which represtents the entire document. Its children are ContSlabs which represent pages. Children of pages are lines. Children of lines are words or images or spaces or line-breaks. One word is kept in each WordSlab. One image is kept in each ImageSlab. A LBTSlab is a line-break, and STSlabs are other whitespace (currently just space characters, but I think tabs will go in here). None of ImageSlab, LBTSlab, STSlab, or WordSlab can contain other slabs. Every Slab has a pointer to a style. If a style is changed, every slab which points to that style will change. If a slab is pointed at a different style, only that slab will change.

The Slab tree is currently a uniform depth of 4.

doc
page page
line line line
word word space word space etc

Some of the code counts on the tree being full (of uniform depth). This will have to be changed before things like tables are possible. I would like the tree to be ragged.

Container slabs can arrange children in a non-overlapping line starting at some point and going in any of the 4 directions. A page arranges its children from top to bottom. A line arranges its children from left to right (or right to left if you're composing in Arabic).

A Slab has a size policy for its X axis and one for its y axis. A size policy can be any of fixed, by-children, or by-parent. If the policy is fixed, the slab wont change its size along that axis. If the policy is by-children, the slab will pack its children together and be as small as possible (along that axis). If the policy is by-parent, the slab will take on the size of its parent (along that axis). Size by parent is largely untested right now. A line's X axis is fixed, and its Y axis is size-by-children. This means that a line will always stay the same width, but it's height will depend on it's children. The line's up value will be the maximum up value of its children's up values, and its down value will be the maximum of its children's down values

  -----line---------------------------------------- <-- ascent
  |                           ---------           |   |
  |   ---------   ---------   |       |           |   |
  |   |  word |   |  word |   |  word |           |   |
  |-- |-------|---|------ |-- --------------------| <--- base line
  |   ---------                                   |   |
  ------------------------------------------------- <-- descent
    

A word's up and down values are determined by the ascent and descent of its font. A page's Y axis is fixed, and its X axis is size-by-children, so it gets its width from the widest line it contains.

Note that it doesn't make sense of have a container slab be size-by-children if any of its children are size-by-parent (along the same axis); Such an arangement will probably cause crashes.

If a ContSlab's size is fixed along an axis, it can align its children is any of three positions: low, center, or high. If the ContSlab's direction is left to right and the its alignment is low, the children will be moved to the left. If the alignment is high, they will be moved to the right. If the alignment is center, they will be centered within the ContSlab. If the container's size policy is size-by-children, the alignment is ignored.

Spots

A Spot is a slab and an index into the slab. A document keeps a list of spots. Spots are used to keep track of places in the document (cursors, hightlighted regions, etc). Spots are garenteed to be valid, despite changes in the document. If a spot's slab gets deleted, the spot will be moved to a neighboring slab. If a spot is within a word and characters are inserted into the word to the left of the spot, the spot's index will be incremented. Plugins should try to work with spots rather than slabs, because the user may be able to make changes to the document while a plugin is running. Plugins should not create their own spots; they should ask the document to create and return them.

Views

A document can have several views open on it. A change in the document might cause visual updates in more than one view. The list of views must be passed to any Slab method that might cause a visual change.

Style Manager

A document's style manager keeps track of all the styles in its document. It allows access to these styles by name (char *'s). The styles are kept in groups. Currently, the groups are named "document", "page", "line", and "word". Styles which are intended for words are kept in the "word" group, those intended for lines in the "line" group, etc. I expect this scheme to change.


Plugins

Sun Feb 8 11:49:16 PST 1998

Scanning for plugins is started from wp.C: WpPluginMgr::thePluginMgr()->refreshPlugins(); These directories are searched:

  1. $GWP_PLUGIN_PATH
  2. ~/.gwp/plugins/
  3. <exec_prefix>/lib/gwp/plugins/

Each shared library found is searched for a function called "WPPlugin_GetPluginVersion". If the function is found, a bridge is created for the plugin. The bridge is asked for its name and the plugins_hash table is checked for that name. The new bridge is then deleted or inserted into plugins_hash (a global hash table).

A plugin bridge contains a pointer to a plugin and the plugin's vtables. A vtable is a list of pointers to functions located inside of the plugin. Every plugin is one of 4 types, and a different type of bridge is created for each one. Each Plugin has two types of vtables -- a VTABLE_BASE and another type which is specific to the type of plugin.

The base vtable contains pointers to WPPlugin_GetPluginVersion and WPPlugin_FillInVTable (note that there is currently no need to query for a base vtable, since you know exactly what's in it, ahead of time). WPPlugin_GetPluginVersion is used to confirm that the shared library is a plugin. WPPlugin_FillInVTable is used to get the type-specific vtable. Here are the plugin bridges and their type-specific vtables.

WpImagePluginBridge's VTABLE_IMAGE

    char *getMimeType();
    char *getFileExtensions();
    int loadAndDraw(char *path, WPDocument *document);
    

WpDocPluginBridge's VTABLE_DOC

    void operateOnDocument(WPDocument *doc);
    void operateOnSelection(WPDocument *doc, Spot endpoint1, Spot endpoint2);
    

WpIOPluginBridge's VTABLE_IO

    char *getMimeType();
    char *getFileExtensions();
    int canSave();
    int canLoad();
    int saveDocument(char *path, WPDocument *doc);
    int loadDocument(char *path, WPDocument *doc);
    

WpToolPluginBridge's VTABLE_TOOL (?)

    none (yet)
    

WpIOPluginBridges get entries added to the <File> menu's open and save dialogs, depending on their responses to canSave and canLoad. WpImagePluginBridges get entries added to the <Insert><Image> dialog. WpDocPluginBridges get entries under the <Tools> menu. WpToolPlugins are vaporware.

There are plans to allow scheme plugins, but they are also vaporware. Last modified: Mon Feb 16 13:22:46 PST 1998