SIMbox Framework - Adding basic UI panes

From SIMboxWiki

Jump to: navigation, search

Each extension can add UI elements such as menus, toolbars and panes. This document and the associated source code will list the required steps for creating a basic pane in the simulation.


A pane is formed by creating an instance of an MFC dialog and adding it as the pane content. This means that you can host any dialog you like with complex logic, controls, display and input validation. You may also create panes that show graph data or any other valid dialog content.


Start off by creating a new extension project, or use an existing one to host your pane:

Image:Extension project.JPG


Open up the resource view and add a new dialog:

Image:Add Resource 1.JPG Image:Add Resource 2.JPG


Use the wizard to create a class representing the dialog you just created:

Image:Add Class 1.JPG Image:Add Class 2.JPG


Open up the new header file created by the wizard and add a reference to the resource.h file:

Image:Add Reference.JPG


Next, add a forward declaration of the dialog class to the extension main header file:

Image:Add Declaration.JPG


Add a new member to the extension that will hold a pointer to an instance of the dialog:

Image:Add Member.JPG


Add an include directive to the extension main cpp file so it will recognize the dialog:

Image:Add Include.JPG


In the extension init phase, create the dialog instance and add it as a pane. Notice the resource switch macros. You may also set some other settings for the pain such as icon, minimum and maximum size and so on:

Image:Init.JPG


Add a cleanup cod segment in the end phase of the extension:

Image:Cleanup.JPG


Now build the extension in release mode and analyze it. Add the extension to an extension collection:

Image:Add Extension.JPG


Run the extension collection and notice the new pane:

Image:New Pane.JPG


Click on the menu item and you should see the new pane hosting the dialog:

Image:New Pane with dialog 1.JPG Image:New Pane with dialog 2.JPG


You may notice the dialog Border in this pane. Set the dialog Border to None to hide it. Also set its style to Child in order to make it resizable while in floating position:

Image:Dialog Adjustments 1.JPG Image:Dialog Adjustments 2.JPG


It is also a good practice to disable the option to close the dialog. For this, override the OnOK and OnCancel methods of the dialog and block the calls to the parent class:

Image:Dialog Adjustments 3.JPG

Image:Dialog Adjustments 4.JPG


As you might see, the simulation does not save the state of the pane – meaning that next time you run your extension collection the pane will be hidden again. If you wish to persist the state of the pane you need to pass a unique pane ID. Valid values for identifiers are 103-300:

Image:Pass ID.JPG


You may also pass an instance of a SimApi::IPaneNotification implementer that can respond to various pane messages.

Review the associated sample project (GUI Extension sample project) to see how you can easily use MFC controls to interact with the user and the simulation engine. The project adds a pane that shows the vector of 2D map selected entities (global attribute) and enables the user to display a message by entering the message text and clicking a button (publish a global event).

Image:Sample Project.JPG

Personal tools