Property

The Control Type property details are as follows:

Property Type Description
Bindable Boolean If true, then the following features are enabled:
  • It is possible to bind runtime values to this property rather than just specifying static values at design time.
  • It is possible to update this value dynamically using script actions and that the ControlWrapper has to deal with updates to the property as notified using the refresh() method.
  • The get() and set() methods are automatically generated on the control, and content assist and script validation reflects this auto-generated API. For example: if the property name is "orientation", and it is marked as bindable=true, then the following two methods will be available on the control:
    • <Type> getOrientation()
setOrientation(<Type> value)

      Where <Type> depends on the Data Type specified on the Property.

      The default value is false.

      Note: Irrespective of the value of the bindable property, the getter and setter methods on properties are available to the ConrolWrapper through the proxy Component.getControl() method.
Data Type Classifier Defines the type of the value for this property. This is a reference either to a built-in BOM Primitive Type, or to a Class or Enumeration defined in a BOM file in the Library project. The Data Type will determine what can be bound to the value property in the form model.

When a property type is defined as a specific Class, then it will limit bindings of that property to objects of that type or a specialization of that type defined in the model. If the Data Type is set to BomPrimitiveTypes::Object, then the property can be bound to an object of any complex type. However, in this case it will be the responsibility of the person designing the form to ensure that the binding is to a value that can actually be used by the custom control.

The use case for supporting complex objects for properties includes the use of complex third party controls such as tables and trees. For example, you could define a "Selection" property on a tree control that will be set to the object currently selected by the user. It would still be up the person designing the form to make sure the selected object is used correctly in the rest of the form, for example, by setting it as the value on a pane that can edit that particular type of object.
Default Value Literal String Provides a default value to use for this property if nothing is provided in the form model.

The value must be a valid literal representation for the property's data type.
Externalize Boolean Indicates the Property provides a value which could vary based on locale. A setting of true here will cause the value to be externalized within the form-level resource bundle that is generated automatically.

In addition, the property editor generated for instances of this control will expose the following two settings:

  • A property where the user can specify a value directly.
  • Allow the user to select a reference to a resource bundle key. Only one of these settings will be allowed.

    If the property is both externalized and multi-valued, then the user will only be able to specify values directly into the list editor associated with the property. These values will be written to the form-level resource bundle and can then be translated into locale-specific bundles. In this version, you will not be able to specify a resource bundle reference for multi-valued, externalized properties.

    The default value is false.
Label String Label used in the Form Designer when exposing this property in the property sheet editor.
Multi-valued Boolean Indicates whether the value for this property is multi-valued. If true, then the value for this property can only be bound to multi-valued values.

The default value is false.
Name String This name is used to expose get() and set() methods on the form Control object, and is used when providing updates to the ControlWrapper using the refresh() method.

This property has the following restrictions:

  • Unique among Property names of the same Control Type.
  • Must be an NCName (that is, a legal, 'non-colonized' XML name)
  • Cannot be set to any of the names in the following restricted list:
    • [n/N]ame
    • [f/F]orm
    • [c/C]loneIndex
    • [c/C]ontrolType
    • [p/P]arent
    • [l/L]abel
    • [s/S]hortLabel
    • [h/H]int
    • [e/E]nabled
    • [v/V]isible
    • [r/R]equired
    • [c/C]lassName
    • [r/R]eadOnly
    • [b/B]ackgroundColor
    • [f/F]ontColor
    • [f/F]ontSize
    • [f/F]ontName
    • [f/F]ontWeight
    • [v/V]isualProperty
    • [f/F]ocus
    • [s/S]tringValue
    • [v/V]alue
Description String Provides the descriptive message to display in the status line when the property is selected in the Properties tab in Form Designer.
Required Boolean Whether a value must be provided for the property. Combined with multi-valued, determines the multiplicity of the generated structural feature whose value will be set when editing the property in the Form Designer Properties tab:

The multiplicity constraint is enforced by the property cell editors and form validation rules. The default value is false.