This page is intended to get you started on working with the modelGUI application programming interface (API) to extend the functionality of the project, or simply to start programming your own custom models and interfaces. To do such, you should have a familiarity with coding in general, and the Java programming language in particular (for which there are many good resources - here's a good start). For details on how to get the current code base, or how to get set up with the ModelGUI project, go here.
Table of Contents
|
Coding Standards
Coding standards provide a set of guidelines for how a language or API should (and should NOT) be implemented. For Java itself, standards have been defined, and it's a good idea to get yourself somewhat acquainted with them (see Sun's conventions). The purpose of standards is not (only) because people like to tell other people what to do; they have a real value in projects for which organization is critical, and those which a number of different programmers are likely to extend in the future. Moreover, the organization of Java is such that it provides ways to neatly organize code into hierarchies, in which classes can inherit the functionality of other classes, or can be forced to implement particular methods via interfaces. This object-oriented approach implies that certain standards of coding practises should be enforced, and this applies for the modelGUI API as well.
There's no need to go into detail about coding standards right now; it will suffice to know that they exist, and when you find yourself hacking through an idea to extend the project in a fantastic new way, it's good to know that a reference exists for how to best organize your implementation. Click the title of this section for a list of the suggested coding standards for the modelGUI project.
The Object Model
By "object model", we are referring to an abstract representation of the modelGUI project - independent of its Java implementation - which provides an intuitive understanding of its organization and core concepts. To be abstract then: modelGUI was conceived as a means of providing an interface between a thinker and his thoughts; or, as an interface between an observer and his universe. Such an idea is by no means original in the world of computation - indeed it is the essence of computer-aided design (CAD), which is one of the oldest applications of computers - but we like to think that by approaching the ideology from a philosophical rather than applied perspective, we can develop a new sort of project with many novel avenues of expansion. In scientific terms, the idea is to provide a library of "interface" objects which allow a "scientist" to define his phenomena, digitize them, visualize them, manipulate them, and analyze them. The analysis of scientific data is an enormous problem domain in itself, and includes not only statistical analysis, but forward modelling techniques which can simulate phenomena for comparison with observation.
Such an abstract project is, of course, virtually infinite in scope; so the idea is to provide a workable foundation (an object model) upon which to expand, and this is the crux of the modelGUI project. Practically speaking, it is also quite important to get an appreciation for the object model and its organizing principles (yes, such do exist), before attempting to jump into the grand quest of extending its functionality. Click the title of this section for an overview of the object model.
The API Specification
Of course, a programmer's best friend is the API specification which lists all classes, their functions, their hierarchy, their constructors, etc. Conceptually, the API is a sort of middle man, mediating between the purely conceptual object model, and the purely practical code implementation. Because of the object-oriented design of Java, packages, classes, and methods can be named in ways which reflect their conceptual essence, and thus a good naming convention can be very useful to programmers who are newly acquainted with the project. Java provides an incredibly useful utility called Javadoc, which compiles a set of HTML pages directly from source code, into an intuitive and easily navigable API specification. Another very important coding standard, then, is to religiously document your code so as to best facilitate the Javadoc compilation. How to do this is described here. Click the title of this section to access the API specifications for particular mgui releases (you can also click the menu link at the left of this page to access the API specifications for the most recent release).
The Source Code
While it is quite possible to write your own code extending modelGUI classes without actually having the source files (i.e., by referencing the binary jar files), having access to the actual code can prove quite helpful, particularly if you are just starting out. The source code for mgui is accessible via the Bazaar version control system, and is hosted on the Launchpad site. Probably the best way to work with Launchpad is through the Eclipse integrated development environment (IDE), for which a Bazaar plugin is available. Bazaar "pulls branches" from the code repository; branches are snapshots of the code base which you are interested in altering or simply referencing. True to the metaphor, a Bazaar branch is like a tree branch, starting at one point in a tree's development, but then splitting off and developing on its own. Once (and if) you are ready to commit these changes (or any newly created classes) to the project itself, this can be done through a process called "merging", which you might conceptualize as a branch remerging with the main trunk of a tree (not something a branch normally does, but metaphor has the advantage of being metareal). In fact, in Bazaar and Launchpad (its official online interface), the main development branch is typically referred to as the "trunk". This process is better (although less poetically) explained here.
The License
modelGUI is licensed under the GNU General Public License version 3 (GPLv3). The upshot of this is summarized on the GNU website:
Developers who write software can release it under the terms of the GNU GPL. When they do, it will be free software and stay free software, no matter who changes or distributes the program. We call this copyleft: the software is copyrighted, but instead of using those rights to restrict users like proprietary software does, we use them to ensure that every user has freedom.
This means that any works derived from modelGUI code must inherit the GPLv3 (or later version, at the author's discretion), and therefore also be distributed as open source. When you start programming with modelGUI, it's good to know that you are also agreeing to the terms of this license contract.
Tutorials
There are a number of general categories for programming with modelGUI, including:
- Graphic user interfaces
- Algorithms
- Dynamic models
Following the time-tested tradition of "hello world" tutorials, we will present separate examples for a number of these categories.
- Tutorial 1 - Hello GUI: An introduction to GUI building.
- Tutorial 2 - Hello Objects: How to use some of the common mgui Interface Objects (shapes, data sources, etc.)
- Tutorial 3 - Hello Black Box
- Tutorial 4 - Hello Time Series