How to Work with ActiveX Controls

This section describes the extended capabilities available by using the TerraExplorer ActiveX controls. The basics of creating a custom application are available in How to Work with the COM Interface in Chapter 1. Here you can find information on usage of the ActiveX components in the various environments.

Adding ActiveX Components

TerraExplorer exposes four separate ActiveX components, the 3D Window, the Project Tree, the external 3D Window, and the external Project Tree. These components are exposed through ActiveX Control technology. You can use the ActiveX controls in your custom user interface from an HTML page, with JavaScript, C# or C++ application, or any other environment that supports adding ActiveX objects.
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.

Note: Visual Studio, which is a 32-bit application, does not support using the form designer when embedding the 64-bit ITE3DWindow in the form. To use the form designer use an x86 project configuration (change configuration, save, reopen VS, reopen project). Then you can switch to x64 in order to build the x64 application. Alternatively you can design the form by code only.

Working with Scripting Languages

ActiveX can only be used in Internet Explorer since it is the only web browser that supports ActiveX controls. Most operating systems (even 64-bit ones) by default execute the 32-bit version of Internet Explorer, so generally you should use the ITE3DWindowEx (and ITEInformationWindowEx). If running 64-bit Internet Explorer, you can use the ITE3DWindow (and ITEInformationWindow). See “In-Process vs. Out-of-Process ActiveX Controls” in this chapter for more information. See also “Creating an HTML Client Application with an ActiveX Component” in the “Examples in JavaScript” chapter.

1. Define an External TerraExplorer3DWindowEx Object – Use the HTML Object tag to declare the object using TerraExplorer 3DWindowEx’s unique class ID and set its size.

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

var sgworld = TerraExplorer3DWindowEx.CreateInstance("TerraExplorerX.SGWorld80");

3. Define an External TerraExplorer3D Information Window (Project Tree) Object (Optional) – Use the HTML Object tag to declare the object using ITEInformationWindowEx’s unique class id.

4. Attach the Project Tree – Use ITEInformationWindowEx.AttachTo3dWindow to attach the Project Tree to the specific 3D Window.

TerraExplorerInformationWindowEx.AttachTo3dWindow(TerraExplorer3DWindowEx);

Working 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.

Note: Visual Studio, which is a 32-bit application, does not support using the form designer when embedding the 64-bit ITE3DWindow in the form. To use the form designer use an x86 project configuration (change configuration, save, reopen VS, reopen project). Then you can switch to x64 in order to build the x64 application. Alternatively you can design the form by code only.

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.

ISGWorld80 SGWorld = (ISGWorld80)axTE3DWindowEx1.CreateInstance("TerraExplorerX.SGWorld80");

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());

Working 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 = { 6000, 10, 350, 250 };
m_wnd3DEx.Create(m_hWnd, rect4, pszTE3DExName, WS_CHILD | WS_VISIBLE);

LPCTSTR pszTEInfoTreeExName = _T("TerraExplorerX.TEInformationWindowEx");
RECT rect5 = { 6000, 10, 350, 250 };
m_wndInfoEx.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).