Package xal.extension.application
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
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
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 = Special
to 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
-
ClassDescriptionAbstractApplicationAdaptor is the abstract superclass of the desktop and frame based application adaptors.ActionFactory is a factory class with methods that can instantiate actions for use in menus and the toolbar.The Application class handles defines the core of an application.ApplicationAdaptor is the abstract superclass of the custom applicaton adaptors each of which acts as a delegate for its corresponding application.Interface which listeners of application events must implement.ApplicationStatus is an interface used in remote access to advertise application status.ApplicationStatusService handles application status queries on behalf of the running application instance.The Commander manages the commands (actions and menu handlers) that are used in toolbars, menu items and menus.provides a default implementation of the XAL windowApplication subclass for JDesktopPane based applications.DesktopApplicationAdaptor is the abstract superclass of the custom application adaptors each of which acts as a delegate for its corresponding desktop application.Application subclass for JFrame based applications.Utility class providing convenience methods for use in the application framework.The base class for custom documents.Interface for common document event listeners.Interface of XAL windows.The base class for custom documents.Interface for document event handlers.The base class for custom windows that are the main windows for documents.The base class for custom windows that are the main windows for documents.