Show Hide

 

Feedback

  • Contents
 

II3IDTools::RegisterTool Method

Synopsis

Add a COM based tool to the collection and return its interface pointer.  The ProgID will be used as the tool's Module name.

IDL Function Prototype

HRESULT RegisterTool(

   [in] VARIANT ToolAddOnEventSink,

   [in] BSTR ToolLabel,

   [in]    BSTR ToolModuleName,

   [in]    BSTR ToolName,

   [in]    BSTR Description,

   [in]    BSTR Category,

   [in]    BSTR RuntimeDLLName,

   [in]    BSTR RuntimeDLLFuncName,long nbrParms,

   [in, otional] BSTR ToolVersion,

   [in, optional, defaultvalue(0)] BSTR HelpFileName,

   [in, optional, defaultvalue(0)] long HelpFileContext,

   [out, retval] II3IDTool ** NewTool

);

C/C++ Syntax

HRESULT RegisterTool(VARIANT ToolAddOnEventSink, BSTR ToolLabel, BSTR ToolModuleName, BSTR ToolName, BSTR Description, BSTR Category, BSTR RuntimeDLLName, BSTR RuntimeDLLFuncName,long nbrParms, BSTR ToolVersion, BSTR HelpFileName, long HelpFileContext, II3IDTool ** NewTool);

Parameters

ToolAddOnEventSink

ToolAddOnEventSink specifies the object that Interaction Designer should call back on with events specified in the II3IDToolAddOn interface. The variant should be one of the following:

  • VT_EMPTY / VT_NULL: Specify when you don't want any II3IDToolAddOn callbacks to occur.

  • VT_BSTR: The bstrVal contains a ProgID of a COM object that Designer should create that implements the II3IDToolAddOn interface.

  • VT_UNKNOWN: punkVal should be an IUnknown interface pointer that Designer can query for an II3IDToolAddOn interface pointer.

  • VT_DISPATCH: pdispVal should be an IDispatch interface pointer that Designer can query for an II3IDToolAddOn interface pointer.

ToolLabel

The label for the tool. The label should be localized because it is displayed to the Interaction Designer user for the tool on the tool palette.

ToolModuleName

The unchanging module name for the tool.

ToolName

The unchanging name of the tool.

NOTE: The module name/initiator pair name needs to be unique among all tools that are registered in Designer. Interaction Designer will fail to register a tool if there is another tool already registered with the same module/name combination.

Description

The localized description for the tool.

Category

The category determines what tab you would like for the tool to appear under on the main Designer window.

RuntimeDLLName

The name of the DLL that contains the 'RuntimeDLLFuncName' function.

RuntimeDLLFuncName

The name of the function to be called in the runtime DLL to be called at runtime to perform the desired functionality of the tool.

nbrParms

The number of registered parameters for instances of this tool.

ToolVersion

A version string that you can assign to the tool. This string does not have to be a number. If you change the registered tool version for a tool, then the II3IDStepEvents::StepOutOfSync method will be called for handlers opened that were saved with earlier versions of your tool.

HelpFileName

The name of a Windows help file that contains information about this tool.

HelpFileContext

The context ID number of a topic in the help file that describes this tool.

NewTool

The return value is an II3IDTool tool object.