Creating a desktop application

Intro

We at Amalgama have noticed that there is a common pattern in most simulation applications that we have created:

  • There are several typical 'perspectives', or application modes: editor, simulation, planning, scenario analysis, etc.

  • Each 'perspective' has its own convenient layout of UI elements.

  • Almost every application uses a set of third-party dependencies.

To save time on routine actions we created a 'Desktop Application Wizard' that generates a starter GUI application in just a few clicks.

Creating an application with Amalgama Desktop Application Wizard

First, make sure that you have:

After that, do the following:

  1. Start a new instance of Eclipse using a completely new Workspace.

  2. Set up JavaFX location. See Set up JavaFX libraries path in Eclipse Workspace for details.

  3. Choose 'File' → 'New' → 'Amalgama Desktop Application'. A new wizard window opens.

  4. Enter the project name, project location (remember it), and package prefix:

    Wizard window
  5. Press 'Finish'.

A new project has been created and opened in Eclipse. But it has compilation errors, as some dependencies are missing. External dependencies used for compilation are listed in the active target platform. By default - the target platform embedded in Eclipse is active.

To use the project’s target platform:

  1. Open the Plug-in Development perspective:

    1. Click the 'Open Perspective' tool button in the top right corner of Eclipse windows.

    2. Select the 'Plug-in Development' from the perspectives list and click 'Open'. The Project Explorer tab should now be displayed in the left part of Eclipse window.

  2. In the Project Explorer window, find the releng/(your-app-package-name).target/(your-app-package-name).target.target file and open it (double-click).

  3. Click the 'Set as Active Target Platform' button (looks like a link) in the top right corner of the target file editor in Eclipse.

The project target platform takes several minutes to download its contents. After the active target platform download is complete, the generated project opened in Eclipse should compile without errors.

Overview of the Generated Application

Starting the New Application

Let’s make sure the new application compiles and runs.

Go to the 'releng/*product' folder, open the '*product' file therein and press the 'Launch an Eclipse application' button (top-right corner).

Your newly created application should have started successfully:

First run of a wizard-generated application

You can now use the created template application to make your own fully-functional simulation model.

Editor mode

When the application is started, it opens in 'Editor' mode. This mode, or perspective, is where you create and edit a scenario, i.e., set the initial data for your simulation.

To create a new (empty) scenario, choose the 'File' → 'New' command. A new scenario is created, and the 'Scenario structure' sub-window (also known as 'part') is populated.

New scenario

The scenario data model in a generated application already contains transport network classes. It it easy to add them directly onto a map. To create a new node, go to the 'Map' part. It has a toolbar on its left with buttons that you can use to add nodes and arcs to the canvas. To add an arc, create at least two nodes first, then press the 'Arc' button and sequentially click the nodes you would like to connect.

The 'Center' toolbar button zooms and pans the canvas so that all nodes and arcs become visible.

Press and hold the right mouse button to pan the map. Press the 'Ctrl' keyboard key and use the mouse scroll to zoom.

Create several random nodes and connect them with arcs:

Editing nodes and arcs

Note the 'Objects' part in the bottom-left corner of the application window. Each time you select a Node or an Arc in the 'Map' part, the 'Objects' part is populated with objects of the respective type. The same happens when you select the 'Nodes' or 'Arcs' items in the 'Scenario structure' part.

The 'Objects' part and the 'Map' part are synchronized: each time you select an object in one part - it gets selected in the other part as well.

Properties of the selected object are shown in the 'Properties' part, you can edit them here. For example, you can manually change the latitude of a Node, and it will change its position on the map accordingly.

Scenario saving and loading

A scenario can be saved to a file and loaded from a file. In the 'Editor' mode, use 'File' → 'Save' (or 'Save as') and 'File' → 'Open' menu items.

A scenario is saved to an Excel file whose structure reflects the scenario data model: . Each scenario data model class has a dedicated Excel sheet. . If your data model contains many-to-many dependencies, a separate sheet is created to break this m2m dependency into two one-to-many dependencies.

Sheet names can be customized, as well as the localized column titles (see ObjectType and EMFExcelTransformFactory classes in the 'application' bundle). This comes in handy when manually editing the Excel scenario file outside the application.

Simulation mode

Select the 'Mode' → 'Simulation' to get to the simulation perspective. This is where you run the model and observe its current state and simulation results.

Simulation mode

A new toolbar appears at the window top to control the simulation process.

You can use 'Run' and 'Stop' buttons to control the simulation. Despite its name, 'Stop' actually means 'Pause': after stopping you can push the 'Run' button again to resume the simulation.

Simulation speed can be increased and decreased. You can also toggle the 'fastest' mode.

The simulation time range is set in the scenario settings. To change it, go back to the 'Editor' mode, select the 'Scenario' item in the 'Scenario structure' and edit its 'Begin date' and 'End date' properties in the 'Properties' part.

The 'Simulation status' part (top-left) shows brief runtime statistics.

The 'Summary statistics' part (bottom-left) displays the output model statistics. In case of a newly created application, arcs count and nodes count are displayed. Real-world examples of model output data include: total distance traveled by vehicles, total costs, etc.

The 'Animation' part draws objects being simulated. Initially, the road graph is shown. Road graph data in the simulation model is mapped directly from the respective scenario data.

Source code overview of the generated application

The generated application contains 3 bundles (subprojects):

  1. 'application': main bundle that creates the graphical interface.

  2. 'datamodel': initial state data model (i.e., scenario data model).

  3. 'simulation': all the simulation logic resides here.

Note that the 'simulation' and 'datamodel' bundles contain no UI-related code, they are independent of SWT, JavaFX, JFace, etc., so these two bundles can be reused as part of a web service or a web application backend.