XML File Structure and Example XML

Elements	Description
<Tool>	Defines a new tool.
<Container>	Defines the window where the tool is displayed.
<Ribbon>	Defines a new ribbon command.
<Submenu>	Defines a drop-down menu for the ribbon command.
<Item>	Defines a sub-command that is added to the drop-down menu.
<file>	Registers COM DLLs.

Example XML

<Iconpath="MyAddon.ico"/>

<RibbonShow="1" Toggle="0" splitButton="1">

<GroupTitle>MyGroup1</GroupTitle>

</Item>

</Item>

<GroupTitle>MyGroup2</GroupTitle>

</Item>

</Submenu>

</Ribbon>

</Container>

</Tool>

<Tool>

This element defines a new tool.

Attributes

Attribute	Description
AutoStart	Determines whether the tool is automatically launched when opening a FLY project. The Auto Start applies for regular panel, popup, and hidden tools. § AutoStart = 0 (Default) – Tool is not automatically launched. § AutoStart = 1 · When NeedProject is set to 0, tool will automatically launch when TerraExplorer starts. · When NeedProject is set to 1, tool is automatically launched only when TerraExplorer project is opened.
Caption	The name of the tool as it should be displayed on the ribbon command and on the tool window.
Id	Uniquely identifies the ribbon command.
NeedProject	Determines whether the ribbon button is disabled if no project is currently open in TerraExplorer: § NeedProject = 0 (Default) – Ribbon button is enabled even when no project is open. § NeedProject = 1 – Ribbon button is disabled when no project is open.
Path	Path to the HTML page (tool) that opens when the ribbon command is executed. Note: The path should include the group’s folder, e.g. “MyToolFolder\MyTool.html.”
RunOnce	Determines whether the tool is set to run only once. § RunOnce = 0 (Default) – Tool can run every time TerraExplorer is opened. § RunOnce = 1 - Tool runs once. Note: This attribute only applies to TEZ files that are installed using the Add-ons tab in the TerraExplorer Options dialog box.
ShowOnVersionTypes	Defines which of the applications in the TerraExplorer family should display this custom tool command. The attribute value can be any combination of the following values: § Display in TerraExplorer Pro = 1 § Display in TerraExplorer Plus = 2 § Display in TerraExplorer Viewer = 4 Use a combination of the values above to display the tool in multiple applications, e.g. to display the tool in both TerraExplorer Pro and Plus, but not Viewer, use ShowOnVersionTypes = 3. This attribute is not mandatory and if it does not appear in the tool.xml, the tool will be displayed in all TerraExplorer applications.
UseEdge	Boolean that determines whether the tool opens in the Edge browser.

Child Elements

Element	Description	Element’s Attributes
<Icon>	Defines an icon for the new ribbon command.	path - Path to the icon that is displayed on the new ribbon button.

<Container>

Child Elements

Element	Description	Element’s Attributes
<Panel>	Set tool in bottom left panel.
<Popup>	Set tool as a popup window and designate window’s position and size. Note: A project must be currently open in TerraExplorer.	X - Left x-coordinate where the pop-up will be displayed relative to the 3D Window. Y - Top y-coordinate where the pop-up will be displayed relative to the 3D Window. Width – Width, in pixels, of the popup window. Height – Height, in pixels, of the pop-up window. ShowCaption – Determines whether a caption is used for the popup window: § ShowCaption = “0” – No tool caption is displayed on the top of the popup window. § ShowCaption = “1” – The tool caption defined by the <Tool> Caption attribute is displayed on the top of the popup window.
<Hidden>	Set tool with hidden window. Note: A project must be currently open in TerraExplorer.

<Ribbon>

Attributes

Attribute	Description
Show	Determines whether there is a ribbon entry for the tool. § Show = “0” – Button does not display on ribbon. § Show = “1” (Default)– Button displays on ribbon.
splitButton	Determines whether the button is split into two halves where clicking the bottom half of the button opens a drop-down menu with sub-options, while clicking the upper half activates the “main” tool option, which will also be listed first in the drop-down menu: § splitButton = “0” - Button only opens a drop-down menu. § splitButton = “1” (Default) Creates a button with two halves with functionality described above.
Toggle	Determines whether the ribbon command is a toggle button: § Toggle = “1” – The button functions as a toggle for opening and closing the tool. § Toggle = “0” (Default) – Clicking the ribbon button always launches the tool. When the tool is already open, clicking the button has no effect.

Child Elements

Element	Description	Element’s Attributes
<Category>	Defines the new ribbon tab in which the new ribbon command should be placed. If no Category tag is specified, the new ribbon command is placed in the Tools tab.	id – Uniquely identifies the ribbon tab. caption – Name of the new ribbon tab.-
<Panel>	Defines the ribbon group in which the new ribbon command should be placed. If this group does not yet exist, it is created. If no Panel tag is specified, the new ribbon command is placed in a default Tools group.	id - Uniquely identifies the ribbon group. caption –Name of the ribbon group as it should be displayed on the ribbon.
<Submenu>	Defines a drop-down menu for the ribbon command.	See "<Submenu>” below.
<ToolTip>	Defines a tooltip that is displayed when placing the mouse cursor over the ribbon command.	title – Title of the tooltip. description – Text of the tooltip.

<Submenu>

This element defines a drop-down menu for the ribbon command.

Child Elements

Element	Description	Element’s Attributes
<Item>	Adds a command to the drop-down menu. If no <Item> tags are used, the drop-down menu only contains the “main” tool option that is displayed and can be activated by clicking on the button itself.	See "<Item>” below.
<Separator>	Creates a horizontal divider line in the drop-down menu.
<GroupTitle>	Defines a heading in the drop-down menu.

<Item>

This element defines a sub-command that is added to the drop-down menu. If no <Item> tags are used, the drop-down menu only contains the “main” tool option that is displayed and can be activated by clicking on the button itself.

Attributes

Attribute	Description
Caption	Name of the command as it should be displayed on the ribbon’s drop-down menu.
id	Uniquely identifies the command that is being added to the drop-down menu.
Path	Path to the HTML page (tool) that opens when the command on the drop-down menu is clicked.
NeedProject	Determines whether the ribbon button is disabled if no project is currently open in TerraExplorer: § NeedProject = 0 (Default) – Ribbon button is enabled even when no project is open. § NeedProject = 1 – Ribbon button is disabled when no project is open.

Child Elements

Element	Attributes	Description
<Container>	Defines the window where the tool is displayed. Note: If the <Container > element appears under the parent element, it overrides the <Container > element of the child element	See “<Container>” above.
<ToolTip>	title – Title of the tooltip. description – Tooltip text.	Defines a tooltip that is displayed when placing the mouse cursor over the command on the drop-down menu.
<Icon>	path - Path to the icon that is displayed on the new ribbon button.	Defines an icon for the command on the drop-down menu.

<file>

Registers specified COM objects from DLL files.

Attributes

Attribute	Description
name	Name of the COM DLL file.

Child Elements

Element

Description

Element’s Attributes

Defines the com object to register.

clsid – COM object class ID.

iid – Interface ID

event_iid – Events ID (optional)

tlbid – Type library ID

Note: The DLL should be digitally signed so that the user does not receive an ActiveX security warning when using it from an HTML page.

Note: In order for the in-memory registration to work, when creating the DLL (at least from ATL C++), use the following syntax when inheriting the object ATL class implementation from IDispatchImpl<> template: class ATL_NO_VTABLE CMyComClass : public CComObjectRootEx<CComSingleThreadModel>, public IDispatchImpl<IMyComClass, &IID_IMyComClass, &_LIBID_MyComClassLib, -1, -1> (Note the -1,-1 parameters at the end instead of the default 1, 0).

Note: All IDs should be in {} e.g. comClass clsid="{DF73AE6A-6DDD-4276-A26E-6CB8B28FE71A}"