Creating New UI Forms For Scenario Editor

Introduction

You may need to define scenario level settings that have a specific startup configuration for the scenario. One example of a configuration ability is the Environment Settings dialog, that allows Instructional Systems Designers to set scenario-startup settings, and allows Instructors to change the environment of the scenario during Distributed Mission Training runtime.

SIMbox provides you with a simple option to create scenario level configuration via global properties. This can be done, either by using the generic global properties editor (View \ Global Properties from the main menu of the Scenario Editor) or by creating your own User Interface (UI) form.

Global Properties Editor

In the Scenario Editor, select View \ Global Properties from the main menu. The Global Properties shows all the global properties that you can edit, and allows you to change their values. Any changes to values will be saved when you save your scenario, and then used when the scenario is executed.

Creating Extension

The first step should be to create an extension in the SIMbox Toolkit (Start\All Programs\KnowBook\SIMbox Toolkit). The extension will define global properties that will hold the initial scenario conditions that we want to add. Of course the extension will require code that reads the properties at runtime and uses them, but this is not discussed in this article.

For this example we assume that we want to create an extension to set the terrain color (R,G,B) for the scenario. We will create a new extension – "TerrainColors", with the global properties, as shown in the SIMbox Toolkit:

To be able to change these global properties at the scenario level, select the Show in Scenario Editor check box to make the properties available for editing in the Scenario Editor:

In the Scenario Editor, select View \ Global Properties from the main menu, type a value in the Filter field to see the Global Properties for Terrain Color. You can set the terrain color properties for the scenario, using the global properties editor:

Creating a Custom UI

An extension can define a menu - using the wizard at the time the extension is created, or it can be added later. In addition, UI forms (for example – a Dialog object) can be added to the extension project. For the Terrain Color UI example (above) we have a simple form with 3 slider controls which control the properties values with a 'Terrain Colors' menu option that opens the Terrain Color dialog. 

Since we want the UI and menu to be loaded when the scenario editor is used, we should add the extension to a duplicated version of the scenario editor configuration (collection). It is also possible to separate the UI and the logic by creating 2 new extensions:

• An extension that defines the global properties and reacts to their values - will be added to the runtime collection (or to a duplicated version or any other collection it is required in).
• And an extension that defines the menu and the UI and will be added to the scenario editor (a duplicated version) collection.

If you use only one extension, it is required to load the UI and menu only if the running configuration is the scenario editor (or a duplicated version of it). This can be done by checking the existence of a global attribute which is defined for the scenario editor collection – for example "GLOBAL_ATT_SCENE_BUILDER_IS_DESIGN_MODE".

Setting the Global Properties from the Extension

In order to change the global properties values for the scenario from the new UI, you will need to use the new simulation event “SetScenarioGlobalPropertyValue”. You’ll need to publish the event for each property you want to update.

For example, if we want to set the GLOBAL_PROP_TERRAIN_COLOR_R to 204 we will use the following code:

SimApi::EventParams* eventParams = SimApi::EventsFactory::getEventInstance(_T("SetScenarioGlobalPropertyValue"));
eventParams->getParam(_T("GlobalPropertyName"))->setValue( L"GLOBAL_PROP_TERRAIN_COLOR_B" );
eventParams->getParam(_T("GlobalPropertyValue"))->setValue( L"204");
eventParams->getParam(_T("UseComponentValue"))->setValue(false);
SimApi::EventHandler::publishEvent(eventParams);

Once the event is published, the new value will be reflected in the global properties table:

In order to implement the reversed direction and update the UI when the global property value is changed in the global properties editor, you’ll need to respond to the new simulation event “ScenarioGlobalPropertyChanged”. This event is published by the Global Properties Editor and notifies of a change done to a global property value.

Your new extension should register to this event and in the callback function update the UI when the global property value is changed:

Using these events, it is possible to keep the UI and global properties list synchronized. The updated global properties values will be saved when the scenario is saved, and the updated values will be loaded when the scenario is run.