Handling the Tool Lifetime Events
In this article
On Tool Start
Controlling the Other Tool Lifetime Events
Order of Tool Lifetime Events
This section describes how to handle tool and user interface initialization and unloading.
On Tool Start
When an add-in class is loaded, the first call to the class after instantiation is to OnToolStart. This method will contain references to the ISPWTool and ISPWToolUI objects, which can be used to communicate back to SharePoint Workspace. In your implementation of this method, you should call Show with a parameter that is a reference to your class implementing ISPWManagedToolAddinUI. In the template and samples, the ISPWManagedToolAddin, ISPWManagedToolAddinUI, and IRibbonExtensibility interfaces are implemented on the same UserControl class for simplicity. The following example shows the OnToolStart method in a project created from the template.
public void OnToolStart(ISPWTool i_SPWTool, ISPWToolUI i_SPWToolUI)
{
this.spwTool = i_SPWTool;
this.spwToolUI = i_SPWToolUI;
this.dataConnector = (SPWDataConnector)this.spwTool.DataConnector;
this.InitializeDataView();
this.spwToolUI.Show(this);
}
Controlling the Other Tool Lifetime Events
The ISPWTool interface provides access to an instance of SPWDataConnector, which is used to fetch and update the tool’s data. (See Accessing Tool Data for more information.) It also contains information about the application and workspace.
There are several other events that you can provide functionality for. In the template they are mostly empty for you to add your own logic when it is necessary:
OnToolActivate—called when the user opens the tool.
OnToolDeactivate—called when the user leaves the tool (that is, moves to another tool in the workspace).
OnToolBeforeUnload—called before the AppDomain of the control is unloaded. You should include any necessary tear-down here.
OnHide—called when the Add-In control is hidden.
OnShow—called when the Add-In control is displayed.
Order of Tool Lifetime Events
If a user opens a workspace and selects the add-in tool, or if a user opens an add-in tool in its own window, lifetime events are executed in the following order:
OnToolActivate() and OnShow are both executed before the tool is displayed to the user. OnToolActivate() is intended for initializing any structures needed for the business logic and OnShow is intended for initializing the user interface.
If a user is using the add-in tool and then closes the workspace, or if a user closes a window that contained the add-in tool, lifetime events are executed in the following order: