This package contains the component reader. Using an XML based definition the properties on a component are described.

## Introduction

The editor and runtime have no knowledge about the components composing a display or symbol. It is not aware that there are rectangles, circles, sliders, alarm overviews, etc. During startup the editor or runtime take a look in the %TLS_ROOT_PATH%\tls\wap\cfg\operatorInterfaces\%d\components directory to find out the components that are available for displays and symbols. Each component is described by a separate xml file that supplies global information about the component and its properties that are available to the editor or runtime. The next sections describe the xml syntax used to describe a component. Many examples of component description files are are found in the directory mentioned above.

## XML file structure

### componentType

    <componentType
      name="name of the component"
      icon="file name of for the icon.png"
      description="component description"
      containedBy="name of container class"
      class="name of the class"
      makeInteractor="name of java class that can make the component interactively"
      enterprise="yes|no"
      resourceBundle="name of translation properties file"
      <property.../>
    />

General remarks: Attribute names (as part of XML element tags) are case sensitive!

The componentType attribute starts the definition of a component. A component must be a class derived from IlvGraphic. If this is not the case then a container can be supplied, which is derived from IlvGraphic, that can embed the component (see containedBy).

- name
  The name of the component.
- icon
  The name of an image file that contains the icon that represents the component. This icon is shown in the drawing pallet of the editor.
- description
  The description of the component. This text is shows as an one liner help about the component.
- containedBy
  A container class name that is capable of containing the component if the component itself is not derived from IlvGraphic. The containedBy class must be derived from IlvGraphic. For swing stuff this is always "fasttools.jwui.ilv.graphic.ExtendedJComponent". As a shortcut just "JComponent" can be specified. In that case the makeInteractor does not need to be specified. It uses then the default make interactor for JComponents.
- class
  The name of the java class (full qualified path) that handles the component.
- makeInteractor
  Each component can have its own method how it is created interactively by the user of the editor. This attribute supplies the name of the class that can be called by the editor to let the user to create the component interactively.
- enterprise
  Whether the component is an enterprise component. If "yes" then the component is only available while editing an enterprise display or symbol. If "no" then the component is available while editing an enterprise or local display or symbol. Default is "no".
- resourceBundle
  This attribute is optional. It specifies an alternative translation resource to the CI Server common translation resource.
  e.g. A resourceBundle value of "my.package.MyResourceBundle"(without ".properties" extension) will be obtained
  by classloader from "my/package/MyResourceBundle.properties" or
  by fileloader from "tls/wap/properties/MyResourceBundle.properties".
  During translation first this bundle is interrogated, then the CI Server common bundle

#### property

    <property
      name="name of the property"
      id="unique id number for the property"
      type="representation of the property"
      description="component description"
      defaultAllowed="yes|no"
      save="yes|no"
      writeAllowed="yes|no"
      readAllowed="yes|no"
      connectAllowed="yes|no"
      deprecated="yes|no"
      enterprise="yes|no"
      bound="yes|no"
      null="none|default|readOnly"
      setter="name of the setter method"
      getter="name of the getter method"
      array="a..b"
      localized="yes|no"
      initialValue="yes|no"
      advanced="yes|no"
      triggers="comma separated list of properties in this component"
    />

Each component can have a number of properties. Each property attribute specifies one of the properties of the component.

- name
  The name of the property.
- id
  A unique identification number of the property. It must be in the range 1-999. When omitted then the id is generated automatically starting with 1000 and in the order as the properties are listed.
- type
  The representation type of the property. This can be java primitive type like "float", "int", etc. Or the name of a class like "java.lang.String" (notice the full path), "fasttools.jwui.common.property.paint.PaintSet", etc.
- description
  The description of the property. It used as an one liner help in the editor.
- defaultAllowed
  The editor is capable in pasting default properties to a component. The defaultAllowed attribute specifies whether a default property value can be applied to this property. For example, the x,y position of the component may not be set by applying default attributes. Default is "yes".
- save
  Specifies whether the value for this attribute must be saved while the display/symbol is saved. Default is "yes".
- writeAllowed
  Specifies whether the property can be assigned a new value. Default is "yes".
- readAllowed
  Specifies whether the property can be read. Default is "yes".
- connectAllowed
  Specifies whether the property can be connected to an item. Default is "yes".
- deprecated
  Specifies whether the property is deprecated. A deprecated property can only be read from a visualization file. It cannot be saved, edited, connected or seen in the Edit Module. This is useful when you want to maintain backward compatibility with a property, but do not want to use the property in a new version of the component. Default is "no".
- enterprise
  Specifies whether the property is only valid in enterprise displays and symbols. Default is "no".
- bound
  Specifies whether the property can fire an event if its value is changed internally. For example, for a slider the value property fires an event if the slider is moved by the user. Default is "no". If at least one property is bound then the component's class must have the methods addPropertyChangeListener(PropertyChangeListener listener) and removePropertyChangeListener(PropertyChangeListener). The PropertyChangeEvent method getPropertyName() returns the name of the property or the name of the getter method.
- null
  This specifies things about a null values for class types:
  - none
    Specifies that a null value may be set that indicates the property as "not set". For example an icon may be set to null that indicates that no icon is set. The icon selection box must have the possibility to select "none".
  - default
    Specifies that a null value may be set that indicates the property as "set to default". For example the foreground color may be set to null that indicates that de default foreground color is set. The color selection box must have the possibility to select "default".
  - readOnly
    Specifies that no null value may be set and if null value is read that at that moment the property is readonly.
- setter
  This specifies the name of the setter method. If not specified then the name of the setter method is derived from the property name.
- getter
  This specifies the name of the getter method. If not specified then the name of the getter method is derived from the property name.
- array
  This specifies that the property is exposed as an properties array. Supported value format is "a..b" where a and b are integer values and a<b. The 'int' array-index is supplied as the first argument when calling the getter and setter methods on the component.
- localized
  This specified that the property is to be localized according to the user locale, when a localization is available. Currently, this can only apply to String properties. The internal property value is unaffected; only its representation is localized.
- initialValue
  Specifies that a property has a (default) initial value. Set to "no" to specify that a property does not have an initial value. For example, a symbol instance component may represents many different symbols, each of which may have a different initial size. When unspecified, the default is "yes".
- advanced
  If yes, then this property will only show on the 'advanced' tab of the component properties sheet. Notice that advanced properties which are connected to a parameter will also show up in the 'basic' tab in italics.
- triggers
  Specifies that a change in the value of this property may trigger an irreversible or unpredictable change to the value of each of the specified properties. This allows value changes in this property to also generate events for any value changes of the specified properties that may occur as a result (e.g. for the undo-redo mechanism).