Building a YAAF Application: Step By Step

This section is a simple step by step describing the steps for constructing a YAAF application. Most YAAF applications are built in a similar fashion, though it is possible to take various shortcuts or use different techniques.

What is a YAAF Application?

In short, the YAAF framework only covers the visual elements of an application: how windows appear, how menus are handled, how controls are drawn. This is to simplify application development. By keeping it simple, the YAAF framework simplifies creating portable applications which can operate on a variety of platforms.

The elements of a YAAF application are the application event loop, windows, views (which are the components which make a window and can include controls), and menus. Other elements built on top of this are YAAF controls and dialog boxes.

There are two types of YAAF applications: the 'single window' application (which includes control panels, single window games, and simple editors), and 'multiple window' applications (which include editors). The primary difference between the two is that when the 'single window' application's main window closes, the application exits. On the other hand, the multiple window application may or may not quit when all of it's windows are closed; see "Application Management" for more information.

User interface elements of the application are built using the XGView class. This class defines a rectangular region of a window, and can be used for creating controls (such as buttons, sliders, edit fields and the like), as well as providing higher level grouping of other views and custom editing or display objects.

These user interface views are then assembled into a window, using the XGWindow class. There are several techniques for tying the views together, depending on the complexity and needs of the application. These include subclassing the XGWindow class, subclassing the XGForm class and associating it with the window, and creating a document using the XGDocument class. For more information, see "Application Management."

Steps To Creating a YAAF Application

> Step 1: Decide the type of application you are building: control panel or multiple window editor style. And declare a custom application class descendant from the appropriate YAAF class.

The two classes you can descend your application class (called TMyApp in this example) from are the XGAppSingleWindow (for single window applications) and XGAppMultiWindow (for multiple window applications). Each provide roughly the same public functionality, so declaring a class based from either is relatively simple. And as both are descendant in turn from the XGAppCore class, you can use the same methods.

The XGAppCore class is descendant from the XGDispatch class, and is in fact the root of the event dispatch tree. This is where global events (such as "New Window" or "Page Setup") should be handled.

The constructor of your application class should contain the system dependant initializations, such as initializing services which your application depends on. And the destructor should release those resources that you can release.

> Step 2: Declare the routine StartApplication() in your main source file and perform the appropriate initialization for your application.

The StartApplication() routine is declared in <XApplication.h> as:

>     extern XGAppCore *StartApplication(void);

If you are declaring a multiple window application (that is, if TMyApp is descendant from the XGAppMultiWindow class), you only need to create your application class. Thus, you can write:

>     /* StartApplication
>      *
>      *  Where my application starts. Just build my app and
>      *  return.
>      */

>     XGAppCore *StartApplication(void)
>     {
>         return new TMyApp;
>     }

After the StartApplication() routine is called, the returned pointer's "Run" method is called, and the event loop is executed. There are two events that you will receive, depending on if the application is started up with or without any command line arguments. It is at that point when you should open an "empty" editor window if your application is started without arguments.

For an XGAppSingleWindow based application, you have to also open your main window. If you don't, you will get an "abort" exception. So you would write:

>     /* StartApplication
>      *
>      *  Where my application starts. Just build my app and
>      *  return.
>      */

>     XGAppCore *StartApplication(void)
>     {
>         TMyApp *myApp = new TMyApp;
>         XGWindowFactory::CreateFromResource(KMyWindowResource);
>         return myApp;
>     }

The additional step is to create the window. That is done here by using the XGWindowFactory's CreateFromResource method with the resource ID of the 'VRes' resource that defines the layout of your main window.

> Step 3: Declare the custom views for the custom controls that you will need.

Just about every application you will build will have it's own custom views. Custom views are regions of the window which draw graphics specific to your application. To do this, you would create a new class based on XGView. And in the constructor of your application, you would call the appropriate registration macros.

Suppose you needed two custom views, called TMyView1 and TMyView2. You would then declare those views as outlined in the View Management section. And in your application's constructor, you would write:

>     TMyApp::TMyApp()
>     {
>         ...other stuff...
>         RegisterView(TMyView1);
>         RegisterView(TMyView2);
>         ...other stuff..
>     }

Methods that would need to be written for your custom views depend on the type of view you are writing. A view which only needs to display information, such as a status line, would only need to override the XGView::DoDrawView method. Views which accept mouse clicks would also need to override the XGView::DoMouseDown, DoMouseMove and DoMouseUp methods.

### Expand on this theme

> Step 4: Glue the elements of the custom views together in an XGWindow object.

There are three ways that messages can be handled.

### Expand on this theme.