Skip navigation links

Package xal.extension.application

Provides a framework for building document based applications and even multi-document based applications.

See: Description

Package xal.extension.application Description

Provides a framework for building document based applications and even multi-document based applications. The framework provides a common look and feel for your applications and each application inherits a common set of implemented features. The framework employs a standard cross-platform look and feel that should be familiar to most users. The architecture was designed to be both extensible and customizable. This allows applications written today to automatically inherit new application features provided in future framework releases, and it also offers developers quite a bit of freedom to customize their applications. Applications inherit most of the features simply by using the framework as a foundation.

The framework supports two kinds of applications, frame based and desktop based. Frame based applications are applications in which each document is a free native window. Desktop based applications have a single container window for the application and the document windows are displayed and restricted to reside within the contents of the application window. You must decide which kind of application to build before you begin writing your application.

Application Features

Applications built from the XAL framework inherit several features that should be familiar to most users. An XAL application is specifically a document based application. While running an application, one or more documents may be open. Generically a document represents a collection of settings and information provided by the user. The user can save the document to a file and recover the document at a later time by opening the document within the application. Each document is associated with one main window called the "document window" but can also have other associated minor windows. For frame based applications, the document window indicates the application name and the document path in the title bar. For desktop applications, the document indicates only the document path since the application name appears in the title of the application container. If the document has been changed an asterisk appears in the title bar to indicate that the document has unsaved changes. Many applications typically support one kind of document. However, the application framework also supports multi-document applications in which an application may have one or more kinds of documents. In this case, each document may be assigned a specific file type for reading and writing and may have its own window, menubar and toolbar. There are different situations where multi-document applications are appropriate. Examples would be applications that are a collection of related tools and applications that have separate documents for taking data and analyzing data. Multi document application adaptors should probably override the newEmptyDocument() method that takes a string as an argument and it should also enable the "^new_documents_state" menu item and populate the "new_documents_menu" property with the list of document types. When the user selects the New Documents menu they will see the list of document types and upon selecting it the type will be passed to the method as the argument. The method must then instantiate the corresponding document.

An application console is provided to capture and display standard output (black text) and standard error (red text).

A standard menu is provided that includes "File", "Edit", "View", "Window" and "Help" menu items. The "File" menu includes commands for creating new documents, opening, closing and saving documents, opening recent documents, printing a document and quiting the application. The "Edit" menu has commands for simple text editing (e.g. cut, copy, paste and "select all") and for editing preferences. The "View" menu has a command for opening the application console. The "Window" menu has commands for capturing the window as a PNG file, cascading all of the application's open documents, showing or hiding all open documents and bringing an open document to the front. The "Help" menu has commands for viewing application information (name, authors, description, etc.) and for viewing application help. A standard toolbar is also provided for some common commands. Developers can define their own custom commands and modify and add menus and menu items as required. For multi-document applications, each document may define its own menu bar and menu items. By default each document inherits the menu definitions from the application's menu definitions. For desktop based applications this document appears as the main application menu which changes to reflect the selected document. Desktop applications also allow you to optionally specify a menu bar that appears within the document's window.

Creating an Application

The best way to build a new application using our framework is to become familiar with the demo applications and to use the demo applications as starting points for new applications. A demo application is provided for both the frame based and desktop based applications. Every application must provide three classes along with some resources. The main class extends from ApplicationAdaptor for frame based applications and from DesktopApplicationAdaptor for desktop based applications. The adaptor provides application specific information that the framework needs and it also provides hooks for custom control at the application level. The document class extends from XalDocument for frame based applications and XalInternalDocument for desktop based applications. It provides the framework with document specific information and also provides hooks for document control. The document window class extends XalWindow for frame based applications and XalInternalWindow for desktop based applications. It defines the main window for a document. Note that the framework supports the popular "Model-View-Controller" (MVC) paradigm. The window is implemented as the document's view, while the document implements the controller and the developer provides a custom model for the application specific business logic. A reference to the model typically resides in the document class.

The main application class (your custom application adaptor) should implement the main() method as the entry into the application. This method should then call Application.launch() and pass to it as the argument an instance of your main application class. You must implement readableDocumentTypes() to return an array of file extensions of readable files, writableDocumentTypes() to return an array of file extensions of writable files, newEmptyDocument() to return a new instance of your document class, newDocument() that takes a URL as an argument to return a new instace of a document class that represents the file specified by the URL and the developer must implement the method applicationName() to provide a name for the application. Please see the abstract adaptor classes for other methods which you may customize.

Each document class should implement the makeMainWindow() method to return a new instance of your main document window class. Also the saveDocumentAs() method should be implemented to save a document to the specified URL. The application framework allows the developer the freedom to encode their document as they wish. The writableDocumentTypes() method allows each document to specify which file extensions can be written by the document. By default this method simply returns the same array of file types as specified by the application's adaptor. It is only necessary to override this method in the document if your application supports more than one kind of document. A document in a multi-document application may also choose to override the getCustomMenuDefinitionPath() method to call Application.getAdaptor().getPathToResource() with the name of the document's custom menu definition. For desktop based applications, you may also choose to override the getCustomInternalMenuDefinitionPath() method to provide the optional menu bar to be displayed within the document window itself.

The document window class must define the main window used to present the document to the user. The developer is free to layout the window as desired.

Three resources ("About.properties", "Help.html" and "menudef.properties") are typically provided to support the application. By default the application will look for these resources to reside in a folder named "resources" that sits at the same level as the application's adaptor class. You may override the location of resources by specifying the locations in your application's adaptor. Each document may define its own menu definitions and these properties files should be added to the resources folder. The "About" resource contains application information that will be displayed in an About box. The format is a standard Java properties format. The developer should provide this file and the properties to define are: "name", "version", "date", "authors", "organization" and "description". The "authors" entry may contain a comma delimitted list of authors. The "Help" resource is simply user documentation written in standard HTML format. This documentation will be displayed in a help window upon user request. The developer should provide this help file. The "menudef" resource is an optional properties file that defines the menus and toolbar items that differ from the inherited menudef resource. The "menudef" format is a standard Java properties format. The menu bar is defined as a space delimitted list of menu identifiers. A menu label is specified by defining a key as the menu identifier followed by ".label" and then providing the label as text. For example you might define a menu identifier as special and then define special_label = Specialto label the menu as "Special". If the ".label" property is not specified then the item key itself is used as the label. If you specify a ".icon" property then an icon of the specified name from the application's resources is applied to the item. The menu is populated similarly except you append ".menu" to the menu identifier as in special_menu = start pause stop to have the specified menu items. Using a dash, "-", between menu items will insert a menu separator. Prepending a menu item with a carat, "^", indicates that the menu item is itself a menu thus allowing for cascading menus. Prepending an item (menu or toggle bar item) with a "*" indicates that the item is a group of mutually exclusive items. You then must define the group with a list of its items and these items will appear as radio-toggle buttons in the view. You must associate commands with menu items. A command must be an action which fires when the menu item is selected and released, a button model which fires when the menu item is selected or a handler which fires when a menu is selected (e.g. a handler may be used to populate a menu). One specifies an action (or button model) by appending ".action" to the menu item identifier as in "start_action" and then providing as the data a unique command identifier. Similarly you can define a handler by appending ".handler" to a menu item identifier. If you define an action for a menu then it will be used as the default action for menu items that do not explicitly define an action. Custom logic to implement actions and handlers may be defined in any of your application's three foundation classes as appropriate. Your commands may be either application or document specific. See ApplicationAdaptor, XalDocument and XalWindow for the hooks that allow you to define your custom action and handler logic. You may also explicitly menu, menu item or toolbar item states by specifying ".state" after the full name of the item (including any "*" or "^" characters) and specifying the desired state for the item by space delimiting the state attributes. At this time the only attributes are "included" and "excluded". You can use these to explicitly include or exclude an item. In particular the "^new_documents" menu item is excluded by default but a multi document application may wish to include this item to get a menu of possible documents to create.

Application Themes

While this package is suitable for building generic document based applications, themes can be developed to support specific kinds of applications. One such theme has been developed specifically for building XAL applications that allow the user to load an accelerator definition file and select a sequence. @see xal.extension.smf.application
Skip navigation links