This document is obsolete as of the tree reorg which occurred between 0.5.3 and 0.5.4. It will be revised as soon as possible.

AbiWord Source Overview

Jeff Hostetler

jeff@abisource.com

AbiSource, Inc.

1. Introduction

This document gives an overview of the AbiWord source code. It is intended as a high level overview of the organization and the architecture of the AbiWord application and an overview of the cross-application framework that will be used as a basis for other applications in the AbiSuite family. Specific details on each portion of the source code will be given in other documents.

AbiWord is an GUI application written in C++. It currently runs on Unix systems using X11 and the GTK toolkit and on Windows ('95, '98, NT) using the Win32 API. Ports are currently underway for BeOS and for the MacIntosh. A lot of time and effort has been spent to make the source code as cross-platform as possible. As of build 0.3.0, our code is approximately 90% cross-platform (~46.5k cross-platform and ~6.5k platform-specific). We have also spent time to abstract the application framework so that we may share it with other AbiSuite applications. As of build 0.3.0, our code is approximately 48% cross-application (~28.5k cross-application and ~31k AbiWord-specific); this ratio will decrease as we add features to AbiWord, but it is a very good start.

This approach gives us great feature/bug consistency between platforms. It also allows us to use native GUI libraries so that we get a native look-and-feel on each platform. It is our hope that by extensively leveraging cross-platform and cross-application code that we can minimize the effort needed to port the code to another OS or GUI toolkit. It will also allow us to better leverage our QA and documentation efforts.

2. Source Naming Conventions

We have divided the source up into functional modules. Each module is given its own subdirectory in the source tree.

Routines or classes which are considered public (accessible outside the boundaries of a module) are given uppercase prefixes; routines or classes considered module-private are given lowercase prefixes. File and class prefixes are chosen to help reflect the module that contains it.

Each module is responsible for compiling its own source and building the appropriate library. Within a module the the platform-independent code is kept in the /xp directory; the unix-specific code is kept in the /unix directory; and the win32-specific code is kept in the /win directory. If a module contains only platform-independent code, it will only have an /xp directory.

Most of the word-processor-core functionality is 100% cross-platform code.

Most of the user-interface code is part cross-platform and part platform-specific. In most cases, we create base classes in cross-platform code that attempt to do as much as possible in cross-platform code and that also define interfaces for functions that must be platform-specific. Each platform can then derive sub-classes and 'fill in the pieces'.

3. Source Directory Organization

3.1. Cross-Application Framework

abi/src/xap {/xp, /unix, /win } -- These directories contain the cross-application framework. These contain the classes to represent the application-independent portion of the main application, top-level window frames, window lists, command line argument handling, and various application-independent dialogs.

abi/src/ev { /xp, /unix, /win } -- These directories contain the code for the keyboard, mouse, menu, and toolbar event handlers. These provide the mechanism to implement the event-binding mechanism.

abi/src/ver { /xp } -- This directory defines code to internalize compile-time build information into the application. Build date and version and various compiler options are placed in various application variables.

3.2. AbiWord-Specific

abi/wp/ap { /xp, /unix, /win } -- These directories contain the AbiWord-Specific portion of the application-framework. These contain classes derived from the abi/src/xap classes. They contain the state tables used by the event-binding mechanism in abi/src/ev. They also contain the code for application-specific dialogs and the ruler widgets.

abi/wp/fmt { /xp } -- This directory contains the layout engine.

abi/wp/gr { /xp, /unix, /win } -- These directories contain the graphics classes used to draw to the screen. This includes basic drawing primitives as well as font operations.

abi/wp/impexp { /xp } -- This directory contains the Import and Export code used to read and write files in the various formats that we support.

abi/wp/main { /unix, /win } -- These directories contain the main program. These are stub entry points to call to package up the command line arguments and pass control to the application framework class.

abi/wp/ptbl { /xp } -- This directory contains the Piece Table code. This is the (quite complex) data structure used to represent the document in memory with complete undo/redo information.

3.3. Miscellaneous Application-Independent

abi/src/config -- This directory contains the Makefile declarations and rules used to build everything; all of the Makefiles in the source tree simply define their targets and include the .mk files found here. Additionally, the /platforms sub-directory contains platform-specific declarations.

abi/src/other -- This directory contains other (3rd party) source code that we have chosen to incorporate into our source. Currently this directory contains:

/expat --an XML parser from James Clark. (This will be moving out of the /abi/src/other source tree and into a peer of /abi in the near future.)

/spell -- the ISPELL spell-checker.

abi/src/util {/xp, /unix, /win} -- These directories contain various utility routines and simple data structures that we have found useful. Some of these are used to isolate platform-specific behavior (such as string routines, debug messages, and assert macros) and others are use to provide useful data structures (such as hash tables, vectors, and string pools). These directories also contain various data conversion routines.

It is one of our goals to restrict platform-specific #ifdef's to code in the abi/src/util/xp directory.

3.4. Additional Sources Libraries

AbiWord also makes use of the following libraries:

GTK and GLIB (on Unix)

zlib and libpng

4. Class Hierarchies

4.1. Application

The Application class contains all of the application instance data (stuff that could be considered to be global).

AP_App (defined in abi/src/xap/xp/xap_App.h)

AP_UnixApp (defined in abi/src/xap/unix/xap_UnixApp.h)

AP_Win32App (defined in abi/src/xap/win/xap_Win32App.h)

AP_App manages information needed the application as a whole. This includes: application build and version information, the command-line arguments, a list of all open frames (documents and windows), pointers to the tables of possible menu and toolbar actions, pointers to the edit bindings. It also contains numerous abstract virtual methods for platform-specific things.

AP_{Unix,Win32}App manages platform-specific application information. This includes: the Dialog Factory for application-persistent dialogs, the Toolbar Combo Factory, and a handle to the system clipboard.

Only one instance of this class is instantiated.

4.2. Frame

The Frame class contains all of the ...[TO BE CONTINUED...]

5. Flow of Control

main()

Execution begins with the platform-specific main entry point (i.e., main(), WinMain(), or whatever) in /abi/src/wp/main/platform. This code is an ultra-minimal function that is responsible for capturing and command-line arguments and creating an instance of class AP_{Unix,Win32}App.

class AP_{Unix,Win32}App

This class is responsible for initializing any application resources (such as registering window classes, loading toolbar icons, loading font directories, and connecting to the display).

It also creates the first Frame and loads the document named on the command-line or creates a new, untitled document.

[TO BE CONTINUED...]