Working with Add-ins Chapter 24
CHAPTER 24
Working with Add-ins
This chapter describes how to create custom programs that are tightly integrated with Solid Edge.
Working with Add-ins—Overview 178
Implementing an Add-in 179
Working with the ISolidEdgeAddIn Interface 180
Working with ISEAddInEvents and DISEAddInEvents 183
Working with Solid Edge Objects, Interfaces, and Events 185
Solid Edge ST 224
Solid Edge ST Enhancements for Add-In GUI 225
Registering an Add-in 228
Registering an Add-in 209
The Solid Edge API provides an easy-to-use set of interfaces that enable programmers to fully integrate custom commands with Solid Edge. These custom programs are commonly referred to as add-ins. Specifically, Solid Edge defines an add-in as a dynamically linked library (DLL) containing a COM-based object that implements the ISolidEdgeAddIn interface. More generally, an add-in is a COM object that is used to provide commands or other value to Solid Edge.
The only restriction placed on an add-in is that the add-in must use standard Windows-based resources. An example of such a resource would be device-independent bitmaps to be added to the Solid Edge graphical user interface. You can create these resources using any of the popular visual programming tools that are available in the Windows programming environment—Visual C++ or Visual Basic, for example.
The following interfaces are available to the add-in programmer:
· ISolidEdgeAddIn—The first interface implemented by an add-in. Provides the initial means of communicating with Solid Edge.
· ISEAddInEvents and DISEAddInEvents—Provides command-level communication between the add-in and Solid Edge.
In addition, several Solid Edge interfaces are available once the add-in is connected to Solid Edge. These include ISEAddIn, ISECommand/DISECommand, ISECommandEvents/DISECommandEvents, ISEMouse/DISEMouse, ISEMouseEvents/DISEMouseEvents, ISEWindowEvents/DISEWindowEvents, and ISolidEdgeBar.
A Solid Edge add-in has the following requirements:
· The add-in must be a self-registering ActiveX DLL. You must deliver a registry script that registers the DLL and adds Solid Edge-specific information to the system registry.
· The add-in must expose a COM-creatable class from the DLL in the registry.
· The add-in must register the CATID_SolidEdgeAddin as an Implemented Category in its registry setting so that Solid Edge can identify it as an add-in.
· The add-in must implement the ISolidEdgeAddIn interface. The definition of this interface is delivered with the Solid Edge SDK (addins.h). The add-in can implement any additional interfaces, but ISolidEdgeAddIn is the interface that Solid Edge looks for.
· During the OnConnect call (made by Solid Edge on the add-in's ISolidEdgeAddIn interface), the add-in can add commands to one or more Solid Edge environments.
· If a graphical user interface (buttons or toolbars, for example) is associated with the add-in, then the add-in must provide a GUI version to be stored by Solid Edge. If the GUI version changes the next time the add-in is loaded, then Solid Edge will purge the old GUI and re-create it based on the calls to AddCommandBarButton with the OnConnectToEnvironment method. A GUI is an optional component of an add-in; some add-ins, for example, simply monitor Solid Edge events and perform actions based on those activities.
· You must follow COM rules and call AddRef on any Solid Edge pointers that the add-in is holding on to. You must also release the pointers when they are no longer needed. In Visual Basic, AddRef is done automatically by Set SEInterface = <Solid Edge interface>; to release the interface, set the interface to "Nothing."
· For Visual C++ users, a Solid Edge Add-in Wizard exists. The wizard is currently available for download from the Solid Edge web site. The wizard generates fully functional add-ins based on Microsoft's Active Template Library (ATL) for COM.
The ISolidEdgeAddIn interface is the first interface that is implemented by an add-in and provides the initial means of communication with Solid Edge. It allows for connection to and disconnection from an add-in. The implementation of this interface is what identifies a COM object as being a Solid Edge add-in.
HRESULT OnConnection( IDispatch *pApplication, seConnectMode ConnectMode, AddIn *pAddIn )
Solid Edge passes in a pointer to the dispatch interface of the Solid Edge application that is attempting to connect to the add-in. The add-in uses this pointer to make any necessary calls to the application to connect to Solid Edge event sinks, or to otherwise communicate with Solid Edge to perform whatever tasks the add-in needs when first starting up.
Solid Edge passes in a connect mode that indicates what caused Solid Edge to connect to the add-in. Current modes are as follows:
· seConnectAtStartUp—Loading the add-in at startup.
· seConnectByUser—Loading the add-in at user's request.
· seConnectExternally—Loading the add-in due to an external (programmatic) request.
Solid Edge also passes in a dispatch interface of a Solid Edge Add-in object that provides another channel of communication between the add-in and Solid Edge. An equivalent v-table form of this interface can be obtained by querying the input Add-in's dispatch interface for the ISEAddIn interface (also described in addins.h).
In general, the add-in needs to do very little needs when OnConnection is called. Here are a few basic steps that an add-in may want to perform during connection.
1. Connect to any Solid Edge application event sets the add-in plans on using by providing the appropriate sinks to the application object.
2. Connect to the Solid Edge Add-in object's event set if the add-in plans to add any commands to any environments.
3. Set the GUI version property of the Solid Edge Add-in object.
HRESULT OnDisconnection( SeDisconnectMode DisconnectMode )
Solid Edge passes in a disconnect mode that indicates what caused Solid Edge to disconnect to the add-in. Current modes are as follows:
· SeDisconnectAtShutDown—Unloading at shutdown.
· SeDisconnectByUser—Unloading the add-in due to a user request.
· SeDisconnectExternally—Unloading the add-in due to an external (programmatic) request.
To disconnect, the add-in should do the following:
4. Disconnect from any Solid Edge event sets it may have connected to.
5. Disconnect from the Add-in event set (if connected).
6. Release any other objects or interfaces the add-in may have obtained from the application.
7. Close any storage and/or streams it may have opened in the application's document.
8. Perform any other cleanup such as freeing any resources it may have allocated.
HRESULT OnConnectToEnvironment( BSTR EnvCatID, LPDISPATCH pEnvironment, VARIANT_BOOL* bFirstTime )
Solid Edge passes in the category identifier of the environment as a string. If the add-in is registered as supporting multiple environments, the add-in can use the string to determine which environment to which it is being asked to connect.
Solid Edge passes in the dispatch interface of the environment.
Solid Edge passes in the bFirstTime parameter to specify that a Solid Edge environment is connecting to the add-in for the first time. When connecting for the first time, the add-in, if necessary, should add any needed user interface elements (for example, buttons). On exiting, Solid Edge will save any such buttons so they can be restored during the next session.
To connect to a Solid Edge environment, the add-in will perform the following steps in its OnConnectToEnvironment:
1. The add-in should always call the SetAddInInfo method of the add-in interface passed to it during OnConnection if it provides any command bars or command bar buttons in the environment.
2. The add-in uses the bFirstTime parameter to determine if it is the first time the add-in has been loaded into the environment by checking to see if it is VARIANT_TRUE. If it is, the add-in should add any command bar buttons it needs to carry out its commands by calling the add-in interface's AddCommandBarButton method. If the add-in is not disconnected, and its GUI version has not changed the next time Solid Edge loads the add-in, then Solid Edge will set the parameter to VARIANT_FALSE because Solid Edge will save the data provided it by the add-in the last time the parameter was VARIANT_TRUE. Note that if the add-in's OnDisconnect function is called with a disconnect mode different from seDisconnectAtShutdown, this parameter will be VARIANT_TRUE the next time Solid Edge calls OnConnection. This happens because when an add-in is disconnected by the user or programatically, Solid Edge will purge all GUI modifications made by the add-in from all environments.
3. Add any commands not included in any of the calls to SetAddInInfo by calling the application's AddCommand method. Generally this method is used when a command is being added to the menu but not any command bar.
Note Command bars are persisted by Solid Edge when exiting. When an environment is first loaded, connection to the add-in is performed before the environment's command bars are loaded. This allows an add-in to call SetAddInInfo to supply any glyphs needed by any buttons that were previously saved by Solid Edge.
Add-ins cannot assume the existence of any particular environment, until this function is called with that environment's catid. Any calls with a catid for an environment that does not yet exist will be rejected.
When an add-in adds commands to a Solid Edge environment, a system of notifications must exist between the add-in and Solid Edge to enable and disable commands, invoke commands, and provide help for the commands. The ISEAddinEvents interface and its equivalent dispatch interface, DISEAddinEvents, serve this purpose.
One of these two interfaces is implemented by the add-in object and is used by Solid Edge to invoke commands added to Solid Edge by the add-in and to allow the add-in to perform basic user interface updates. The interface contains three methods: OnCommand, OnCommandUpdateUI and OnCommandHelp.
HRESULT OnCommand( long nCmdID )
Solid Edge calls this method, passing in nCmdID whenever the user invokes an add-in command. The value of the add-in command identifier passed in is the same value the add-in previously gave the AddIn object when it called its SetAddInInfo method.
When OnCommand is called, if the add-in wants to take advantage of the Solid Edge command control or mouse control, it can create a command object using the application's CreateCommand method. CreateCommand returns a DISECommand interface (from which the ISECommand equivalent v-table interface can be obtained).
HRESULT OnCommandUpdateUI( long nCmdID, long* pdwCmdFlags, BSTR Menutext, long *nIDBitmap)
Solid Edge calls this method, passing in nCmdID whenever it needs to determine the availability of a command previously added to Solid Edge by the add-in. The value of nCmdID will be one of the values the add-in previously passed in the SetAddInInfo method. The add-in uses the pointer to the dwCmdFlags bit mask to enable/disable the command and to notify Solid Edge to make other GUI changes. The values of the masks are as follows:
· seCmdActive_Enabled—Used to enable the command.
· seCmdActive_Checked—Used to add a check mark on the command's menu item.
· seCmdActive_ChangeText—Used to change the text that appears on the command's menu item.
· seCmdActive_UseDotMark—Used to add a dot mark on the command's menu item.
· seCmdActive_UseBitmap—Used to display the command's menu item as a bitmap.
Menutext can be used to change the text that appears on the menu. In order to change the text, allocate and return the desired text string. nIDBitmap can be used to have a bitmap appear on the menu next to the text.
Note After calling OnCommandUpdateUI, Solid Edge will determine whether seCmdActive_UseBitmap is set and if so, the returned value of nIDBitmap should represent the resource identifier of a bitmap stored in the resource DLL whose handle was passed in the SetAddInInfo method.
This method is called to determine if a command is enabled or disabled. It is called for commands visible on toolbars during idle processing, just before displaying a menu, when an accelerator is pressed, and when the application receives a WM_COMMAND message.
HRESULT OnCommandHelp(long hFrameWnd, long uHelpCommand, long nCmdID )
Solid Edge calls this method, passing in nCmdID whenever the user requests help for an add-in command previously added to Solid Edge by the add-in. The value of the add-in command identifier passed in will be one of the values the add-in gave the application when it previously called the SetAddInInfo method. If Solid Edge passes in -1, the add-in should call help for the add-in in general (that is, not help for a specific command).
The handle to the frame window, hFrameWnd as well as an indicator as to the type of help (uHelpCommand) is also passed in. These two parameters can be used in the WinHelp call and valid values of uHelpCommand are documented with the WinHelp function documentation.
Note When a command bar button is added, the dispatch interface of the button is returned. The interface contains help filename and context properties that can be set by the add-in. If set, these properties are used to invoke WinHelp directly from Solid Edge instead of calling OnCommandHelp.
This interface is passed into the add-in's OnConnection method. The Solid Edge objects that implement this interface are created one per add-in when Solid Edge starts up regardless of whether the add-in is loaded. These objects represent the add-in within Solid Edge. This same interface is exposed by means of the application's add-in's collection object. Because this interface is exposed to automation, some of the functions in the interface can only be called during the connection process, thus ensuring that only the add-in itself makes the calls.
· To return the dispatch interface of the application:
HRESULT get_Application( IDispatch **Application )
· To return the IUnknown of the connectable object that provides the ISEAddInEvents and DISEAddInEvents connection points:
HRESULT get_AddInEvents( AddInEvents **AddInEvents )
· To determine whether or not the add-in is connected. Connect is set to VARIANT_TRUE if the add-in is connected otherwise VARIANT_FALSE:
HRESULT get_Connect( VARIANT_BOOL *Connect )
· To programmatically connect to (VARIANT_TRUE) or disconnect from (VARIANT_FALSE) the add-in:
HRESULT put_Connect( VARIANT_BOOL Connect )
· To access a brief description of the add-in:
HRESULT get_Description( BSTR *Description )
· To set a brief description of the add-in. The description should be internationalized and also serves as the menu text of a tools pop-up menu that will be created if the add-in adds any commands to an environment. The put_Description can only be called successfully during initial connection:
HRESULT put_Description( BSTR Description )
Note: As of Solid Edge Version 9, the Description string can be used to indicate that the addin wants its menu to appear on the top-level of the Solid Edge main menu or as a pop-up menu under one of the common entries other than the tools menu. To get a new entry on the top-level menu, add a new line character (\n) to the beginning of the description. The pop-up menu can be placed under one of the common menu entries by concatenating one of the following strings (case insensitive) with the new line character and the description:
· FILE
· EDIT
· VIEW
· WINDOW
· HELP
· TOOLS
For example, if the description is “File\nMy Addin”, the file menu will contain a “My Addin” entry. A description of “\nMy Addin” will result in the top-level menu containing a “My Addin” entry.
· To get the add-in's guid in the string format defined by the Win API StringFromGUID. The CLSIDFromString Win API can convert the string back into its globally unique identifier form:
HRESULT get_GUID( BSTR *GUID )
· To get the version of the add-in as it relates to the user interface changes it makes in Solid Edge:
HRESULT get_GuiVersion( long *GuiVersion )
· ...
radziu667