CreateMessage

In TerraExplorer, a message is an object which is displayed in a container (e.g., pop-up window) and which defines a content type (e.g., HTML or simple text). The message is triggered when the user clicks on an object (or clicks on a Fly-To link to the object) which is associated with that message object. When a message object is triggered, the message content is displayed in the message-defined client.

Usually after creating a message object, the client associates it with an object by setting that object MessageID property to the ID of the newly created message (See ISingleMessageObject5::MessageID property). Several different objects can be associated to the same message object at the same time.

Note: When TerraExplorer runs as an ActiveX component (like in the SkylineGlobe web site) only the HTML Pop-up containers are visible to the user. However, in order to catch and analyze those messages you can target them to other containers.  To do so listen to the _ITerraExplorerEvents4::OnTerraExplorerMessage() event notification.

HRESULT CreateMessage (

[in] MsgClient Client,

[in] BSTR Data,

[in] MsgType Type,

[in, optional, defaultvalue(0)] _HTML_POPUP_FLAGS PopupFlags,

[in, optional, defaultvalue("")] BSTR PopupCaption,

[in, optional, defaultvalue(-1)] double PopupTimeout,

[in, optional, defaultvalue(0)] int PopupTopLeftX,

 [in, optional, defaultvalue(0)] int PopupTopLeftY,

[in, optional, defaultvalue(0)] int PopupWidth,

[in, optional, defaultvalue(0)] int PopupHeight,

[in, defaultvalue(FALSE)] BOOL BringToFront,

[out, retval] ITerraExplorerMessage5** pITerraExplorerMessage5)

Parameters:

• MsgClient – An enum that determines where, the message appears. The MsgClient enum has the following values:

• CLIENT_UPPER_LEFT = 0
  The message appears in TerraExplorer's upper left container.

• CLIENT_LOWER_LEFT = 1
  The message appears in TerraExplorer's lower left container.

• CLIENT_MAIN = 2
  The message appears in TerraExplorer's main container.

• CLIENT_MESSAGE_BAR = 3
  The message appears in TerraExplorer's message bar.

• CLIENT_FLOAT = 4
  The message appears in an external web browser.

• CLIENT_POPUP = 5
  The message appears in a floating pop-up window.

• Data – The message that is displayed. The MsgType parameter determines how this parameter is interpreted. If the MsgType parameter is set to TYPE_TEXT, this parameter is the text to be displayed. If MsgType parameter is set to TYPE_URL, this should be a full URL address (or a full path name) of a web page. If MsgType parameter is set to TYPE_ SCRIPT, this should be the content of the VBScript code.

• MsgType – An enum that determines whether the message is text, a URL or script. The MsgType enum has the following values:

• TYPE_TEXT = 0

• TYPE_URL = 1

• TYPE_SCRIPT = 3

• Pop-upFlags – The following flags can be used to customize the HTML Pop-up window:

• HTML_POPUP_ANCHOR_3D_WINDOW  = 1
  Defines whether the pop-up window moves when the 3D window changes position.

• HTML_POPUP_ALLOW_DRAG         = 2
  Enables users to drag and move the pop-up window.

• HTML_POPUP_NO_CAPTION         = 4
  Removes the caption area. Note – you still need to set a caption string to identify the window and remove it.

• HTML_POPUP_USE_DEFAULT_POS         = 8
  Places the window in its default position.

• HTML_POPUP_USE_LAST_SIZE     = 16
  Sets the window size according to the size of the last HTML pop-up window.

• HTML_POPUP_ALLOW_RESIZE         = 32
  Enables the users to resize the pop-up window.

• HTML_POPUP_ADD_SHADOW         = 64
  Adds a shadow to the pop-up window.
  Important – In some hardware and software configurations this feature may dramatically reduce performance.

• HTML_POPUP_NO_BORDER         = 128
  Removes the window border.

• HTML_POPUP_SET_FOCUS_TO_RENDER = 256
  Sets the focus to the 3D window after the message is triggered.

• HTML_POPUP_NOT_USE_POINTER = 512
  Displays the window without a pointer to the object.

• HTML_POPUP_ALWAYS_VISIBLE = 1024
  Defines whether the pop-up window is automatically hidden when the 3D window is not visible.

• HTML_POPUP_USE_LAST_POS = 2048
  Sets the window size according to the size of the last HTML pop-up window.

• PopupCaption – A caption string which is displayed on the pop-up window caption area. This parameter is also used as the pop-up window identifier. When using the same PopupCaption names, the new content replaces the content of the window with the same name. Use this parameter to remove the pop-up window using the IContainer2.RemoveURL method.

• PopupTimeout – Sets the timeout in seconds for closing the pop-up window. Use -1 to disable this feature.

• PopupTopLeftX – The top left X position of the window, in pixels, relative to the top left position of the 3D window.

• PopupTopLeftY – The top left Y position of the window, in pixels, relative to the top left position of the 3D window.

• PopupWidth – The bottom right X position of the window, in pixels, relative to the top left position of the 3D window. This value includes all captions and borders.

• PopupHeight – The bottom right Y position of the window, in pixels, relative to the top left position of the 3D window. This value includes all captions and borders.

• BringToFront – If the client for this message (i.e. the upper left container) already contains other items (i.e. Information Tree or HTML pages) those items appear in separate tabs. When this message is triggered, a message tab is added to that container (if the message tab already exists the message content replaces the content of the previous message). This parameter determines whether this tab becomes the active tab when the message is triggered. The parameter is ignored if MsgClient is not set to the CLIENT_UPPER_LEFT, CLIENT_LOWER_LEFT or CLIENT_MAIN.

• pITerraExplorerMessage5 – An interface pointer to the newly created message. This parameter must not be Null.

Return Values:

The return value obtained from the returned HRESULT can be one of the following:

Remarks:

Several objects can own the message object that is created by this method. A rectangle for example, may own a message object that is also owned (at the same time) by a circle object. This means that both objects, the rectangle and the circle, display the same message when clicked upon.