IUI Interface Reference

Contains functions relating to the user interface. More...

Inheritance diagram for IUI:

Public Member Functions
HRESULT	AddContextMenu ([in, ref] GUID *pId, [in] IContextMenu *pMmenu, [in] enum ViewType viewType_, [in] enum ContextMenuShowCase showCase_)
	Adds items and submenus to Renga context menus.
HRESULT	AddContextMenuS ([in] BSTR uniqueId_, [in] IContextMenu *pMmenu, [in] enum ViewType viewType_, [in] enum ContextMenuShowCase showCase_)
	Same as AddContextMenu, but accepting GUID as a string.
HRESULT	AddExportAction ([in] IAction *pAction)
	Adds an action to the export drop-down menu of the application.
HRESULT	AddExtensionToActionsPanel ([in] IUIPanelExtension *pUIPanelExtension, [in] enum ViewType viewType_)
	Adds a UI panel extension to the Actions application panel.
HRESULT	AddExtensionToPrimaryPanel ([in] IUIPanelExtension *pUIPanelExtension)
	Adds a UI panel extension to the primary application panel.
HRESULT	AddToolButtonToActionsPanel ([in] IAction *pAction, [in] enum ViewType viewType_)
	Adds a tool button to the Actions application panel.
HRESULT	CreateAction ([out, retval] IAction **ppAction)
	Creates a new action object.
HRESULT	CreateActionWithId ([in] GUID id, [out, retval] IAction **ppAction)
	Creates a new action object with the specified identifier.
HRESULT	CreateContextMenu ([out, retval] IContextMenu **ppContextMenu)
	Creates a new context menu.
HRESULT	CreateDropDownButton ([out, retval] IDropDownButton **ppDropDownButton)
	Creates a drop-down button.
HRESULT	CreateDropDownButtonWithId ([in] GUID id, [out, retval] IDropDownButton **ppDropDownButton)
	Creates a drop-down button with the specified identifier.
HRESULT	CreateDropDownButtonWithIdS ([in] BSTR id, [out, retval] IDropDownButton **ppDropDownButton)
	Creates a drop-down button with the specified identifier.
HRESULT	CreateImage ([out, retval] IImage **ppImage)
	Creates an image.
HRESULT	CreateSplitButton ([in] IAction *pDefaultAction, [out, retval] ISplitButton **ppSplitButton)
	Creates a split button.
HRESULT	CreateSplitButtonWithId ([in] GUID id, [in] IAction *pDefaultAction, [out, retval] ISplitButton **ppSplitButton)
	Creates a split button with the specified identifier.
HRESULT	CreateSplitButtonWithIdS ([in] BSTR id, [in] IAction *pDefaultAction, [out, retval] ISplitButton **ppSplitButton)
	Creates a split button with the specified identifier.
HRESULT	CreateToolButton ([out, retval] IToolButton **ppToolButton)
	Creates a tool button.
HRESULT	CreateToolButtonWithId ([in] GUID id, [out, retval] IToolButton **ppToolButton)
	Creates a tool button with the specified identifier.
HRESULT	CreateToolButtonWithIdS ([in] BSTR id, [out, retval] IToolButton **ppToolButton)
	Creates a tool button with the specified identifier.
HRESULT	CreateUIPanelExtension ([out, retval] IUIPanelExtension **ppUIPanelExtension)
	Creates an extension for a UI panel.
HRESULT	GetAction ([in] GUID id, [out, retval] IAction **ppAction)
	Returns an existing action by the given id.
HRESULT	GetControlVisibility ([in] GUID id, [out, retval] VARIANT_BOOL *pVisible)
	Returns the control visibility state.
HRESULT	GetControlVisibilityS ([in] BSTR id, [out, retval] VARIANT_BOOL *pVisible)
	Returns the control visibility state.
HRESULT	SetControlVisibility ([in] GUID id, [in] VARIANT_BOOL isVisible)
	Allows to set the control visibility state.
HRESULT	SetControlVisibilityS ([in] BSTR id, [in] VARIANT_BOOL isVisible)
	Allows to set the control visibility state.
HRESULT	ShowMessageBox ([in] enum MessageIcon icon_, [in] BSTR title_, [in] BSTR text_)
	Shows a modal message box with the given icon, title and text and the Close button.
HRESULT	ShowOpenFileDialog ([in] BSTR title_, [in] BSTR defaultPath, [in] BSTR filter, [out, retval] BSTR *pFileName)
	Shows the Open File dialog and returns the name of an existing file selected by user.
HRESULT	ShowSaveFileDialog ([in] BSTR title, [in] BSTR defaultPath, [in] BSTR filter, [out, retval] BSTR *pFileName)
	Shows the Save File dialog and returns the file name selected by user.

Detailed Description

Contains functions relating to the user interface.

This interface provides methods to manage custom user interface controls displayed in the application, such as tool buttons on the primary panel. There are several ways to extend Renga's user interface:

• Add custom buttons to the main toolbar using the AddExtensionToPrimaryPanel() method;
• Add custom buttons to the Actions tool panel using the AddExtensionToActionsPanel() and AddToolButtonToActionsPanel() methods;
• Add custom items to the context menu using the AddContextMenu() method;
• Add custom items to the Export drop-down menu using the AddExportAction() method.

Besides, it provides methods to show messages and use the Open and Save File dialogs.

Member Function Documentation

AddContextMenu()

HRESULT AddContextMenu	(	[in, ref] GUID *	pId,
		[in] IContextMenu *	pMmenu,
		[in] enum ViewType	viewType_,
		[in] enum ContextMenuShowCase	showCase_ )

Adds items and submenus to Renga context menus.

Parameters

[in]	pId	The unique identifier of added Renga context menu.
[in]	pMmenu	The items to add.
[in]	viewType_	The type of the view whose context menu will contain the new items.
[in]	showCase_	The situation when the items should be shown.

AddContextMenuS()

HRESULT AddContextMenuS	(	[in] BSTR	uniqueId_,
		[in] IContextMenu *	pMmenu,
		[in] enum ViewType	viewType_,
		[in] enum ContextMenuShowCase	showCase_ )

Same as AddContextMenu, but accepting GUID as a string.

Parameters

[in]	uniqueId_	The unique identifier of added Renga context menu.
[in]	pMmenu	The items to add.
[in]	viewType_	The type of the view whose context menu will contain the new items.
[in]	showCase_	The situation when the items should be shown.

AddExportAction()

HRESULT AddExportAction

(

[in] IAction *

pAction

)

Adds an action to the export drop-down menu of the application.

Parameters

[in]

pAction

The action to add.

See also

AddContextMenu()

AddExtensionToActionsPanel()

HRESULT AddExtensionToActionsPanel	(	[in] IUIPanelExtension *	pUIPanelExtension,
		[in] enum ViewType	viewType_ )

Adds a UI panel extension to the Actions application panel.

Parameters

[in]	pUIPanelExtension	The UI panel extension to add.
[in]	viewType_	The specific type of the view to show the extension on.

AddExtensionToPrimaryPanel()

HRESULT AddExtensionToPrimaryPanel

(

[in] IUIPanelExtension *

pUIPanelExtension

)

Adds a UI panel extension to the primary application panel.

Parameters

[in]

pUIPanelExtension

The UI panel extension to add.

AddToolButtonToActionsPanel()

HRESULT AddToolButtonToActionsPanel	(	[in] IAction *	pAction,
		[in] enum ViewType	viewType_ )

Adds a tool button to the Actions application panel.

Parameters

[in]	pAction	The action to associate with the new button.
[in]	viewType_	The specific type of the view to add the button to.

CreateAction()

HRESULT CreateAction

(

[out, retval] IAction **

ppAction

)

Creates a new action object.

Parameters

[out]

ppAction

The action interface which references the new action.

See also

GetAction()

CreateActionWithId()

HRESULT CreateActionWithId	(	[in] GUID	id,
		[out, retval] IAction **	ppAction )

Creates a new action object with the specified identifier.

Parameters

[in]	id	The unique identifier of the action
[out]	ppAction	The action interface which references the new action.

See also

GetAction()

CreateContextMenu()

HRESULT CreateContextMenu

(

[out, retval] IContextMenu **

ppContextMenu

)

Creates a new context menu.

Parameters

[out]

ppContextMenu

The new context menu.

See also

AddContextMenu()

CreateDropDownButton()

HRESULT CreateDropDownButton

(

[out, retval] IDropDownButton **

ppDropDownButton

)

Creates a drop-down button.

Parameters

[out]

ppDropDownButton

The drop-down button interface which references the new drop-down button.

CreateDropDownButtonWithId()

HRESULT CreateDropDownButtonWithId	(	[in] GUID	id,
		[out, retval] IDropDownButton **	ppDropDownButton )

Creates a drop-down button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control.
[out]	ppDropDownButton	The drop-down button interface which references the new drop-down button.

CreateDropDownButtonWithIdS()

HRESULT CreateDropDownButtonWithIdS	(	[in] BSTR	id,
		[out, retval] IDropDownButton **	ppDropDownButton )

Creates a drop-down button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control as a string.
[out]	ppDropDownButton	The drop-down button interface which references the new drop-down button.

CreateImage()

HRESULT CreateImage

(

[out, retval] IImage **

ppImage

)

Creates an image.

Parameters

[out]

ppImage

The new image.

See also

IAction::Icon

CreateSplitButton()

HRESULT CreateSplitButton	(	[in] IAction *	pDefaultAction,
		[out, retval] ISplitButton **	ppSplitButton )

Creates a split button.

Parameters

[in]	pDefaultAction	The action to trigger when user clicks on the primary button
[out]	ppSplitButton	The split button interface which references the new split button.

CreateSplitButtonWithId()

HRESULT CreateSplitButtonWithId	(	[in] GUID	id,
		[in] IAction *	pDefaultAction,
		[out, retval] ISplitButton **	ppSplitButton )

Creates a split button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control.
[in]	pDefaultAction	The action to trigger when user clicks on the primary button
[out]	ppSplitButton	The split button interface which references the new split button.

CreateSplitButtonWithIdS()

HRESULT CreateSplitButtonWithIdS	(	[in] BSTR	id,
		[in] IAction *	pDefaultAction,
		[out, retval] ISplitButton **	ppSplitButton )

Creates a split button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control as a string.
[in]	pDefaultAction	The action to trigger when user clicks on the primary button
[out]	ppSplitButton	The split button interface which references the new split button.

CreateToolButton()

HRESULT CreateToolButton

(

[out, retval] IToolButton **

ppToolButton

)

Creates a tool button.

Parameters

[out]

ppToolButton

The tool button interface which references the new tool button.

CreateToolButtonWithId()

HRESULT CreateToolButtonWithId	(	[in] GUID	id,
		[out, retval] IToolButton **	ppToolButton )

Creates a tool button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control.
[out]	ppToolButton	The tool button interface which references the new tool button.

CreateToolButtonWithIdS()

HRESULT CreateToolButtonWithIdS	(	[in] BSTR	id,
		[out, retval] IToolButton **	ppToolButton )

Creates a tool button with the specified identifier.

Parameters

[in]	id	The unique identifier of the control as a string.
[out]	ppToolButton	The tool button interface which references the new tool button.

CreateUIPanelExtension()

HRESULT CreateUIPanelExtension

(

[out, retval] IUIPanelExtension **

ppUIPanelExtension

)

Creates an extension for a UI panel.

Parameters

[out]

ppUIPanelExtension

The action interface which references the new panel extension.

GetAction()

HRESULT GetAction	(	[in] GUID	id,
		[out, retval] IAction **	ppAction )

Returns an existing action by the given id.

Parameters

[in]	id	The unique identifier of the action.
[out]	ppAction	The requested action interface if there exists one; nullptr otherwise.

See also

CreateAction(), CreateActionWithId()

GetControlVisibility()

HRESULT GetControlVisibility	(	[in] GUID	id,
		[out, retval] VARIANT_BOOL *	pVisible )

Returns the control visibility state.

Parameters

[in]	id	The unique identifier of the control.
[in]	isVisible	The visibility flag to return.

GetControlVisibilityS()

HRESULT GetControlVisibilityS	(	[in] BSTR	id,
		[out, retval] VARIANT_BOOL *	pVisible )

Returns the control visibility state.

Parameters

[in]	id	The unique identifier of the control as a string.
[in]	isVisible	The visibility flag to return.

SetControlVisibility()

HRESULT SetControlVisibility	(	[in] GUID	id,
		[in] VARIANT_BOOL	isVisible )

Allows to set the control visibility state.

Parameters

[in]	id	The unique identifier of the control.
[in]	isVisible	The visibility flag.

SetControlVisibilityS()

HRESULT SetControlVisibilityS	(	[in] BSTR	id,
		[in] VARIANT_BOOL	isVisible )

Allows to set the control visibility state.

Parameters

[in]	id	The unique identifier of the control as a string.
[in]	isVisible	The visibility flag.

ShowMessageBox()

HRESULT ShowMessageBox	(	[in] enum MessageIcon	icon_,
		[in] BSTR	title_,
		[in] BSTR	text_ )

Shows a modal message box with the given icon, title and text and the Close button.

When a message box is shown, users cannot interact with any other Renga's windows until the box is closed.

Note

This method should not be called from any threads other than the ones run by Renga.

Parameters

[in]	icon_	The message box icon.
[in]	title_	The message box title.
[in]	text_	The message text.

ShowOpenFileDialog()

HRESULT ShowOpenFileDialog	(	[in] BSTR	title_,
		[in] BSTR	defaultPath,
		[in] BSTR	filter,
		[out, retval] BSTR *	pFileName )

Shows the Open File dialog and returns the name of an existing file selected by user.

Parameters

[in]	title_	The localized dialog title.
[in]	defaultPath	The working directory of the dialog. If defaultPath includes a file name, the file will be selected initially. The defaultPath may be empty.
[in]	filter	Filters determine which files to show in the dialog. A filter consists of the filter name followed by a space-separated list of filename wildcard patterns, enclosed in parentheses. To supply multiple filters, separate them with two semicolons. For example: ‍"Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" To show all files, pass an empty string.
[out]	pFileName	The file name selected by user. If the user has pressed the Cancel or Close button instead, an empty string is returned.

ShowSaveFileDialog()

HRESULT ShowSaveFileDialog	(	[in] BSTR	title,
		[in] BSTR	defaultPath,
		[in] BSTR	filter,
		[out, retval] BSTR *	pFileName )

Shows the Save File dialog and returns the file name selected by user.

Parameters

[in]	title	The localized dialog title.
[in]	defaultPath	The working directory of the dialog. If defaultPath includes a file name, the file will be selected initially. The defaultPath may be empty.
[in]	filter	Filters determine which files to show in the dialog. A filter consists of the filter name followed by a space-separated list of filename wildcard patterns, enclosed in parentheses. To supply multiple filters, separate them with two semicolons. For example: ‍"Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" To show all files, pass an empty string.
[out]	pFileName	The file name selected by user; the file does not have to exist. If the user has pressed the Cancel or Close button instead, an empty string is returned.