IRnWidgetSubsystem Interface Reference

Inherits IUnknown.

List of all members.

Public Member Functions
HRESULT	Activate ()
HRESULT	Deactivate ()
HRESULT	DeactivateManagedWidgets ([in] GUID gGroupId,[in] IRcUndoRedoGroup *pUndoRedo)
HRESULT	QueryWidgetCache ([in] BSTR bstrWidgetName,[in] BSTR bstrAspectName,[out, retval] IRsWidgetCacheItem **pItem)
HRESULT	AddWidgetToCache ([in] IRnActiveWidget *pWidget)
HRESULT	InvalidateCache ([in] BSTR bstrNodeName)
HRESULT	RemoveWidget ([in] IRnActiveWidget *pWidget)
HRESULT	AddManagedWidget ([in] IRnActiveWidget *pWidget)
HRESULT	ReplaceManagedWidget ([in] IRnActiveWidget *pWidget,[in] IRcUndoRedoGroup *pUndoRedo)
HRESULT	UpdateActiveWidgets ([in] BSTR bszWidgetPrototype,[in] BSTR bszRelativePath,[in]CONID conid)
HRESULT	ReactivateWidgets ([in] BSTR bszWidgetPrototype)
HRESULT	GetActiveWidgetParameters ([out] IRdWidgetParameters **ppParams)
HRESULT	ActivateDefaultWidget ([in] IRcUndoRedoGroup *pUndoRedo)
HRESULT	SetSelection ([in] RtUlong uCount,[in] IRsNode **ppSelectionList)
HRESULT	SetSelectionList ([in] IRsObjectList *pList)
HRESULT	ForceSelectionOwner ([in] BSTR szOwner)
HRESULT	ResetSelection ()
HRESULT	IgnoreSelection ([in] RtUlong uCount)
HRESULT	SetGroupDependency ([in] GUID source_id,[in] GUID dependent_id)
HRESULT	RemoveGroupDependency ([in] GUID source_id,[in] GUID dependent_id)
HRESULT	GetActiveWidget ([out] IRnActiveWidget **ppActiveWidget)
HRESULT	CheckWidgetPrototypeActive ([in] BSTR szWidgetPrototype,[out] RtBool *pbActive)
HRESULT	EnableSelectionAutoHandling ([in] RtBool bActive)
HRESULT	GetManagedWidgetsCount ([out, retval] RtUlong *pdwCount)
HRESULT	GetManagedWidget ([in] RtUlong dwIndex,[out, retval] IRnActiveWidget **ppActiveWidget)
HRESULT	SetEventHandling ([in] RtBool bEnable)
HRESULT	CheckWidgetPrototypeGroupActive ([in] BSTR szWidgetPrototype,[in] GUID gGUID,[out] RtBool *pbActive)
HRESULT	RegisterWidgetSelectionHandler ([in] IRsWidgetSelectionHandler *pSelectionHandler)
HRESULT	UnregisterWidgetSelectionHandler ([in] IRsWidgetSelectionHandler *pSelectionHandler)
HRESULT	GetWidgetPrototypeInstance ([in] BSTR szWidgetProto,[out] IRnActiveWidget **ppWidgetInstance)
HRESULT	GetWidgetGroupSize ([in] GUID gGroupId,[out] RtUlong *dwNumWidgets)
HRESULT	GetWidgetGroupWidget ([in] GUID gGroupId,[in] RtUlong dwIndex,[out] IRnActiveWidget **ppWidget)

---

Detailed Description

IRnWidgetSubsystem provides managing of widgets stored inside it's encapsulator.

Widget subsystem supports two types of widget:

• Self handled.
  Self handled widgets need to be manualy activated and deactivated.
• Automatic (managed).

For Automatic widgets there exists internal state machine that according to selections activates widgets from /Select group.

• After widget subsystem receives selection notification, it searches all widgets in /Select group and activate best matching widget into Default context.
  This action is performed in all contexts (modes) but it can be overriden by IRsWidgetSelectionHandler interface by registering user handler using RegisterWidgetSelectionHandler.
  You can override default behavior if your widget handles selections from Link editor or other Rosetta parts and you don't want to close your widget on selection event.

• During undo/redo commands automatic selection events handling is disabled. Selection auto handling can be also overriden locally by setting changing selection owned by widgets or by ignoring selection events directly.

There are 2 types of automatic groups for managed widgets (you can define as many groups as you wish).

• Default setting contains WIDGETGROUP_MODE and WIDGETGROUP_VIEW.
• WIDGETGROUP_MODE consists of WIDGETGROUP_MODE_TOOLS and WIDGETGROUP_MODE_SUBTOOLS.

Whenever you activate widget to mode or view group:

• Widget subsystem deactivates all dependent contexts (including kernel tool manager tools).
• Thus changing of MODE group causes deactivation of it't tools and sub-tools.
• Similarly, deactivation of tools group deactivates subtools group too.

Remarks:

Deactivation rules are defined by SetGroupDependency commands.

---

Member Function Documentation

HRESULT IRnWidgetSubsystem::Activate

(

)

Activate widget subsystem.

Returns:

standard HRESULT processing can be applied to returned value

HRESULT IRnWidgetSubsystem::Deactivate

(

)

Deactivate widget subsystem.

Returns:

standard HRESULT processing can be applied to returned value

HRESULT IRnWidgetSubsystem::DeactivateManagedWidgets	(	[in] GUID	gGroupId,
		[in] IRcUndoRedoGroup *	pUndoRedo
	)

Deactivate managed widgets in specified group.

Parameters:

	gGroupId	[in] Widget group ID.
	pUndoRedo	[in] Widget group Undo/Redo command.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::QueryWidgetCache	(	[in] BSTR	bstrWidgetName,
		[in] BSTR	bstrAspectName,
		[out, retval] IRsWidgetCacheItem **	pItem
	)

Retrieve cached widget from widget cache.

Parameters:

	bstrWidgetName	[in] Name of the widget.
	bstrAspectName	[in] Active aspect.

Returns:

pItem Widget [out,retval] cache item.

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::AddWidgetToCache

(

[in] IRnActiveWidget *

pWidget

)

Add widget to cache.

Parameters:

pWidget

[in] Active widget to add to cache.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::InvalidateCache

(

[in] BSTR

bstrNodeName

)

Deactivate widget cache items that are dependent on specified node.

Parameters:

bstrNodeName

[in] Node name.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::RemoveWidget

(

[in] IRnActiveWidget *

pWidget

)

Deactivate widget.

Parameters:

pWidget

[in] Widget interface.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::AddManagedWidget

(

[in] IRnActiveWidget *

pWidget

)

Add widget to managed group.

Parameters:

pWidget

[in] Widget interface.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::ReplaceManagedWidget	(	[in] IRnActiveWidget *	pWidget,
		[in] IRcUndoRedoGroup *	pUndoRedo
	)

Deactivate widget group and add new widget.

Parameters:

	pWidget	[in] Widget interface
	pUndoRedo	[in] Widget Undo/redo group command.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::UpdateActiveWidgets	(	[in] BSTR	bszWidgetPrototype,
		[in] BSTR	bszRelativePath,
		[in] CONID	conid
	)

Update all active widgets after connector changed in their template node.

Parameters:

	bszWidgetPrototype	[in] Widget prototype node.
	bszRelativePath	[in] Relative path inside widget prototype.
	conid	[in] Changed connector ID.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::ReactivateWidgets

(

[in] BSTR

bszWidgetPrototype

)

Re-activate widgets that are created from specified template (for example after widget topology change).

Parameters:

bszWidgetPrototype

[in] Widget prototype node.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetActiveWidgetParameters

(

[out] IRdWidgetParameters **

ppParams

)

Get widget parameters for currently active widget.

Parameters:

ppParams

[out] Widget parameters.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::ActivateDefaultWidget

(

[in] IRcUndoRedoGroup *

pUndoRedo

)

Activate default widget.

Parameters:

pUndoRedo

[in] Widget undo/redo group command.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::SetSelection	(	[in] RtUlong	uCount,
		[in] IRsNode **	ppSelectionList
	)

Force selection to widget automatic management.

Parameters:

	uCount	[in] Number of nodes in selection.
	ppSelectionList	[in] Array of at the least uCount nodes.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::SetSelectionList

(

[in] IRsObjectList *

pList

)

Force selection to widget automatic management.

Parameters:

pList

[in] List of selected nodes.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::ForceSelectionOwner

(

[in] BSTR

szOwner

)

Force selection ownership to widget automatic management.

• Selection ownerships are used to detect if there exists widget that was activated as a response to selection change.

Parameters:

szOwner

[in] Owner widget name.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::ResetSelection

(

)

Clear internal widget automatic management selection.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::IgnoreSelection

(

[in] RtUlong

uCount

)

Set number of selection events to ignore.

Parameters:

uCount

[in] Number of events to ignore.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::SetGroupDependency	(	[in] GUID	source_id,
		[in] GUID	dependent_id
	)

Set widget groups dependency.

Parameters:

	source_id	[in] Parent group ID.
	dependent_id	[in] Children group ID.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::RemoveGroupDependency	(	[in] GUID	source_id,
		[in] GUID	dependent_id
	)

Remove widget groups dependency.

Parameters:

	source_id	[in] Parent group ID.
	dependent_id	[in] Children group ID.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetActiveWidget

(

[out] IRnActiveWidget **

ppActiveWidget

)

Return active widget (currently receiving mouse tool manager messages) if any.

Parameters:

ppActiveWidget

[out] Active widget.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::CheckWidgetPrototypeActive	(	[in] BSTR	szWidgetPrototype,
		[out] RtBool *	pbActive
	)

Check if widget is active or not.

Parameters:

	szWidgetPrototype	[in] Widget prototype name.
	pbActive	[out] True, if widget prototype is activated.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::EnableSelectionAutoHandling

(

[in] RtBool

bActive

)

Enable or disable selection auto handling.

• If handling is disabled, change of selection causes activation of appropriate widget from select group.
• To enable auto selection handling, you need to call enable auto handling the same number of times as it was disabled.

Parameters:

bEnable

[in] True to enable auto handling, false to disable.

Returns:

If selection handling is enabled, return is S_OK. Otherwise return is S_FALSE.

HRESULT IRnWidgetSubsystem::GetManagedWidgetsCount

(

[out, retval] RtUlong *

pdwCount

)

Get number of managed widgets.

Returns:

pdwCount [out,retval]] Number of managed widgets.

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetManagedWidget	(	[in] RtUlong	dwIndex,
		[out, retval] IRnActiveWidget **	ppActiveWidget
	)

Get managed widget by index.

• You must call GetManagedWidgetsCount to validate managed widgets list before retrieving managed widgets.

Parameters:

dwIndex

[in] Index of managed widget.

Returns:

ppActiveWidget [out,retval] Active managed widget.

standard HRESULT processing can be applied to returned value

HRESULT IRnWidgetSubsystem::SetEventHandling

(

[in] RtBool

bEnable

)

Enable/Disable event handling and automatic management of widget controlled objects lists.

• This message is spread to all active widgets.
• Note, that this state is not serialized and event handling should be disabled only for minimal period of time.

Parameters:

bEnable

[in] Set to true to enable handling, false to disable.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::CheckWidgetPrototypeGroupActive	(	[in] BSTR	szWidgetPrototype,
		[in] GUID	gGUID,
		[out] RtBool *	pbActive
	)

Check if any widget with specified prefix is active.

Parameters:

	szWidgetPrototype	[in] Widget prototype name.
	gGUID	[in] Widget group. Set to GUID_NULL to check for all groups.
	pbActive	[out] True, if widget prototype is activated.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::RegisterWidgetSelectionHandler

(

[in] IRsWidgetSelectionHandler *

pSelectionHandler

)

Register widget selection handler which are used to override global selection events - for example selecting in LE.

Parameters:

pSelectionHandler

[in] Handler to register.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::UnregisterWidgetSelectionHandler

(

[in] IRsWidgetSelectionHandler *

pSelectionHandler

)

Unregister widget selection handler.

Parameters:

pSelectionHandler

[in] Handler to unregister.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetWidgetPrototypeInstance	(	[in] BSTR	szWidgetProto,
		[out] IRnActiveWidget **	ppWidgetInstance
	)

Return first active widget from specified prototype.

Parameters:

	szWidgetProto	[in] Prototype name.
	ppWidgetInstance	[out] Returned active widget or NULL if none found.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetWidgetGroupSize	(	[in] GUID	gGroupId,
		[out] RtUlong *	dwNumWidgets
	)

Return number of widgets within specified group.

Parameters:

	gGUID	[in] Widget group ID.
	dwNumWidgets	[out] Number of widgets within specified group.

Returns:

standard HRESULT processing can be applied to returned value.

HRESULT IRnWidgetSubsystem::GetWidgetGroupWidget	(	[in] GUID	gGroupId,
		[in] RtUlong	dwIndex,
		[out] IRnActiveWidget **	ppWidget
	)

Return widget specified by group and index.

Parameters:

	gGUID	[in] Widget group ID.
	dwIndex	[in] Index of a widget within widget group to retrieve.
	ppWidget	[out] is filled with widget specified by group ID and index.

Returns:

standard HRESULT processing can be applied to returned value.