Window (IWindow80)

The window property of the SGWorld interface is a wrapper for all the functionality that represents interaction with the 3D Window, such as snapshots, dimensions and query pixel information.

 

Properties

 

Cursor

Gets and sets the URL of a cursor to use in the 3D Window.

DisablePresentationControl

Gets and sets a Boolean that determines whether TerraExplorer should hide the onscreen presentation controls when a presentation is played.

Rect

An IScreenRect80 representing the size and position of the SGWorld window.

 

Methods

 

CenterPixelToWorld

Returns an IWorldPointInfo with information about the center pixel on the window: its real world coordinates, and the ID and type of the object positioned at that point.

GetControls

Returns the currently shown navigation controls.

GetInputMode

Returns the current input mode of the mouse.

GetMouseInfo

Returns information about the pointer position.

GetPopupByCaption

Returns an interface to the popup with the specified caption.

GetPopups

Returns a string array of captions of the currently open popups.

GetSnapShot

Returns a snapshot of the window

HideMessageBarText

Hides the text message in the Message Bar container.

PixelFromWorld

Returns an indication of whether a specified terrain coordinate falls in the 3D Window.

PixelToObjects

Returns a list of objects positioned at a specified pixel on the window.

PixelToWorld

Returns an IWorldPointInfo with information about a specified point on the window: its real world coordinates, and the ID and type of the object positioned at that point.

RemovePopup

Removes the popup window

RemovePopupByCaption

Removes the popup with a specified caption.

SetInputMode

Determines the input mode of the mouse.

ShowControls

Shows navigation controls and/or graphical and textual information in the 3D Window.

ShowMessageBarText

Displays the text message in the Message Bar container.

ShowPopup

Displays a popup window.

 

Cursor

Gets and sets the URL of a cursor to use in the 3D Window. Pass an empty string to restore the default cursor.

JavaScript

 

Cursor

 

C#

 

string Cursor { get; set; }

 

C++

 

HRESULT Cursor ([out, retval] BSTR* cursorURL)

HRESULT Cursor([in] BSTR cursorURL);

 

DisablePresentationControl

Gets and sets a Boolean that determines whether TerraExplorer should hide the onscreen presentation controls when a presentation is played.

JavaScript

 

DisablePresentationControl

 

C#

 

bool DisablePresentationControl { get; set; }

 

C++

 

HRESULT DisablePresentationControl ([out, retval] VARIANT_BOOL* pVal)

HRESULT DisablePresentationControl([in] VARIANT_BOOL pVal);

CenterPixelToWorld

Returns an IWorldPointInfo with information about the center pixel on the window: its real world coordinates, and the ID and type of the object positioned at that point.

 

JavaScript

 

CenterPixelToWorld(

       TypeFilterFlags)

 

C#

 

IWorldPointInfo80 CenterPixelToWorld(  

       WorldPointType TypeFilterFlags = WorldPointType.WPT_DEFAULT)

 

C++

 

HRESULT CenterPixelToWorld(

       WorldPointType TypeFilterFlags,

       IWorldPointInfo80 ** pWorldPointInfo) 

Parameters

TypeFilterFlags

This parameter can be any combination of the values below. An object that is positioned at the center pixel will be returned by IWorldPointInfo80.ObjectID only if its object type is one of the filter types passed.

·          WPT_TERRAIN = 0

·          WPT_MODEL = 1

·          WPT_LABEL = 2

·          WPT_PRIMITIVE = 4

·          WPT_ANIM = 8

·          WPT_BUILDING = 16

·          WPT_SKY = 32

·          WPT_ACCURATE_CPT = 64

·          WPT_BBOX_CPT = 128

·          WPT_VIDEO = 256

·          WPT_UNDERGROUND = 512

·          WPT_SCREEN_OVERLAY = 1024

·          WPT_SCREEN_CONTROL = 2048

·          WPT_SCREEN_COVERED = 4096

·          WPT_3DML = 8192

·          WPT_SURFACE = 65536

·          WPT_DEFAULT = -1

Return Value

pWorldPointInfo

An IWorldPointInfo80 representing information about the specified point. For an object type of WPT_SURFACE, null is returned for IWorldPointInfo80.ObjectID.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

GetControls

Returns the currently shown navigation controls.

 

JavaScript

 

GetControls()

 

C#

 

int GetControls()  

 

C++

 

HRESULT GetControls(

       long * controlFlags)

Return Value

controlFlags

The currently displayed navigation controls. This parameter can be any combination of the following values: 

·          HUD_LAYER_NONE                         = 0

·          HUD_LAYER_ACTIVE_ARROWS  = 1

·          HUD_LAYER_CENTER_SIGN         = 2

·          HUD_LAYER_TEXT_DATA              = 4

·          HUD_LAYER_COMPASS                 = 8

·          HUD_LAYER_GRAPHIC_1              = 16 (reserved)

·          HUD_LAYER_PAN_BARS                = 32

·          HUD_LAYER_DATE_TIME              = 64

·          HUD_LAYER_SCALE_BAR              = 128

·          HUD_LAYER_ZOOM_CONTROL  = 256

GetInputMode

Returns the current input mode of the mouse.

 

JavaScript

 

GetInputMode()

 

C#

 

MouseInputMode GetInputMode()

 

C++

 

HRESULT GetInputMode(

       MouseInputMode * InputMode)

Return Value

InputMode

An enum determining the mouse input mode. The MouseInputMode enum can use any of the following values:

·          MI_FREE_FLIGHT                             = 0

·          MI_COM_CLIENT                             = 1

·          MI_CONTROLLED_FLIGHT            = 2

·          MI_EDIT                                               = 3

·          MI_MEASUREMENT                       = 4

GetMouseInfo

Returns the mouse position and general mouse information.

 

JavaScript

 

GetMouseInfo()

 

C#

 

IMouseInfo80 GetMouseInfo()

 

C++

 

HRESULT GetMouseInfo(

       IMouseInfo80 ** pMouseInfo)

Return Value

pMouseInfo

An IMouseInfo80 representing the position of the mouse and general mouse information.

GetPopupByCaption

Returns an interface to the popup with the specified caption.

 

JavaScript

 

GetPopupByCaption(PopupCaption)

 

C#

 

IPopupMessage80 GetPopupByCaption(

       string PopupCaption)

 

C++

 

HRESULT GetPopupByCaption(

       BSTR PopupCaption,

       IPopupMessage80 ** pPopup) 

Parameters

PopupCaption

The caption of the required popup.

Return Value

pPopup

An IPopupMessage80 representing the HTML popup window.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

GetPopups

Returns a string array of captions of the currently open popups.

Note:    In JavaScript, use the VBArray object. E.g.,

var captions = SGWorld.Window.GetPopups()

var arr = new VBArray(captions).toArray();

See “Using the VBArray Object” for more information.

 

JavaScript

 

GetPopups

 

C#

 

dynamic GetPopups()

 

C++

 

HRESULT GetPopups(

       VARIANT* pVal) 

Return Value

pVal

String array of captions of the currently open popups.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

 

GetSnapShot

Returns a snapshot of the window.

 

JavaScript

 

GetSnapShot(

       toFile,

       Width,

       Height,

       Format,

       TerrainQuality)

 

C#

 

string GetSnapShot(

       bool   toFile = false,

       int    Width = 0,

       int    Height = 0,

       string Format = "",

       int    TerrainQuality = 0)

 

C++

 

HRESULT GetSnapShot(

       VARIANT_BOOL toFile,

       long   Width,

       long   Height,

       BSTR   Format,

       long   TerrainQuality,

       BSTR * pPath )

 

Parameters

toFile

A Boolean that indicates whether the snapshot should be saved to a file (TRUE) or whether a dialog window should be opened with the snapshot image.

Width

The width of the snapshot. If the width is not specified, the snapshot is created with the current 3D Window width.

Height

The height of the snapshot. If the height is not specified, the snapshot is created with the current 3D Window height.

Format

A string defining the format and compression of the image file. Use ”BMP” for a windows bitmap file, or “JPeg75" for a 75% JPEG image.

TerrainQuality

Defines how to get the required terrain database resolution for every snapshot. The following are the possible values for this property:

·          0 – Use the terrain database information that is currently in memory.

·          1 – Use the best resolution available in the MPT. Download and wait for additional information, if required.

Return Value

pPath

The path to the file where the snapshot was saved in the local temporary directory.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

HideMessageBarText

This method hides (but does not remove) the text message in the Message Bar container.

 

JavaScript

 

HideMessageBarText()

 

C#

 

void HideMessageBarText()

 

C++

 

HRESULT HideMessageBarText()

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

PixelFromWorld

This method returns an indication of whether a specified terrain coordinate is visible in the 3D Window. If it is visible, the screen coordinates of the specified pixel are returned.

 

JavaScript

 

PixelFromWorld(

       Position,

       Mode)

 

C#

 

IScreenPointInfo80 PixelFromWorld(

       IPosition80 Position,

       PixelFromWorldMode Mode = PixelFromWorldMode.PFW_IGNORE_Z_BUFFER)

 

C++

 

HRESULT PixelFromWorld(

       IPosition80 * Position,

       PixelFromWorldMode Mode,

       IScreenPointInfo80 ** pScreenPointInfo) 

Parameters

Position

The position of the specified coordinate, defined by its coordinates in the 3D World.

Mode

An enum that determines if the method takes obstructions into account in determining the visibility of  the world point. This following are the possible values:

·          PFW_IGNORE_Z_BUFFER = 0

Visibility check is made only for the world point. If the point is in the view, the result is TRUE even if it is obstructed by other objects or by the terrain.

·          PFW_USE_Z_BUFFER = 1

Visibility check is made for the world point taking into account other objects and all the terrain. If the point is in the view but obstructed by other objects or by the terrain the result is FALSE.

Return Value

PScreenPointInfo

An IScreenPointInfo80 representing the pixel and its visibility status in the 3D Window.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

PixelToObjects

Returns an ITerraExplorerObjects80 representing a list of objects that are positioned at a specified pixel on the window.

Note:    Currently, this method only returns ITerrainLabel80 or ITerrainImageLabel80 label objects.

Example in C#:

        private bool Globe_OnLButtonDown(int Flags, int X, int Y)
        {
            ITerraExplorerObjects80 objectsUnderCursor =  globe.Window.PixelToObjects(X, Y, WorldPointType.WPT_DEFAULT);
            foreach (dynamic teObj in objectsUnderCursor)
            {
                Console.WriteLine( ((ITerraExplorerObject80)teObj).ID);
            }
            return false;
        }

 

JavaScript

 

PixelToObjects(

       PixelX,

       PixelY,

       TypeFilterFlags)

 

C#

 

ITerraExplorerObjects80 PixelToObjects (

       int PixelX,

       int PixelY,

       WorldPointType TypeFilterFlags = WorldPointType.WPT_DEFAULT)

 

C++

 

HRESULT PixelToObjects (

       [in] long PixelX,

       [in] long PixelY,

       [in] WorldPointType TypeFilterFlags,

       [in] ITerraExplorerObjects80** pITerraExplorerObjects) 

 

Parameters

PixelX

The left-right coordinate in pixels of a specified point on the window.

PixelY

The top-bottom coordinate in pixels of a specified point on the window.

TypeFilterFlags

The following are the possible values for this parameter

·          WPT_LABEL                                        = 2

·          WPT_DEFAULT                                  = -1

Return Value

pITerraExplorerObjects

An ITerraExplorerObjects80 representing the objects positioned at the specified pixel on the window.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

 

PixelToWorld

Returns an IWorldPointInfo with information about a specified point on the window: its real world coordinates, and the ID and type of the object positioned at that point.

 

JavaScript

 

PixelToWorld(

       PixelX,

       PixelY,

       TypeFilterFlags)

 

C#

 

IWorldPointInfo80 PixelToWorld(

       int PixelX,

       int PixelY,

       WorldPointType TypeFilterFlags = WorldPointType.WPT_DEFAULT)

 

C++

 

HRESULT PixelToWorld(

       long PixelX,

       long PixelY,

       WorldPointType TypeFilterFlags,

       IWorldPointInfo80 ** pWorldPointInfo) 

 

Parameters

PixelX

The left-right coordinate in pixels of a specified point on the window.

PixelY

The top-bottom coordinate in pixels of a specified point on the window.

TypeFilterFlags

This parameter can be any combination of the values below. An object that is positioned at the specified point will be returned by IWorldPointInfo80.ObjectID only if its object type is one of the filter types passed. An object positioned at the specified point that is below the terrain or objects will be returned, as long as it is showing through the terrain or object based on its ShowThroughDistance.

·          WPT_TERRAIN                                  = 0

·          WPT_MODEL                                     = 1

·          WPT_LABEL                                        = 2

·          WPT_PRIMITIVE                               = 4

·          WPT_ANIM                                        = 8

·          WPT_BUILDING                                = 16

·          WPT_SKY                                             = 32

·          WPT_ACCURATE_CPT                    = 64

·          WPT_BBOX_CPT                              = 128

·          WPT_VIDEO                                       = 256

·          WPT_UNDERGROUND                   = 512

·          WPT_SCREEN_OVERLAY                = 1024

·          WPT_SCREEN_CONTROL              = 2048

·          WPT_SCREEN_COVERED              = 4096

·          WPT_3DML                                        = 8192

·          WPT_SURFACE                                 = 65536

·          WPT_DEFAULT                                  = -1

Return Value

pWorldPointInfo

An IWorldPointInfo80 representing information about the specified point, including its real world coordinates, and the ID and type of object positioned at the point. For an object type of WPT_SURFACE, null is returned for IWorldPointInfo80.ObjectID.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

RemovePopup

Specifies an instance of an IPopupMessage80 object up to be removed. The popup is removed and not simply hidden from view. 

 

JavaScript

 

RemovePopup(popup)

 

C#

 

void RemovePopup(

       IPopupMessage80 popup)

 

C++

 

HRESULT RemovePopup(

       IPopupMessage80 * popup)

 

Parameters

popup

An IPopupMessage80 representing the existing popup object that is to be removed.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

RemovePopupByCaption

Removes a popup with a specified caption. The popup is removed and not simply hidden from view.

 

JavaScript

 

RemovePopupByCaption(

       PopupCaption)

 

C#

 

void RemovePopupByCaption(

       string PopupCaption)

               

C++

 

HRESULT RemovePopupByCaption(

       BSTR   PopupCaption)

Parameters

PopupCaption

A string representing the caption of the popup that is to be removed.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

SetInputMode

This method determines the input mode of the mouse. Different input modes allow you to control the behavior of the mouse. For example, in free flight mode, clicking with the mouse on the various areas of the 3D Window, changes the camera’s yaw or tilt. This makes it hard to click a point on the terrain to place an object. Instead you can use the COM client mode that does not change the camera position.

.

JavaScript

 

SetInputMode(

       InputMode,

       cursorURL,

       AllowDrag)

 

C#

 

void SetInputMode(

       MouseInputMode InputMode,

       string cursorURL = "",

       bool AllowDrag = false)

 

C++

 

HRESULT SetInputMode(

       MouseInputMode InputMode,

       BSTR cursorURL,

       VARIANT_BOOL AllowDrag) 

 

Parameters

InputMode

Can be one of the following:

·          MI_FREE_FLIGHT                             = 0

·          MI_COM_CLIENT                             = 1

Note:    The other three modes returned by GetInputMode can only be set from the TerraExplorer GUI.

cursorURL

If the input mode is MI_COM_CLIENT, this parameter can specify the URL of a cursor to be displayed on the 3D Window.

AllowDrag

This parameter indicates whether the 3D Window can be moved by dragging it to another position on the screen.

Exceptions

HRESULT can return any of the values listed in the HRESULT Return Values list, as well as the following value:

TE_E_RENDER_WRONGINPUTMODE - Mouse input mode must be MI_COM_CLIENT for this method to take effect.

ShowControls

Shows navigation controls and/or graphical and textual information in the 3D Window.

 

JavaScript

 

ShowControls(controlFlags)

 

C#

 

void ShowControls(

       int controlFlags)

 

C++

 

HRESULT ShowControls(

       long   controlFlags)

Parameters

controlFlags

The currently displayed navigation controls. This parameter can be any combination

 of the following values: 

·          HUD_LAYER_NONE                         = 0

·          HUD_LAYER_ACTIVE_ARROWS  = 1

·          HUD_LAYER_CENTER_SIGN         = 2

·          HUD_LAYER_TEXT_DATA              = 4

·          HUD_LAYER_COMPASS                 = 8

·          HUD_LAYER_GRAPHIC_1              = 16 (reserved)

·          HUD_LAYER_PAN_BARS                 = 32

·          HUD_LAYER_DATE_TIME              = 64

·          HUD_LAYER_SCALE_BAR              = 128

·          HUD_LAYER_ZOOM_CONTROL  = 256

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

ShowMessageBarText

This method displays the text message in the Message Bar container.

 

JavaScript

 

ShowMessageBarText(

       Text,

       Alignment,

       Timeout)

 

C#

 

void ShowMessageBarText(

       string Text,

       MessageBarTextAlignment Alignment = MessageBarTextAlignment.MBT_CENTER,

       int Timeout = 5000)

 

C++

 

HRESULT ShowMessageBarText(

       BSTR   Text,

       MessageBarTextAlignment Alignment,

       long   Timeout) 

 

Parameters

Text

The text string that is to be displayed in the message bar.

Alignment

An enum determining the alignment of the message bar. The MessageBarTextAlignment enum can use any of the following values:

·          MBT_LEFT           = 0

·          MBT_CENTER    = 1

·          MBT_RIGHT       = 2

Timeout

Time in milliseconds, the message bar is displayed.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

ShowPopup

This method displays an HTML popup window that contains any text or HTML content.

 

JavaScript

 

ShowPopup(popup)

 

C#

 

void ShowPopup(

       IPopupMessage80 popup)

 

C++

 

HRESULT ShowPopup(

       IPopupMessage80 * popup)

 

Parameters

Popup

An IPopupMessage80 object representing the content and properties of the popup window

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.