Working with ActiveX Controls

ActiveX controls, formerly known as OLE controls or OCX controls, are software components (or objects) that can be embedded into Windows desktop applications built with environments such as C# or C++. The controls enable the reuse of packaged functionality which was developed independently. Embedding ActiveX controls in a web page was previously supported in Internet Explorer, but this has since been discontinued. See older TerraExplorer Programmer guides for more information.

All TerraExplorer components can run in embedded mode using ActiveX controls. The use of ActiveX controls in TerraExplorer enables you to embed the 3D Window, the Project Tree (Information Window), as well as external 3D Windows and external 3D Project Trees as ActiveX objects within a customized user interface.  

§  ITE3DWindow – Provides access to the 3D Window ActiveX control and keyboard override.

§  ITEInformationWindow – Provides access to the Information Window ActiveX control.

§  ITE3DWindowEx – Provides access to the external 3D Window Active X controls and allows creating SGWorld objects from them.  

§  ITEInformationWindowEx – Provides access to the Information Window  control for an attached 3DWindowEx control. 

The Navigation Map is no longer supported.

When you use the ActiveX component, you must use the 3D Window component. This launches TerraExplorer with the 3D Window displayed in the ActiveX display area, and without the standard TerraExplorer GUI. You can then also add the other ActiveX objects.

In-Process vs. Out-of-Process ActiveX Controls

TerraExplorer exposes both in-process and out-of-process ActiveX controls:

§  ITE3DWindow and ITEInformationWindow – When instantiated, these components are created as in-process DLL COM objects, i.e., they are loaded into the same executable as the host application. In-process objects enjoy the advantage of faster in-process COM communication with the host application. They also share resources with the host application, e.g. memory and CPU. Their main constraint is that the host application must be 64-bit, to allow the TE 64-bit DLL’s to be loaded into the same application.

§  ITE3DWindowExand ITEInformationWindowEx – When instantiated, these components are created as standalone out-of-process COM executables (one for each ITE3DWindowEx). This offers two main advantages: it enables the creation of multiple 3D windows in the same application (including one regular ITE3DWindow, and multiple 3DWindowEx’s) and supports hosting by both 64-bit and 32-bit applications. The downside of out-of-process objects is that COM communication may be slower when handling intensive calls and events.

Adding ActiveX Components in a C# Environment

C# allows you to easily add ActiveX controls to your application. TerraExplorer provides ActiveX controls for the 3D Window, Project Tree (Information Window), external 3D Window, and external Project Tree. Add them to your project and build your own custom GUI with embedded controls.

The instructions provided here refer to Microsoft Visual Studio 2017.

1.      Add the ActiveX components to the Toolbox – While in design view, right click on the Toolbox, and select Choose Items. In the dialog box select COM Components tab and select the check-boxes next to TE3DWindow Class, TEInformationWindow Class, TE3DWindowEx Class, and TEInformationWindowEx Class and then click OK. Four icons are added to your toolbox, the 3D Window , Project Tree (Information Window) , 3DWindowEx , and external Project Tree controls.

2.      Add any of the following elements to your form:

·        TE3DWindow Class – Click on the 3D Window control icon and draw the location of the 3D Window on your form.

·        TEInformationWindow Class – Click on the Project Tree control icon and draw the location of the Project Tree on your form.

·        TE3DWindowEx Class – Click on the 3DWindowEx control icon and draw the location for an external 3D window on your form. Repeat for each external 3D Window that you want to add.

·        TEInformationWindowEx Class – Click on the external Project Tree control icon and draw the location for an external Project Tree on your form. Repeat for each external Project Tree that you want to add.

3.      If you are using an external 3D window (ITE3DWindowEx), do the following:

a.      Create an SGWorld instance from the external 3D Window – Use ITE3DWindowEx.CreateInstance to create an instance of the 3D Window.

ISGWorld81 SGWorld = (ISGWorld81)axTE3DWindowEx1.CreateInstance("TerraExplorerX.SGWorld81");

b.      If you are using TEInformationWindowEx, attach it to the specific external 3D window – Use ITEInformationWindowEx.AttachTo3dWindow to attach the Project Tree to the specific 3D Window.

axTEInformationWindowEx1.AttachTo3dWindow((TE3DWindowEx)axTE3DWindowEx1.GetOcx());

Adding ActiveX Components in a C++ Environment

There are several ways in which a C++ client can work with the ActiveX controls. This document describes just one way of using the TerraExplorer from within a simple ATL dialog application.

1.      Derive your dialog from the ATL template class CAxDialogImpl.
This allows your dialog to host ActiveX controls, such as the 3D Window, the Information Window, the external 3D Window, and external Information Window.

Your dialog class should look something like this:

class CMyDialog :
              public CAxDialogImpl<CMyDialog>
{
public:

  :
  :
  :

};

You can use the Visual C++ "insertàNew ATL Object…" menu option to create your dialog. Select the "Dialog" object from the "Miscellaneous" category.

2.      Add any of the following to your project:

·        3D Window

·        Project Tree (Information Window)

·        External 3DWindow

·        External Project Tree

3.      Add the following members to your dialog class definition:

CAxWindow m_wnd3D;
CAxWindow m_wndInfoTree;
CAxWindow m_wnd3DEx;
CAxWindow m_wndInfoTreeEx;

CAxWindow is an ATL class that can be used to encapsulate ActiveX controls.
Add the following lines to your dialog OnInitDialog handler:

LPCTSTR pszTE3DName = _T("TerraExplorerX.TE3DWindow");
RECT rect1 = { 10, 10, 350, 250 };
m_wnd3D.Create(m_hWnd, rect1, pszTE3DName, WS_CHILD | WS_VISIBLE);

LPCTSTR pszTEInformationName = _T("TerraExplorerX.TEInformationWindow");
RECT rect2 = { 400, 10, 550, 250 };
m_wndInfoTree.Create(m_hWnd, rect2, pszTEInformationName, WS_CHILD | WS_VISIBLE);
 
LPCTSTR pszTE3DExName = _T("TerraExplorerX.TE3DWindowEx");
RECT rect4 = { 600, 10, 950, 250 };
m_wnd3DEx.Create(m_hWnd, rect4, pszTE3DExName, WS_CHILD | WS_VISIBLE);

 

LPCTSTR pszTEInfoTreeExName = _T("TerraExplorerX.TEInformationWindowEx");
RECT rect5 = { 600, 270, 950, 510 };
m_wndInfoTreeEx.Create(m_hWnd, rect5, pszTEInfoTreeExName, WS_CHILD | WS_VISIBLE);

 

The code lines above create the 3D Window control, Project Tree (Information Window) control, External 3D Window control and External Project Tree control.

At this point, if you compile and run your project, you should see that your dialog contains the 3D Window, Project Tree, external window, and external Project Tree (You can even start working by clicking on the 3D Window and pressing Ctrl+O to open a Fly file).