Using 'capsis.kernel' and 'capsis.commongui' in other applications

fc - 4.5.2010

The two packages are bundled in a capsis-kernel.jar file distributed under the terms of the LGPL licence. They can be used to build new application making a given scene 'grow' with a given model. They both rely on the jeeb-util.jar file, also LGPL.

The capsis.kernel package

The package contains the main organisational classes of Capsis.

The user implements his model in a module, overiding the GModel class. The module also contains descriptions of the InitialParameters (set at initialisation time) and the EvolutionParameters (the stop criterium during an evolution). The model class implements the main processEvolution() method with the evolution loop from one given Step to a target EvolutionParameters instance (e.g. 10 years, 3 months… depending of the moel and its time step).

The Session contains Projects, each containing at least a root Step. The Step carries a GScene instance, to be overriden in the user module to describe the user scene. In capsis, this scene is a plantation or a natural forest possibly containing tree objects. In Xplo, the Scene is an ArchiTree, i.e. an architectural description of a single plant or tree.

In both application, the model class says how the scene grows : with a forest growth model within Capsis and with a structure function model (for example) within Xplo.

The capsis.commongui package

The applications based on the capsis.kernel may use common gui components to manage a given set of basic actions. Two main packages are provided for this purpose.

The command package

Standards commands

capsis.commongui.command proposes a set of basic commands to manage projects. All the applications running a capsis kernel will have to manage the Session, the Projects, trigger evolution processes… The main commands are provided for this and can directly be added in the menus of the hosting application:

Step level commands are also provided:

And optional commands, mainly for the session level management:

CommandManager

The package also contain a convenient class to manage the commands: the CommandManager. It must be constructed during the gui initialisation of the hosting application (e.g. in the MainFrame constructor) by calling its constructor once. Then, the single instance of the CommandManager can be retrieved from anywhere by CommandManager.getInstance () (like a Singleton pattern).

The CommandManager knows all the capsis.commongui commands and proposes a method to get them simply: getCommand (Class commandClass). Thus, to add the project commands in the hosting application menu, just write: 

// project menu is a JMenu
projectMenu.add(CommandManager.getInstance ().getCommand (NewProject.class));
projectMenu.add(CommandManager.getInstance ().getCommand (OpenProject.class));
projectMenu.add(CommandManager.getInstance ().getCommand (CloseProject.class));
...

To add the same commands in a toolbar: 

// toolBar is a JToolbar
toolBar.add (CommandManager.getInstance ().getCommand (NewProject.class));
toolBar.add (CommandManager.getInstance ().getCommand (OpenProject.class));
toolBar.addSeparator ();
toolBar.add (CommandManager.getInstance ().getCommand (SaveProject.class));
...

An example of the Step popup menu that will permit specific actions on a given Step: 

// stepMenu is a JMenu
stepMenu.add(CommandManager.getInstance ().getCommand (Evolution.class));
stepMenu.add(CommandManager.getInstance ().getCommand (Intervention.class));
stepMenu.add(CommandManager.getInstance ().getCommand (DeleteStep.class));
// Step visibility sub menu
JMenu visibilityMenu = new JMenu (Translator.swap ("ShowStep.visibility"));
stepMenu.add (visibilityMenu);
visibilityMenu.add (CommandManager.getInstance ().getCommand ("ShowStep1"));
visibilityMenu.add (CommandManager.getInstance ().getCommand ("ShowStep5"));
...

Note: these commands are Actions (javax.swing) and also Commands (from the command pattern, with an execute () method). That's why you can directly add them in menus and toolbars, as well as trigerring them directly from your code this way: 

CommandManager.getInstance ().getCommand (NewProject.class).execute ();

Note: it is possible to add your own commands to the CommandManager to uniformise the way commands wil be managed in your hosting application: just create commands like the ones in the commongui package: the must extends AbstractAction and implement ActionCommand. To add them, use CommandManager.addCommand (ActionCommand command, Level level) or addCommand (String commandName, ActionCommand newCommand, Level level).

ShutdownHook

The command package also contains a way to save the session when the application is closed in an unexpected way. To add this facility, create a ShutdownHook in the constructor of your MainFrame this way (change “capsis” by the name of your application): 

// Register a shutdown hook to be called if the application is interrupted 
// in an unexpected way (Ctrl+C in shell...)
new ShutdownHook (this, "capsis");

And add the following code a bit lower in the MainFrame construction: 

// Rescue mode: check if the previous Capsis session crashed and if so, 
// propose to reload the previous rescue session
ShutdownHook.getInstance ().proposeToRestoreRescueSessionIfAny ();

The projectmanager package

The ProjectManager shows the current state of the session with all the included projects. Each project is drawn with its Steps according to its current memory and visibility options. Each Step in a project is shown as a button (instance of StepButton) with its name. The name is built with the date of the carried GScene and a letter (a, b…) to differentiate the various scenarios that can be built from the root Step.

Current Step

The Current Step has a special border. There is only one Current Step in all the session. To change the Current Step, click on it with the mouse in the ProjectManager.

The Current Step has a special border. Its embedding project is the Current Project, it is bordered with the same kind of border than the Current Step. The commands in the menu may rely on the Current Step or Project.

The Current object (Singleton: Current.getInstance ()) always knows about the Current Step and Project. It is possible to register to it as a listener to be told when the Current Step is changed by the user in the ProjectManager. This is a very convenient way to organise your hosting application regarding the Steps synchronisation.

Step popup

You may build the StepPopup in your hosting application by adding to it the commands you wish. The following example shows the construction of the StepPopup in Capsis. It mixes some commands of the commongui package and some Capsis specific commands (added to the CommandManager at construction time). 

// We want the step popup menu to look like the main step menu
List<Action> actionList = new ArrayList<Action> ();
actionList.add(commandManager.getCommand (Evolution.class));
actionList.add(commandManager.getCommand (Intervention.class));
actionList.add(commandManager.getCommand (Summary.class));
actionList.add(commandManager.getCommand (DeleteStep.class));
actionList.add(null);  // separator
actionList.add(commandManager.getCommand (BuildGrouper.class));
actionList.add(commandManager.getCommand (ExportStep.class));
actionList.add(commandManager.getCommand (ToolBox.class));
actionList.add(null);
actionList.add(commandManager.getCommand (ConfigureProject.class));
actionList.add(null);
// TODO: Add a JMenu visibilityMenu containing the four next actions
actionList.add(commandManager.getCommand ("ShowStep1"));
actionList.add(commandManager.getCommand ("ShowStep5"));
actionList.add(commandManager.getCommand ("ShowStep10"));
actionList.add(commandManager.getCommand ("ShowStep20"));
actionList.add(null);
actionList.add(commandManager.getCommand (StepProperties.class));
 
StepPopup.setActionList (actionList);

Right clicking on a Step has two effects: the Step becomes Current and the StepPopup opens. This popup proposes the Step level commands, for example Evolution to trigger the evolution method of the underlying model. This Evolution command generally results in the creation of several Steps after the current one.

Synchronisation colors

The application may use the ProjectManager's color system to open tools synchronised on given steps. These tools can listen to the color moves in the ProjectManager to move according to the user wish.

The colors are managed by the ButtonColorer (Singleton pattern). A tool manager can get a color with ButtonColorer.getInstance ().newColor (StepButton b). The opened tool can use the returned color to draw the data matching the colored Step. The tool should also implement ButtonColorerListener and register to it as a listener. Thus, it will be able to update on the new Step when the user moves the color to another Step: colorMoved (prevButton, newButton) or to close when the color is removed: colorRemoved (StepButton). Note that the color may change during the moves.

Steps visibility

The ProjectManager shows compact views of the projects i.e. not all the steps are shown. To tune the visibility, use the Step Menu / Step PopupMenu and use the visibility commands. It is possible to view All steps or to set a frequency: 1 / 5, 10 or 20.

For finer tuning, select a Step, Shift+select another one and the Expand / Collapse menu appears. Expand sets visible all the Steps in the range of the two selected, collapse set them unvisible.