Novocode Application Framework - Documentation

• Architectural Overview
• Getting Started
• More Examples

Architectural Overview

NAF consists of the following major components:

• Resource Management (package com.novocode.naf.resource)

  The ResourceManager can load resource files which contain descriptions of ConfigurableObjects. Multiple ResourceLoader implementations can be plugged in to support different description languages.

• XML Resource Loader (package com.novocode.naf.resource.xml)

  The XMLResourceLoader can parse XML resource files. It is always available in newly created ResourceManagers.

• JavaScript Resource Loader (package com.novocode.naf.js)

  The JSResourceLoader uses Mozilla Rhino to execute resource files written in JavaScript. It provides JavaScript methods for defining resources and running NAF applications directly from JavaScript.

• Color Management (package com.novocode.naf.color)

  Colors are represented in NAF by PreciseColor objects which can contain 192-bit RGB and HSV colors. These color objects can be modified with high precision by chains of IColorDecorators.

• Image Management (package com.novocode.naf.gui.image)

  Images in NAF are represented by IManagedImage objects from which SWT Images can be obtained and released. Managed images are created by IImageManagers.

• Custom SWT Controls and JFace Viewers and Providers (packages com.novocode.naf.swt.* and com.novocode.naf.jface.*)

  These classes do not require any other parts of NAF and can be used independently as well.

• Events and Models (packages com.novocode.naf.gui.event and com.novocode.naf.model)

  There are separate model interfaces for reading and modifying different kinds of data (e.g. strings, numbers, window positions) and matching default implementations. Applications can use these default implementations for their view models or implement the model interfaces directly. Actions are sent by IActionSources and received by IActionListeners which are usually implemented directly by applications. Some common action listeners are provided as separate classes (e.g. DisposeWindowActionListener and SetObjectModelValueActionListener).

• GUI Widgets (package com.novocode.naf.gui)

  All widgets inherit from NGWidget (which in turn is a subclass of NGComponent). Some widget classes can create a WindowInstance object which represents a top-level widget (e.g. an SWT Shell or TrayItem) which is managed by NAF.

• Layout Managers (package com.novocode.naf.gui.layout)

  NAF layout managers are subclasses of NGLayout (a subclass of NGComponent). They are wrappers for SWT layout managers which allow layout and layout data properties to be set from NAF resource files (just as NGWidgets are wrappers for SWT widgets).

• Model Persistence (package com.novocode.naf.persist)

  Persister classes implement the IPersister interface. They are used to create XML representations of models and restore model states from these XML representations.

Getting Started

Opening a window with NAF requires only a few lines of Java code (taken from HelloExample.java):

NAFApplication app = new NAFApplication(HelloExample.class);
app.runMainWindow(app.getResourceObject("hello.naf", IWindowInstanceWidget.class), null);
app.dispose();

All NAF applications create one NAFApplication object which manages the windows and runs the SWT event queue. The Class object which is passed to the NAFApplication constructor is used as the base for resolving relative URLs. A tree which describes a window is loaded with app.getResourceObject() from the file hello.naf which must be in the class path in the same package as HelloExample.class. The second argument to getResource() is the expected type of the resource object, in this case IWindowInstanceWidget (a GUI widget which can be used to create a top-level window). getResource() performs a type check, so you get a proper error message (in a NAFException) if the resource object is not what you expect. The returned object is passed directly to app.runMainWindow(). This is a convenience method for simple applications which instantiates the window, opens it and runs the event loop. The method returns when the last managed window has been disposed. Finally all native resource associated with the application are disposed by calling app.dispose().

NAF resource files (*.naf) are XML files which describe GUIs as a tree of Widget elements. Here is the simple hello.naf file used by HelloExample.java:

<?xml version="1.0" encoding="UTF-8"?>
<Shell title="HelloExample" resize="false" xmlns="http://www.novocode.com/namespaces/naf">
    <Label text=" Hello, World ! " font="Arial Black, 0.5in" />
</Shell>

The first line is the usual header which is found in all XML files. The root element is named Shell which translates to the class com.novocode.naf.gui.NGShell. All elements in NAF resource files use the NAF namespace which is declared in the root element with the special xmlns attribute (xmlns="http://www.novocode.com/namespaces/naf"). The other attributes belong to the NGShell widget. Quite obviously, title sets the window's title and resize="false" makes the window non-resizable. The window contains only one widget, a Label (class com.novocode.naf.gui.NGLabel). The label's text is set with the text attribute. The font attribute specifies the font for the label (in this case Arial Black with a height of 0.5 inches). This attribute is available for all widgets but it may be ignored in some cases (e.g. the font specified on a Button will be used when the button is used as a Control but not when it is used as a MenuItem).

Note that no layout has been specified for the Shell in this example, so the default FillLayout will be used. This makes the Shell's client area the size of the Label.

More Examples

The sample applications in the "examples" folder demonstrate most of the features of NAF. Here is an overview of what you can expect from the individual applications:

• com.novocode.naf.example.bars

  Menus, Toolbars and Coolbars.

• com.novocode.naf.example.browser

  A simple web browser. Shows how to use the Browser control and how to connect its models to a typical browser UI.

• com.novocode.naf.example.details

  StringList, CLabelModel and FormLayout's invisibilityPolicy.

• com.novocode.naf.example.dialogs

  All system dialogs and system images.

• com.novocode.naf.example.explorer

  Tree and Table controls, BackgroundTreeContentProvider.

• com.novocode.naf.example.hello

  See above.

• com.novocode.naf.example.ishell

  MDI with the InternalShell and DesktopForm controls. This is a basic SWT application. There are no NAF wrappers for InternalShell yet.

• com.novocode.naf.example.js.hello

  The JavaScript version of the "Hello, World" application. Use the supplied launcher "hello.js.launch" to run it with JSRunner.

• com.novocode.naf.example.js.model

  Model binding in JavaScript. Use "model.js.launch" to run it with JSRunner.

• com.novocode.naf.example.js.test

  A comprehensive JavaScript resource definition which uses most features of the JSResourceLoader.

• com.novocode.naf.example.persist

  Using model persistence to store the state of a GUI.

• com.novocode.naf.example.splash

  A splash screen which is updated from a background thread.

• com.novocode.naf.example.test

  Various controls and features. This is the testbed for most new controls.

• com.novocode.naf.example.thread

  Updating a typical progress dialog from a background thread; Using multiple image versions for a shell image.

• com.novocode.naf.example.xpath

  An XPath explorer which allows you to evaluate XPath expressions on NAF widget trees, using a Tree control and NAFNavigator. Also demonstrates the use of @ModelField and @ActionMethod annotations.

More documentation to follow...