Creating Client Applications

The TerraExplorer Application Programming Interface (API) provides a powerful way of integrating TerraExplorer and custom applications. It also allows development of extensions that expand application functionalities and support for external information sources such as databases or geospatial files. TerraExplorer API is based on the COM standard, enabling communication between TerraExplorer and external applications. You can develop a client application that utilizes TerraExplorer COM capabilities by using scripting languages (e.g., JavaScript) within an HTML page or by using non-scripting languages (e.g., C++ or C#) in a stand-alone or DLL application. For creating a client application using embedded controls, see How to Work with ActiveX Controls.

SGWorld Object

TerraExplorer COM capabilities are incorporated into a web page using the SGWorld object that gives you access to all of its main interfaces. This integration involves two main steps: first, adding the initSGWorld function to your code, and second, instantiating the SGWorld object by calling this function.

 Follow these steps to create a JavaScript client application using TerraExplorer interfaces:

1.       Include initSGWorld Function: Copy the initSGWorld function below into your web page's script to enable the instantiation of the SGWorld object.

<script language="javascript">

function initSGWorld() {

   if(SGWorld != null) 

        return SGWorld;

 

    //Fusion -> use parent's instance (parent of IFrame)

    if (parent && parent.SGWorld) {

        SGWorld = parent.SGWorld;

 

        return SGWorld;

    }

   

    //Desktop -> create an instance

    try{

        SGWorld = new ActiveXObject("TerraExplorerX.SGWorld81");  //IE

    }

    catch(e){

        if(SGWorld == undefined)

        {

            SGWorld = __sgworld__.SetParamEx(9970, 81);           //EDGE

        }

    };

 

    return SGWorld;

}

</script>

2.       Instantiate SGWorld: Once initSGWorld is included, call the function to create an instance of SGWorld.

var SGWorld = initSGWorld("");

Note:     It is recommended to pass an empty string "" to get the latest version of SGWorld. For a specific version of SGWorld, consult that version's user guide for the correct clsid. TerraExplorer Fusion will always return the latest version regardless of the clsid passed.

3.       Access the main interfaces: The SGWorld object exposes an ISGWorld interface based on the parameter passed to initSGWorld. Using this interface you can access all the main TerraExplorer interfaces. For example, to zoom in you will need to call the INavigate81.ZoomIn method:

SGWorld.Navigate.ZoomIn();

See "Creating an HTML Client Application" in the "Examples in JavaScript" chapter for an example of how to initialize SGWorld and create a basic HTML to which to add the TerraExplorer COM interfaces using JavaScript.

Working with C++

 Create a new Win32 Console Application project in Visual Studio, using Visual C++:

1.       In Visual Studio, click Create a new project.

2.       Select a C++ Console Application.

3.       Name the project 'TerraExplorerShowcaseCPP'.

4.       Click OK and then click Create.

5.       Add the "#import" directive after the include statement to link your project to the TerraExplorer COM interface. It is used to incorporate TerraExplorer interfaces in your application. Make sure the name of the file in this command points to the TerraExplorer executable on your computer.

#import "C:\Program Files\Skyline\TerraExplorer Pro\TerraExplorerX.dll" no_namespace, named_guids, no_namespace rename("GetObject","GetTEObject")

6.       Initialize COM infrastructure inside your main method.

CoInitialize(NULL);
 {
 // Work with TerraExplorer here, using SGWorld class
 }
CoUninitialize();

7.       Create the SGWorld CoClass.

Note:     You must create a SGWorld81 CoClass before working with the interfaces. The constant CLSID_SGWorld81 is automatically defined by the "#import" command.

ISGWorld81Ptr pISGWorld;
pISGWorld.CreateInstance(CLSID_SGWorld81);

8.       Call the methods on the interface pointer.

pISGWorld->Project->Open("https://www.skylineglobe.com/SkylineGlobeLayers/SG_ExternalFlys/skylineglobe7.fly",FALSE,"","");
IPosition81Ptr pIPosition81 = pISGWorld->Creator->CreatePosition(-81.374173,28.537068,616.158537,AltitudeTypeCode::ATC_TERRAIN_RELATIVE, 312.967450,313.936515,0.0,0.0);
pISGWorld->Navigate->FlyTo(_variant_t((IDispatch*)pIPosition81),ActionCode::AC_FLYTO);

9.       Build and run the application.

Working with C#   

Using C# or any non-scripting language allows you to develop more complex and powerful client applications.

The instructions provided here refer to Microsoft Visual Studio 2017.

 Follow these steps to create a C# client application using TerraExplorer Interfaces:

1.       Set Project References – From the Project menu, select Add Reference. Select the COM tab,  locate TerraExplorerX 1.0 Type Library from the available references, select its check box, and then click OK.

Note:     When a reference to a COM component is added to a .NET project an interop DLL is automatically created. You can find "Interop.TerraExplorerX.dll" in the obj folder of your project. This DLL intermediates between the COM and .NET components.

2.       Add Using directive – To access types in the TerraExplorerX namespace.

using TerraExplorerX;

3.       Define Variable for SGWorld Object – Declare an SGWorld variable.

private SGWorld81 SGWorld;

4.       Create TerraExplorer Object – Use new to reference the variable to the SGWorld object.

this.SGWorld = new SGWorld81();

5.       Access the main interfaces – Using this object you can access all the main TerraExplorer interfaces. For example to zoom in you will need to call the INavigate81 ZoomIn method:

SGWorld.Navigate.ZoomIn();