v2.32
 
How to extend the user interface

Overview

Renga API allows developers to extend user interface of Renga in a number of ways: plugins can add custom controls to panels and commands to context menus, show notification messages, use the "Open file" and "Save file" dialogs, etc. Most of these means are available via the IUI interface. To get a refernce to it call IApplication::GetUI().

How to create actions

Renga API does not allow to operate directly on UI controls, such as tool buttons and windows. Instead, it provides a higher-level abstraction of user interface commands, represented by the IAction interface. Actions control the UI elements they are assigned to: an action defines the tooltip, the icon image and the state of the element and supplies handlers for the element's events. The same action instance can be assigned to different controls simultaneously, for example, both to a button and a context menu item. Call IUI::CreateAction() to create an action.

C++

Renga::IImagePtr pImage = pUI->CreateImage();
pImage->LoadFromFile(L"Icon path");
Renga::IActionPtr pAction = pUI->CreateAction();
pAction->PutDisplayName(L"Name");
pAction->PutToolTip(L"Tooltip text");
pAction->PutIcon(pImage);

C#

Renga.IImage image = ui.CreateImage();
image.LoadFromFile("Icon path");
Renga.IAction action = ui.CreateAction();
action.DisplayName = "Name";
action.ToolTip = "Tooltip text";
action.Icon = image;

How to handle action events

Event handling, in a way, differs between the SDK languages. C++ SDK provides the ActionEventHandler helper class, which leverages the COM event subscription itself. C# SDK provides an alternative implementation, the ActionEvents class, to facilitate the native .NET event syntax.

C++

class MyActionHandler : public Renga::ActionEventHandler
{
public:
void OnTriggered() override
{
// handle the OnTriggered event
}
void OnToggled(bool checked) override
{
// handle the OnToggled event
}
};
...
Renga::IActionPtr pMyAction = createMyAction();
m_pMyHandler = new MyActionHandler(pMyAction); // should stay alive as long as you need to handle the events
Definition ActionEventHandler.hpp:21

C#

Renga.IAction myAction = createMyAction();
m_myActionEvents = new Renga.ActionEvents(myAction); // should stay alive as long as you need to handle the events
myActionEvents.Triggered += (sender, args) => { /* handle the Triggered event */ };
myActionEvents.Toggled += (sender, args) => { /* handle the Toggled event */};

Since Renga API is built on COM, you can also create your own event handlers using the IConnectionPoint mechanism directly.

How to add custom controls to panels

C++

Renga::IUIPanelExtensionPtr pUIPanelExtension = pUI->CreateUIPanelExtension();
pUIPanelExtension->AddToolButton(CreateAction1());
Renga::IDropDownButtonPtr pDropDownButton = pUI->CreateDropDownButton();
pDropDownButton->PutToolTip(L"DropDownButton tooltip");
pDropDownButton->PutIcon(CreateIconForDropdownButton());
pDropDownButton->AddAction(CreateAction2());
pDropDownButton->AddAction(CreateAction3());
pUIPanelExtension->AddDropDownButton(pDropDownButton);
Renga::ISplitButtonPtr pSplitButton = pUI->CreateSplitButton(CreateDefaultAction()));
pSplitButton->AddAction(CreateAction4());
pSplitButton->AddAction(CreateAction5());
pUIPanelExtension->AddSplitButton(pSplitButton);
// Add controls to the primary panel:
pUI->AddExtensionToPrimaryPanel(pUIPanelExtension);
// Add controls to the action panel, specific for the 3D view:
pUI->AddExtensionToActionsPanel(pUIPanelExtension, Renga::ViewType::ViewType_View3D);

C#

Renga.IUIPanelExtension uiIPanelExtension = ui.CreateUIPanelExtension();
uiIPanelExtension.AddToolButton(CreateAction1());
Renga.IDropDownButton dropDownButton = ui.CreateDropDownButton();
// DropDownButton has it's own name and icon
dropDownButton.ToolTip = "DropDownButton tooltip";
dropDownButton.Icon = CreateIconForDropdownButton();
dropDownButton.AddAction(CreateAction1());
dropDownButton.AddAction(CreateAction2());
uiIPanelExtension.AddDropDownButton(dropDownButton);
// SplitButton has a default action
Renga.ISplitButton splitButton = ui.CreateSplitButton(CreateDefaultAction()));
splitButton.AddAction(CreateAction3());
splitButton.AddAction(CreateAction4());
uiIPanelExtension.AddSplitButton(splitButton);
// Add controls to the primary panel:
ui.AddExtensionToPrimaryPanel(uiIPanelExtension);
// Add controls to the action panel, specific for the 3D view:
ui.AddExtensionToActionsPanel(uiIPanelExtension, Renga.ViewType.ViewType_View3D);

How to create context menus

C++

Renga::IContextMenuPtr pContextMenu = pUI->CreateContextMenu();
pContextMenu->AddActionItem(CreateAction1());
pContextMenu->AddActionItem(CreateAction2());
pContextMenu->AddSeparator();
// Create a nested context menu node:
Renga::IContextMenuNodeItemPtr pContextMenuNode = pContextMenu->AddNodeItem();
pContextMenuNode->AddActionItem(CreateAction3());
pContextMenuNode->AddSeparator();
pContextMenuNode->AddActionItem(CreateAction4());
// Define the context menu ID. It can be used to update the contents of the menu.
// To update the menu create a new context menu and call AddContextMenu with the previously used ID.
GUID contextMenuId;
IIDFromString(L"{AE6F83B2-648D-4D01-B393-841D65DA922E}", &contextMenuId);
// The context menu will be shown on the 3D view scene. Use ContextMenuShowCase_Selection to show the menu only on selected objects.
pUI->AddContextMenu(&contextMenuId, pContextMenu, Renga::ViewType::ViewType_View3D, Renga::ContextMenuShowCase::ContextMenuShowCase_Scene);

C#

Renga.IContextMenu contextMenu = ui.CreateContextMenu();
contextMenu.AddActionItem(CreateAction1());
contextMenu.AddActionItem(CreateAction2());
contextMenu.AddSeparator();
// Create a nested context menu node:
Renga.IContextMenuNodeItem contextMenuNode = contextMenu.AddNodeItem();
contextMenuNode.AddActionItem(CreateAction3());
contextMenuNode.AddSeparator();
contextMenuNode.AddActionItem(CreateAction4());
// Define the context menu ID. It can be used to update the contents of the menu.
// To update the menu create a new context menu and call AddContextMenu with the previously used ID.
Guid contextMenuId = new Guid("{AE6F83B2-648D-4D01-B393-841D65DA922E}");
// The context menu will be shown on the 3D view scene. Use ContextMenuShowCase_Selection to show the menu only on selected objects.
ui.AddContextMenu(contextMenuId, contextMenu, Renga.ViewType.ViewType_View3D, Renga.ContextMenuShowCase.ContextMenuShowCase_Scene);

See also

Related samples

  • Buttons
  • ControlStateManagement
  • ContextMenus