Graphics Editor API

Create Items

Graphics items are “created” via configurations. Every type of item has its own configuration implementation in the OTGui library. These configurations are then used in the Frontend by the OTWidgets library to create the actual item. For more information read the ot::GraphicsItemCfg code documentation.

Fill item picker

The item picker is a tree structure containing the item information sorted in collections. To fill the item picker a ot::GraphicsPickerCollectionPackage must be provided. The collection package contains a list of (potentially nested) ot::GraphicsPickerCollectionCfg where every collection may be seen as a “folder”. The collection contains child collections and a list of ot::GraphicsPickerCollectionCfg::ItemInformation. Every information entry represents an item that the user can pick. A item information consists of the item name (that is used in the Add Item Callback), the item title that is displayed to the user and the preview icon.

Add Items to View

#include "OTCore/Owner.h"
#include "OTGui/GraphicsPackage.h"

void foo(void) {
   // Create items to add to the scene
   ...

   // Create package
   ot::GraphicsScenePackage pckg("My Graphics View Name");
   pckg.addItem(myFirstItem);
   pckg.addItem(mySecondItem);
   ...

   // Create request
   OT_rJSON_createDOC(reqDoc);
   OT_rJSON_createValueObject(pckgObj);
   pckg.addToJsonObject(reqDoc, pckgObj);

   ot::rJSON::add(reqDoc, OT_ACTION_MEMBER, OT_ACTION_CMD_UI_GRAPHICSEDITOR_AddItem);
   ot::rJSON::add(reqDoc, OT_ACTION_PARAM_GRAPHICSEDITOR_Package, pckgObj);
   ot::GlobalOwner::instance().addToJsonObject(reqDoc, reqDoc);

   // Create request that should be send to the UI
   std::string request = ot::rJSON::toJSON(reqDoc);

   // Send request
   ...
}

Remove Items from View

#include "OTCore/Owner.h"

void foo(void) {
   std::list<std::string> items;

   // Add item UIDs to the list above (items to be removed)
   ...

   // Create request
   OT_rJSON_createDOC(reqDoc);
   ot::rJSON::add(reqDoc, OT_ACTION_MEMBER, OT_ACTION_CMD_UI_GRAPHICSEDITOR_RemoveItem);
   ot::rJSON::add(reqDoc, OT_ACTION_PARAM_GRAPHICSEDITOR_EditorName, "My Graphics View Name");
   ot::rJSON::add(reqDoc, OT_ACTION_PARAM_GRAPHICSEDITOR_ItemIds, items);
   ot::GlobalOwner::instance().addToJsonObject(reqDoc, reqDoc);

   // Create request that should be send to the UI
   std::string request = ot::rJSON::toJSON(reqDoc);

   // Send request
   ...
}

Add Connections

#include "OTCore/Owner.h"
#include "OTGui/GraphicsPackage.h"

void foo(void) {
   // Create package
   ot::GraphicsConnectionPackage pckg("My Graphics View Name");

   // Fill package
   pckg.addConnection(sourceUid, sourceName, destinationUid, destinationName);
   ...

   // Create request
   OT_rJSON_createDOC(reqDoc);
   OT_rJSON_createValueObject(pckgObj);
   pckg.addToJsonObject(reqDoc, pckgObj);

   ot::rJSON::add(reqDoc, OT_ACTION_MEMBER, OT_ACTION_CMD_UI_GRAPHICSEDITOR_AddConnection);
   ot::rJSON::add(reqDoc, OT_ACTION_PARAM_GRAPHICSEDITOR_Package, pckgObj);
   ot::GlobalOwner::instance().addToJsonObject(reqDoc, reqDoc);

   // Create request that should be send to the UI
   std::string request = ot::rJSON::toJSON(reqDoc);

   // Send request
   ...
}

Remove Connections

#include "OTCore/Owner.h"
#include "OTGui/GraphicsPackage.h"

void foo(void) {
   // Create package
   ot::GraphicsConnectionPackage pckg("My Graphics View Name");

   // Fill package
   pckg.addConnection(sourceUid, sourceName, destinationUid, destinationName);
   ...

   // Create request
   OT_rJSON_createDOC(reqDoc);
   OT_rJSON_createValueObject(pckgObj);
   pckg.addToJsonObject(reqDoc, pckgObj);

   ot::rJSON::add(reqDoc, OT_ACTION_MEMBER, OT_ACTION_CMD_UI_GRAPHICSEDITOR_RemoveConnection);
   ot::rJSON::add(reqDoc, OT_ACTION_PARAM_GRAPHICSEDITOR_Package, pckgObj);
   ot::GlobalOwner::instance().addToJsonObject(reqDoc, reqDoc);

   // Create request that should be send to the UI
   std::string request = ot::rJSON::toJSON(reqDoc);

   // Send request
   ...
}

Callbacks

The Graphics API provides the following actions as callbacks:

OT_ACTION_CMD_UI_GRAPHICSEDITOR_AddItem
OT_ACTION_CMD_UI_GRAPHICSEDITOR_AddConnection
OT_ACTION_CMD_UI_GRAPHICSEDITOR_AddConnectionToConnection
OT_ACTION_CMD_UI_GRAPHICSEDITOR_ItemChanged

The actions are defined in OTCommunication/ActionTypes.h.

Note

Note that remove requests are handled via the ModelEntities and not via the Graphics API.

Add Item Callback

Action Parameters
Action Parameter	Type	Description
OT_ACTION_PARAM_GRAPHICSEDITOR_ItemName	String	The name of the requested item.
OT_ACTION_PARAM_GRAPHICSEDITOR_ItemPosition	ot::Point2DD	The position the user dropped the item at.
OT_ACTION_PARAM_GRAPHICSEDITOR_EditorName	String	Name of the Graphics Editor.

The add item action is sent whenever the user dropped a Graphics Item on the View.

Add Connection Callback

Action Parameters
Action Parameter	Type	Description
OT_ACTION_PARAM_GRAPHICSEDITOR_Package	ot::GraphicsConnectionPackage	Package containing all connections and the editor name.

The add connection action is sent when the user has created a valid connection in the Graphics Editor. A valid connection is a connection that has a valid origin and destination item and the origin and destination are not equal.

Add Connection To Connection Callback

Action Parameters
Action Parameter	Type	Description
OT_ACTION_PARAM_GRAPHICSEDITOR_Package	ot::GraphicsConnectionPackage	Package containing all connections and the editor name. Note that the connection destination UID is the targeted connection and the destination connectable name is always empty.
OT_ACTION_PARAM_POSITION	ot::Point2DD	The new control point. This is the location the user pressed with the mouse at. Here the new intersection item should be placed at when needed.

The add connection to connection action is sent when the user has created a valid connection in the Graphics Editor. A valid connection is a connection that has a valid origin item and valid connection item as destination.

Item Changed Callback

Action Parameters
Action Parameter	Type	Description
OT_ACTION_PARAM_Config	ot::GraphicsItemCfg	The current item configuration.
OT_ACTION_PARAM_GRAPHICSEDITOR_EditorName	String	Name of the Graphics Editor.

The change action is sent whenever the current item configuration has changed. For example the item has been moved (after the move operation is finished), transformed, renamed, and so on. In general, whenever any member of the ot::GraphicsItemCfg has changed in the Frontend the item changed action is sent.