# 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.