Overview

At it's root, most windowing user interfaces use an event loop for managing interactions with the user. This event loop often polls for events and dispatch events to other parts of the application.

The Application class XGAppCore encapsulates this functionality, and provides a portable way of hiding the details of how an event loop operates. This chunk of code also encapsulates how windows, documents and forms interact with this event loop and define the higher level application functionality.

The Event Loop

The event loop is encapsulated by the XGAppCore class. This maintains the core event loop, encapsulating the functionality of the Macintosh event loop, the Windows event loop and the X library's event loop

### Expand on above

There are two different application models supported by the YAAF libraries. A "multiple window application" is a traditional editor or windowing application containing several windows and potentially able to open multiple files. A "single window application" is a control panel or any application that relies on only one window; when the window is closed, the application is shut down.

Variations on the multiple window application exist on Microsoft Windows: either the application can be operated as an MDI style application, or an SDI application. On X a multiple window application runs as an SDI-like application. And on the Macintosh, it operates more like an MDI style application. When a multiple window application operates as an SDI-style application, the last closed window shuts the application down. For maximal portability, you should write your multiple window application as if it were an SDI-style application: open an initial empty window if the application is started with no command-line arguments, and be prepared to terminate when the last window is closed.

Windows

A "window" is a top-level object, the full window that is manipulated by users. This differs from X and from Windows, which uses "child windows" which can be contained inside a top level view. That functionality (of a "child window") is performed by views, described in View Management.

Windows are like containers, holding several different views which comprise the interface presented in that window. As a window is a focus and a dispatch object, XGWindow objects receive events from the children views it contains.

###

Designing Windows

The model for constructing an application using YAAF is similar to the model used by Visual Basic with XGView derived views defining the "controls", glued together by higher level code. This helps make applications built using YAAF easily reusable by taking apart and putting together view objects together as they are needed.

There are three different options for stringing those views together inside the XGWindow "container".

First, you can derive your own window from the XGWindow class, and include the code for tying together the different views inside of your own XGWindow class. (This is possible because all control views dispatch their messages to themselves, and when unhandled, these events wind up at the XGWindow class.) You must also then register your class with the XGWindowFactory, using the RegisterWindow macros.

While this is the simplest way of handling creating a window object, this has the disadvantage of having to create and wire up a separate window class object for each potential window in your application. Also, by placing some of the initialization and editing code in your window, the code can become somewhat "crowded."

Second, you could create a "form" object with the code for tying together the different views and associate it with the XGWindow class. The XGForm object is specifically designed to handle events sent from the XGWindow object and the views inside it, and is in fact functionally equivalent to a Visual Basic "form" which handles events and ties together different VB controls. This has the advantage of providing a known metaphore for application construction, and keeps the code for gluing and connecting the various views together in a separate logical module. Further, as a form can handle more than one window object, you can create a single form global object and handle all your editing windows as events occur.

One future goal of mine is to replicate some of the functionality of Visual Basic within the YAAF framework. This would be a relatively straightforward process: the interpreter engine would be a descendant of the XGForm object (where TMyForm is on the diagram above), and dispatch events that are received from the various views to the form object. Provide a few accessors for getting the views that are contained, and provide a mechanism for creating a "View DLL" which is similar to a Visual Basic control, and that's most of the hard stuff.

Both of the above cases don't take into account the concept of a "document." Fundamentally, a "document" object mediates access between a file and the window which edits the contents of that file. In the third case you can use the XGDocument class (you don't have to, but it helps) to create the concept of a "document" (a database which gives information about the contents of a file), and access that document from the window via the form object.

The XGDocument model (shown above) inserts itself above the windows that contain that document. This allows the document object, rather than the window that contains the document, to handle operations such as "saving" and "reverting." The document object also sends messages to the XGWindow (which are optionally passed to the associated form) when the document is renamed; this gives the window the opportunity to rename itself.

As the XGDocument object inserts itself between the window and the application, it's possible to mix more than of the various paradigms above. For example, you could build a XGWindow custom object which handles some messages, and sends the rest to the form object, while the document handles document-related events.

### Add section on how to open such a window.

User Specified Routines

> StartApplication()

> > This routine must be provided by your code, and is considered the "starting point" or the "main" of a YAAF application. This constructs the application, the application's window (if necessary) and returns a pointer to the newly constructed application object.

Classes

> XGAppCore

> > The core application event engine. When creating your application, create it as a descendant of either the XGAppMultiWindow or XGAppSingleWindow classes; each contain the proper event handling routines for providing a control panel style application or a multiple window editor application.

> XGAppMultiWindow

> > The application event loop engine for supporting multiple window applications.

> XGAppSingleWindow

> > The application event loop engine for supporting single window applications.

> XGWindow

> > The window class that encapsulates a top-level window.

> XGPopWindow

> > The class for support pop-up windows. Pop-up windows are used for supporting pop-up menus.

> XGWindowFactory

> > The window factory class; this is used for registering and creating windows (and their contained views).

> XGWindowTemplate

> > A template class which is used in conjunction with the RegisterWindowID or RegisterWindow macros to create an entry for building a particular window type using the XGWindowFactory class.

> XGForm

> > The form object. This is a high level object which handles the events and initialization sequence for tying togther view-based controls inside of a window.

> XGDocument

> > The document object. This mediates access to a file, providing the basis for developing document save and load, as well as a common database used by views and windows for editing.

Macros

> RegisterWindow

> > Registers a window class.

> RegisterWindowID

> > Registers a window class with a different window type.