G3X panel.xml Basics

Introduction

The panel.xml file allows developers to configure their aircraft-specific G3X Touch installation. A basic understanding of the XML language is recommended when working with panel.xml.

File Structure

Below is an example of a simple panel.xml file:

<PlaneHTMLConfig>

  <G3X>
  </G3X>

  <Instrument>
    <Name>G3XTouch_1</Name>
  </Instrument>

  <Instrument>
    <Name>G3XTouch_2</Name>
  </Instrument>

</PlaneHTMLConfig>

The file contains the root tag <PlaneHTMLConfig> under which all other tags must be placed. All options for the G3X Touch are located either within the <G3X> tag or within one of the G3X Touch <Instrument> tags.

There can only be one <G3X> tag. If there are multiple copies, then all of them except the first will be ignored.

There is one <Instrument> tag for each JS/HTML instrument in the plane. The <Name> tag identifies the specific instrument referenced by its parent <Instrument> tag. Only those <Instrument> tags that declare a proper G3X Touch name will be parsed by the G3X Touch. In the above example, there are two declared G3X Touch instruments.

info

G3X Touch instrument names are standardized to the following format: G3XTouch_[index], where index is 1, 2, 3, etc.

Tag Scope

Each tag parsed by the G3X Touch has a required scope, defined as the parent under which it must be placed. If a tag is placed in an incorrect scope, it may not be parsed at all or it may be interpreted as a different type of tag with the same name. Therefore, it is important to ensure that all tags are defined in the correct scope.

The tags documentation details the scope of each tag. When the scope is listed as "Global", this means the tag should be placed directly under the <G3X> tag. When the scope is listed as "Instrument", this means the tag should be placed directly under a G3X Touch <Instrument> tag.

Global vs. Instrument-Specific Options

panel.xml options can either be global or specific to a particular instrument. Tags that are descendants of an <Instrument> tag define options specific to the instrument referenced by their parent <Instrument> tag. Tags that are not descendants of any <Instrument> tag define global options.

Certain instrument-specific tags can be defined globally by placing them them in the global scope (directly under the <G3X> tag) instead of under an <Instrument> tag. When doing so, the option will apply to all instruments that support the option. If an instrument-specific tag is defined both globally and within a <Instrument> tag, then the version defined within the <Instrument> tag will override the global one.

caution

Not all instrument-specific tags can be defined globally. Please refer to the tags documentation to find which ones can be defined globally and which ones cannot.

Required vs. Optional Tags

Tags and attributes can either be required or optional. Required tags/attributes must be explicitly defined for panel.xml to be successfully parsed. If a required tag/attribute is missing, the G3X Touch will throw a Javascript error during initialization with a message describing what was missing. Optional tags/attributes do not have to be explicitly defined, and omitting these will have no adverse effects. When an optional tag/attribute is omitted, the option it defines will revert to a default value.

The tags documentation details which tags and attributes are required and which are optional, as well as the default values for optional tags/attributes.

caution

If the G3X Touch detects that an optional attribute or tag was not formatted correctly (e.g. a mis-spelled option, an out-of-bounds numeral, etc), it will emit a console warning and revert the option to its default value. Therefore, during development it is recommended that you monitor the console output of all instruments to ensure that panel.xml is being parsed cleanly.

Option Inheritance

Certain complex instrument-specific option tags support a basic form of inheritance. This allows you to define similar, but not identical, options in multiple instruments without needing to duplicate the entire tag subtree for each instrument. Here is an example:

<G3X>
  <AirspeedIndicator id="base-airspeed">
    <Scale min="30" max="999" window="60" major-tick-interval="10" minor-tick-factor="2">
  </AirspeedIndicator>
</G3X>

<Instrument>
  <Name>G3XTouch_1</Name>

  <AirspeedIndicator inherit="base-airspeed" />
    <VSpeedBugs>
      <Bug name="r" label="R" />
    </VSpeedBugs>
  </AirspeedIndicator>
</Instrument>

<Instrument>
  <Name>G3XTouch_2</Name>

  <AirspeedIndicator inherit="base-airspeed" />
    <VSpeedBugs>
      <Bug name="ref" label="REF" />
    </VSpeedBugs>
  </AirspeedIndicator>
</Instrument>

Here, the two <AirspeedIndicator> tags defined for the G3XTouch_1 and G3XTouch_2 instruments both inherit from the globally defined <AirspeedIndicator> tag. Inheritance is enabled for these tags by the presence of the inherit attribute, which defines the ID of the tag from which they inherit (in this case: base-airspeed).

When inheriting, a tag copies all descendants and attributes that it does not explicitly define itself from the source tag. In the example, the two instrument-specific <AirspeedIndicator> tags inherit the <Scale> tag from #base-airspeed. The instrument-specific <AirspeedIndicator> tags also define their own (different) <VSpeedBugs> tags. If #base-airspeed had defined its own <VSpeedBugs> tag, it would not be inherited by the instrument-specific tags.

Redundant Tags

When you define multiple copies of a tag that is meant to be a singleton, only the first instance of the tag (in tree order) will apply. Take the following example:

<Instrument>
  <Name>G3XTouch_1</Name>

  <AirspeedIndicator id="base-airspeed">
    <Scale min="30" window="60">
  </AirspeedIndicator>

  <AirspeedIndicator id="base-airspeed">
    <Scale min="20" window="70">
  </AirspeedIndicator>
</Instrument>

Of the two <AirspeedIndicator> tags defined for G3XTouch_1, only the top one will apply. As a result, the PFD will have an airspeed indicator with a minimum value of 30 knots and a window size of 60 knots.

Numeric Tags and Operators

Certain G3X Touch-specific tags define numeric values. One such tag is the generic <Number>, which is a numeric tag that returns a constant value equal to its content (for example, <Number>0</Number> returns a value of zero). Other numeric tags may return values with more complicated logic.

Numeric tags can be used together with numeric operator tags to generate computed numeric values. Each numeric operator tag accepts one or more numeric tags as children (the operands) and outputs the result of the operation as a new numeric value. Numeric operators also are considered numeric tags, so they can be used as operands of other numeric operator tags.

The available numeric operator tags are:

Operator	Operand Count	Description
<Min>	One or More	Returns the minimum value among all operands.
<Max>	One or More	Returns the maximum value among all operands.

The following are examples of numeric operator usage:

<!-- Always returns 0 -->
<Min>
  <Number>0</Number>
  <Number>5</Number>
  <Number>10</Number>
</Min>

<!-- Always returns 100 -->
<Max>
  <Number>10</Number>
  <Min>
    <Number>100</Number>
    <Number>1000</Number>
  </Min>
</Max>