Updated for release version: 1.1.0-beta
This is the start page for the ModelGUI developer manual. The proposed beta release (1.0.0-beta) for the mgui project is early 2015. This manual will (in theory) be updated to provide support for the latest release. However, as a general policy all user manual entries will specify the release version for which they were written or updated.
The "developer manual" series is intended for developers of the ModelGUI code. End users should refer to the "user manual".
Table of Contents
|
Introduction
This manual describes the various Java objects which comprise the object model of ModelGUI, and the various semantics underlying these objects. This includes the inheritance structure, the listener models, the initialization routines, and the package organization. The manual attempts to discuss all the relevant details required to work with and extend the ModelGUI project, and to describe the various standards for I/O, GUI functionality, utility classes, resources, etc.
ModelGUI is, in a nutshell, a project intended to implement a generic API for visualizing and processing scientific models, including geometric models and dynamic models. It is also intended to provide implementations for more specialized applications of the generic framework. In this sense, there is no limit to the intended scope of this project, nor is there an intended endpoint. In other words, while individual milestones will specify the direction of the project at any given time, the underlying concept of ModelGUI is to constantly evolve its functionality according to the needs of its contributor base. As an mgui developer, you are invited to participate in this evolution.
The Startup Process
ModelGUI is launched by calling:
InterfaceSession.start(args);
..where args is an array of String arguments, typically passed to a main function. Currently, args will either be empty, or contain one argument, which is the name of the initialization file ("init file") to use; this file must be contained in mgui's "init" subfolder. If no argument is specified this defaults to "mgui.model.init". Init files specify how a session and its environment is to be set up at start-up, by specifying a list of simple commands. They are described in detail here.
Github
ModelGUI was migrated from Launchpad to Github in 2020. Github uses the git version control system to handle concurrent uptakes to its code base. You can use this system to clone the ModelGUI code, and either develop your own fork, or use the pull request framework to propose changes to the owner of the repository. It is recommended that you get acquainted with git and Github if you intend to develop ModelGUI code.
Coding Standards
Because ModelGUI is an open source community process, we have defined a number of coding standards which should be followed when developing the project. Following these standards provides code readability, allows for efficient API documentation, and facilitates the interpretation and extension of code by a community of developers. These standards are described in detail here.
Tutorials
A list of the currently available tutorials is available here.
Java Foundation Classes (Swing)
ModelGUI is built on the Java Foundation Classes (JFC), a.k.a. Swing, GUI engine. This means that all of its windows, panels, and controls are extensions of Swing components, and its event handling is based upon JFC's Event Dispatch Thread. We recommend developers who are not acquainted with Swing check out the excellent tutorials provided by Oracle. This page is a good starting point.
Integrated Development Environments
The use of an integrated development environment (IDE) is very useful for working with a project the size of ModelGUI. IDEs provide many useful development tools, including easy navigation between classes and methods, refactoring, organization of imports, automatic building and compiling, and detection of syntax and other errors. Two of the best free and open source IDEs for Java programming are:
IDEs can also include plugins for checking out and committing code to/from revision control software repositories. ModelGUI is hosted on Launchpad, which is build on the Bazaar versioning system. Plugins exist for Eclipse but currently not for NetBeans. However, Bazaar works quite well as a stand-alone tool, so this is not a critical feature for ModelGUI developers — thus, either IDE should be suitable for ModelGUI development.
The Object Model
The object model in ModelGUI is based on a hierarchy of containers. The top container is a Session, which contains and Environment and a Workspace. The basic hierarchy is depicted below:
Sessions represent the current execution instance of ModelGUI. These are implemented as the static class InterfaceSession.
An Environment specifies all the capabilities and property settings of the current Session. This includes all of its I/O types (see below), its data source drivers, its colour maps, etc. On start up, the Session will load the Environment from a specific ".init" file, specified as a command line argument. If this argument is not specified, a default file is used. Environments are implemented as the static class InterfaceEnvironment.
Workspaces are the top-level container for transient model objects in the Session. This includes shape models, data sources, graphs, plots, and windows. Workspaces are implemented as the class InterfaceWorkspace.
Environment
Interface Objects
An interface object represents a semantic link between the underlying data and the user. All objects in ModelGUI implement this Java interface, which provides a basic set of functions for user-data interactions. Note the semantic difference between "interface" in the mgui sense (i.e., a high-level concept indicating user interaction), and "interface" in the Java sense (i.e., a low-level construct defining a specification which all inheriting classes must implement). Since the idea of an interface is basic to the ModelGUI concept, we have not invented a new term; the downside, of course, is some ambiguity over what the term is referring to. This is important to bear in mind when documenting or describing mgui code.
Interface Shapes
Interface shapes (alias ShapeInts) provide an interface framework for geometric shapes. They add the following basic functionality:
- Attributes
- A set of attributes which determine how a shape is to be rendered in 2D and 3D. Also specify a method called attributeUpdated through which to respond to changes in a ShapeInt's attributes. Attributes are implemented by the Attribute class, and attribute sets are represented by the AttributeList class.
- Tree Nodes
- Specify a method for issuing tree nodes, which include an attribute node, and which can be inserted into an object tree. Shape tree nodes are implemented by the ShapeTreeNode class.
- Shape Listeners
- Maintain a list of ShapeListener objects, which implement a method called shapeUpdated, allowing these objects to respond to modifications to a shape.
- Vertex-wise Data
- Allow the association of primitive values (instances of MguiNumber) with a shape's vertices.
The abstract class InterfaceShape is the base implementation of interface shapes. It currently has two subclasses: Shape2DInt and Shape3DInt.
Shape Sets
Shape sets are collections of interface shapes.
The interface ShapeSet is the basic interface for all shape sets.
Tree Nodes
Tree nodes allow an interface object to be represented as a node on a tree graph, and provide an interface for changing attributes, copying, cutting, pasting, moving, and drag-and-dropping.
The class InterfaceTreeNode is the basic implementation of all tree nodes.
Input/Output (I/O)
Input and output (I/O) operations in ModelGUI are handled through an I/O interface. The purpose of this object is to:
- Provide standard methods for input and output operations
- Provide complementarity between input and output operations. That is, for each input operation that loads data from persistent memory, there is a complementary output operation, which puts the identical data back into persistent memory.
The I/O interface is specified by the Java interface InterfaceIO. The two major subclasses of this interface are FileWriter and FileLoader.
Instances of I/O operations are specified by the user's Environment. This specification includes the extensions associated with the operation, and the specific implementations of InterfaceIO which perform the operation. This specification is implemented in mgui by the class InterfaceIOType.