Solid Edge ST Addins - Part I

• Download demo project - 18.87 KB

Table of Contents

• Introduction
• Overview
• The Solid Edge API
  • SDK
  • Type Libraries
  • Environment Categories
  • ISolidEdgeAddIn Interface
    • OnConnection
    • OnConnectToEnvironment
    • OnDisconnection
• Getting started
• Add Class - ATL Simple Object
• stdafx.h
• ExampleAddIn.h
• ExampleAddIn.cpp
• ExampleAddIn.rgs
• Debugging
• Conclusion
• Credits

Introduction

Solid Edge ST is a 3D CAD parametric feature solid modeling software that now features Synchronous Technology.  It runs on Microsoft Windows platforms and provides solid modeling, assembly modelling and drafting functionality for mechanical engineers.

Throughout its history, Solid Edge has supported 3rd party COM addins similar to Microsoft Office products.  Whether you're an engineer with C++ experience or a full-time programmer, this article will layout the details that you'll need to create your own custom Solid Edge addins.

In order to reference the SDK information discussed in this article, you must have Solid Edge ST installed.  If you want to purchase your own copy of Solid Edge ST, you will need to find a reseller.  One that I know of off hand is Swoosh Technologies. The actual cost of a seat of Solid Edge ST will vary on a number of factors.  I believe though the range is around $5000 - $6000, give or take a few thousand.

Overview

This article is the 1st of a series that I plan to create in order to bring people up to speed on creating Solid Edge addins. I will only demonstrate the bare minimum requirements to create an addin in this article. There are many things you can do with an addin and I will cover those in future articles.

While it is certainly possible to create an addin using any COM enabled programming language, I chose to keep it simple and focus on VC++ and ATL technologies. If you need MFC, WTL, etc. in your project, you can certainly add it yourself and expand on what I'm presenting here. I'll also note that it is also possible to use .NET to create COM Addins, but that's an entirely different article in itself with its own set of problems.

I also want to mention that while this article is written specifically for Solid Edge ST, the majority of the article is still valid for older releases of Solid Edge. The path to the Solid Edge installation directory will vary from release to release. New interfaces\method\properties may be referenced in this article that are not available in older releases.

The Solid Edge API

The Solid Edge API is a very large and robust COM based API.  Solid Edge can be automated using any modern COM enabled programming\scripting language.

SDK

When you install Solid Edge, you will have access to the SDK which can be found in "%PROGRAMFILES%\Solid Edge ST\SDK".  You will want to reference the following items in the SDK.

• \include\*.h
• \Samples\Addins\Doc\addin.doc
• Sesdk.chm

Type Libraries

In the following table, I have outlined the most significant portions of the Solid Edge API. Solid Edge offers other API's for various things but these are the most commonly used for addin development. All of the Solid Edge type libraries can be found in the "%PROGRAMFILES%\Solid Edge ST\Program" folder.

The SolidEdgeFramework type library is the base library. It contains everything you will need to create a Solid Edge addin. Specifically, we will implement the ISolidEdgeAddIn interface. This interface is analogous to Microsoft's IDTExtensibility2 interface for creating Office addins.

Environment Categories

Solid Edge has many possible environments that addin developers need to account for. These CATID's are documented in the "%PROGRAMFILES%\Solid Edge ST\SDK\include\secatids.h" include. This information is important later in the article when I discuss the ExampleAddIn.rgs registry script.

You can use CATID_SEApplication when you want your addin to work outside of a specific environment. For example, when you first start Solid Edge and no documents are open. You can also use CATID_SEAllDocumentEnvrionments when you want your addin to work in all document environments, even future document environments that do not currently exist. Similarly, you can use CATID_SEAll to support all environments, even future environments that do not currently exist.

The following table describes the possible Environment Categories.

ISolidEdgeAddIn Interface

The ISolidEdgeAddIn interface is the interface that all Solid Edge addins must implement to be recognized by Solid Edge. It has 3 methods that get called by Solid Edge back into your addin. You can also reject the loading of your addin by returning any HRESULT other than S_OK in OnConnection.

HRESULT OnConnection( IDispatch *pApplication, seConnectMode ConnectMode, AddIn *pAddIn )

pApplication

SolidEdgeFramework::Application pointer to the dispatch interface of the Solid Edge application that is attempting to connect to the addin. The addin 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.

ConnectMode

Connect mode that indicates what caused Solid Edge to connect to the addin. The possible values are:

• seConnectAtStartUp - Loading the addin at startup.
• seConnectByUser - Loading the addin at user's request.
• seConnectExternally - Loading the addin due to an external (programmatic) request.

pAddIn

SolidEdgeFramework::AddIn pointer to the dispatch interface of a Solid Edge addin object that provides another channel of communication between the addin and Solid Edge.

HRESULT OnConnectToEnvironment( BSTR EnvCatID, LPDISPATCH pEnvironment, VARIANT_BOOL* bFirstTime )

EnvCatID

The category identifier of the environment as a string. If the addin is registered as supporting multiple environments, the addin can use the string to determine which environment to which it is being asked to connect.

pEnvironment

SolidEdgeFramework::Environment pointer to the dispatch interface of the environment.

bFirstTime

The bFirstTime parameter specifies that a Solid Edge environment is connecting to the addin for the first time. When connecting for the first time, the addin, 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.

HRESULT OnDisconnection( SeDisconnectMode DisconnectMode )

DisconnectMode

Disconnect mode that indicates what caused Solid Edge to disconnect from the addin. The possible values are:

• seDisconnectAtShutdown - Unloading at shutdown.
• seDisconnectByUser - Unloading the addin due to a user request.
• seDisconnectExternally - Unloading the addin due to an external (programmatic) request.

Getting started

To get started, you will need to create a Visual C++ ATL Project as shown below.

You can check the "Allow merging of proxy/stub code" for convenience.

Now that your project is created, you will want to modify the project properties. By setting the debugging command to Edge.exe, you will be able to debug you addin real-time in Solid Edge.

You will also want to add the "%PROGRAMFILES%\Solid Edge ST\SDK\include" path to your additional include directories setting. This will allow us to bring in the secatids.h include.

Add Class - ATL Simple Object

The next step is to execute the Add Class wizard on the project. You'll need to add an ATL Simple Object to your project. This class will ultimately implement the ISolidEdgeAddIn interface.

stdafx.h

Next, you'll need to modify your stdafx.h to include the SolidEdgeFramework type library. You can add the #import statement at the bottom of stdafx.h as shown below. Note the way that I use #import, the type library information is obtained via the registry. This keeps us from having to define project paths to the type libraries manually. The libid can be extracted using oleview.exe which is found in %VS80COMNTOOLS% for Visual Studio .NET 2005.

// stdafx.h : include file for standard system include files,
// or project specific include files that are used frequently,
// but are changed infrequently

#pragma once

#ifndef STRICT
#define STRICT
#endif

// Modify the following defines if you have to target a platform prior to the ones specified below.
// Refer to MSDN for the latest info on corresponding values for different platforms.
#ifndef WINVER                // Allow use of features specific to Windows XP or later.
#define WINVER 0x0501         // Change this to the appropriate value to target other versions of Windows.
#endif

#ifndef _WIN32_WINNT          // Allow use of features specific to Windows XP or later.                   
#define _WIN32_WINNT 0x0501   // Change this to the appropriate value to target other versions of Windows.
#endif                        

#ifndef _WIN32_WINDOWS        // Allow use of features specific to Windows 98 or later.
#define _WIN32_WINDOWS 0x0410 // Change this to the appropriate value to target Windows Me or later.
#endif

#ifndef _WIN32_IE             // Allow use of features specific to IE 6.0 or later.
#define _WIN32_IE 0x0600      // Change this to the appropriate value to target other versions of IE.
#endif

#define _ATL_APARTMENT_THREADED
#define _ATL_NO_AUTOMATIC_NAMESPACE

#define _ATL_CSTRING_EXPLICIT_CONSTRUCTORS    // some CString constructors will be explicit


#include "resource.h"
#include <atlbase.h>
#include <atlcom.h>
#include <initguid.h>

using namespace ATL;

#pragma warning( disable : 4278 )
#pragma warning( disable : 4146 )

#include "secatids.h"

#import "libid:8A7EFA3A-F000-11D1-BDFC-080036B4D502" exclude ("UINT_PTR", "LONG_PTR")
using namespace SolidEdgeFramework;

#pragma warning( default : 4146 )
#pragma warning( default : 4278 )
    

ExampleAddIn.h

You will need to modify your ExampleAddIn.h to look like the following. Specifically, note the addition of the ISolidEdgeAddIn interface implementation. I've also added a couple of private smart pointers for later use.

// ExampleAddIn.h : Declaration of the CExampleAddIn

#pragma once
#include "resource.h"       // main symbols

#include "CodeProjectExample.h"


#if defined(_WIN32_WCE) && !defined(_CE_DCOM) && !defined(_CE_ALLOW_SINGLE_THREADED_OBJECTS_IN_MTA)
#error "Single-threaded COM objects are not properly supported on Windows CE platform..."
#endif


// CExampleAddIn
class ATL_NO_VTABLE CExampleAddIn :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CExampleAddIn, &CLSID_ExampleAddIn>,
    public IExampleAddIn,
    public ISolidEdgeAddIn
{
public:
    CExampleAddIn()
    {
    }

    DECLARE_REGISTRY_RESOURCEID(IDR_EXAMPLEADDIN)
    DECLARE_NOT_AGGREGATABLE(CExampleAddIn)

    BEGIN_COM_MAP(CExampleAddIn)
        COM_INTERFACE_ENTRY(IExampleAddIn)
        COM_INTERFACE_ENTRY(ISolidEdgeAddIn)
    END_COM_MAP()

    DECLARE_PROTECT_FINAL_CONSTRUCT()

    HRESULT FinalConstruct()
    {
        return S_OK;
    }

    void FinalRelease()
    {
    }

private:
    /* local smart pointers */
    SolidEdgeFramework::ApplicationPtr m_pApplication;
    SolidEdgeFramework::ISEAddInPtr m_pAddIn;
    SolidEdgeFramework::ISEAddInExPtr m_pAddinEx;

public:
    /* ISolidEdgeAddIn members */
    STDMETHOD(raw_OnConnection)( THIS_ IDispatch* pAppDispatch, SeConnectMode ConnectMode, SolidEdgeFramework::AddIn* pUnkAddIn );
    STDMETHOD(raw_OnConnectToEnvironment)( BSTR EnvironmentCatid, LPDISPATCH pEnvironment, VARIANT_BOOL bFirstTime );
    STDMETHOD(raw_OnDisconnection)( THIS_ SeDisconnectMode DisconnectMode );
};

OBJECT_ENTRY_AUTO(__uuidof(ExampleAddIn), CExampleAddIn)
    

ExampleAddIn.cpp

You will need to modify your ExampleAddIn.cpp to look like the following. I added a bit of skeleton code to demonstrate the usage.

// ExampleAddIn.cpp : Implementation of CExampleAddIn

#include "stdafx.h"
#include "ExampleAddIn.h"


// CExampleAddIn

STDMETHODIMP CExampleAddIn::raw_OnConnection( IDispatch *pAppDispatch, SeConnectMode ConnectMode, AddIn* pAddIn )
{
    HRESULT hr = S_OK;

    /* Assign smart pointers */
    m_pApplication = pAppDispatch;
    m_pAddIn = pAddIn;
    m_pAddinEx = pAddIn;  /* This QueryInterface() will fail on pre ST builds */
    
    // Set the gui version. If the version changed since the last time 
    // addin was connected, SE will purge any gui related to 
    // this it and force bFirstTime to VARIANT_TRUE when calling 
    // OnConnectToEnvironment.
    m_pAddIn->GuiVersion = 1;

    /* Unremark if you want to hide the addin from addin manager. */
    // m_pAddIn->Visible = VARIANT_FALSE;

    /* Handle connect mode if required */
    switch (ConnectMode)
    {
    case SolidEdgeFramework::seConnectAtStartup:
        break;
    case SolidEdgeFramework::seConnectByUser:
        break;
    case SolidEdgeFramework::seConnectExternally:
        break;
    }

    return hr;
}

STDMETHODIMP CExampleAddIn::raw_OnConnectToEnvironment( BSTR EnvironmentCatid, LPDISPATCH pEnvironment, VARIANT_BOOL bFirstTime )
{
    HRESULT hr = S_OK;

    CLSID clsidEnv;
    CLSIDFromString(EnvironmentCatid, &clsidEnv);
    
    /* If you need to handle a specific environment, do the following. */
    if (IsEqualCLSID(clsidEnv, CATID_SEApplication))
    {
        /* Do something specific for this environment. */
    }

    return hr;
}

STDMETHODIMP CExampleAddIn::raw_OnDisconnection( SeDisconnectMode DisconnectMode )
{
    HRESULT hr = S_OK;

    /* Handle disconnect mode if required */
    switch (DisconnectMode)
    {
    case SolidEdgeFramework::seDisconnectAtShutdown:
        break;
    case SolidEdgeFramework::seDisconnectByUser:
        break;
    case SolidEdgeFramework::seDisconnectExternally:
        break;
    }

    /* Free smart pointers */
    m_pAddIn = NULL;
    m_pApplication = NULL;

    return hr;
}
    

ExampleAddIn.rgs

The .rgs registry script gets executed when regsvr32.exe is executed for the .dll. It adds all of the required registry entries that enable Solid Edge to see the addin. Specifically, the Implemented Categories entry is what allows Solid Edge to recognize our .dll as a Solid Edge addin.

For the possible Environment Categories, you can refer to the secatids.h include or the Environment Categories table in this article.

HKCR
{
    CodeProjectExample.ExampleAddIn.1 = s 'ExampleAddIn Class'
    {
        CLSID = s '{B66BA526-53E5-41B1-9620-AB7945F57155}'
    }
    CodeProjectExample.ExampleAddIn = s 'ExampleAddIn Class'
    {
        CLSID = s '{B66BA526-53E5-41B1-9620-AB7945F57155}'
        CurVer = s 'CodeProjectExample.ExampleAddIn.1'
    }
    NoRemove CLSID
    {
        ForceRemove {B66BA526-53E5-41B1-9620-AB7945F57155} = s 'ExampleAddIn Class'
        {
            val 409 = s 'Code Project Example AddIn'
            val AutoConnect = d 1
            
            ProgID = s 'CodeProjectExample.ExampleAddIn.1'
            VersionIndependentProgID = s 'CodeProjectExample.ExampleAddIn'
            
            ForceRemove 'Environment Categories'
            {
                ForceRemove '{26618394-09D6-11d1-BA07-080036230602}' = s 'CATID_SEApplication'
                ForceRemove '{BAD41B8D-18FF-42c9-9611-8A00E6921AE8}' = s 'CATID_SEAllDocumentEnvrionments'
            }

            ForceRemove 'Implemented Categories'
            {
                ForceRemove '{26B1D2D1-2B03-11D2-B589-080036E8B802}' = s 'CATID_SolidEdgeAddIn'
            }

            InprocServer32 = s '%MODULE%'
            {
                val ThreadingModel = s 'Apartment'
            }
            
            Summary
            {
                val 409 = s 'Code Project Example AddIn Description'
            }
            
            val AppID = s '%APPID%'
            'TypeLib' = s '{7AA65125-937A-40F5-9F85-44FA48617F46}'
        }
    }
}

    

Debugging

Assuming that you're able to compile the code successfully, you can now begin debugging the project and see how the addin works. What I typically do is set a breakpoint on the first line of code in the OnConnection, OnConnectToEnvironment and OnDisconnection methods.

Since we've configured our addin to connect to the CATID_SEApplication environment category, you should hit the OnConnection almost immediately.

Once you're in Solid Edge, you can verify that your addin is correctly registered by opening the Add-In Manager. The Add-In Manager will only display registered Environments that are explicitly set. Since we used the generic CATID_SEAllDocumentEnvrionments in the .rgs registry script, those environments are not displayed. In this example, only the CATID_SEApplication is displayed.

Conclusion

This article was written to target the bare minimum requirements for writing Solid Edge addins. It does not cover other very important topics as those will be discussed in later articles. My goal is to create step-by-step articles that are easy to understand and that build upon each other in the series.

If you've followed the step-by-step instructions in this article, you should not have any trouble getting up to speed quickly. You can also download the attached example which should compile without much effort.

Credits

Siemens PLM Software - Portions of this article are reused from existing Solid Edge SDK documentation.
R.D. Holland - R.D. is a Software Engineer at Siemens PLM Software. He is THE MAN when it comes to Solid Edge addins. I would not have had as good of an understanding of this topic if it were not for R.D.'s help.
John Hilton - John is the owner of Spatial Freedom and is the inventor of the Astroid 3D motion controller. John basically taught me C++ programming so he also deserves credit for the article.

History

2/21/2009 - Initial Release