skip to main content
Programmer's documentation > Developing with the JViews Charts SDK > Integrating a chart customizer into your application > XML specification of the chart customizer
 
XML specification of the chart customizer
Example of XML File
 
<!-- Customizer Form for IlvChart.Area -->
 <form bundles="ChartAreaForm">
   <group title="AppearanceGroup">
     <group title="ColorsGroup">
       <property name="foreground"
        displayedName="foregroundDisplayedName"
        tooltip="foregroundTooltip"/>
       <property name="opaque"
        displayedName="opaqueDisplayedName"
        tooltip="opaqueTooltip"/>
       <property name="backgroundPaint"
        displayedName="backgroundDisplayedName"
        tooltip="backgroundTooltip">
        <enabled>
         <when property="opaque" value="true"/>
        </enabled>
       </property>
       <property name="border"
        displayedName="borderDisplayedName"
        tooltip="borderTooltip"/>
       <property name="font"
        displayedName="fontDisplayedName"
        tooltip="fontTooltip"/>
     </group>
   </group>
 </form>
The GUI elements are specified between <form> and </form> elements.
For internationalization purposes, you can pass a resource bundle to the <form> element.
The resource bundle is used to retrieve all texts (labels, tooltips) that should be displayed in the chart customizer. Furthermore, the specification consists of groups ( <group> ) and properties ( <property> ).
The <group> element specifies a section in the chart customizer. Usually, a group has a title that indicates the purpose of the section. Groups can be nested, that is, a group can contain other groups. Finally, a group consists of a list of properties. In the chart customizer, you can consider a group as a panel with a titled order that groups together a collection of controls (buttons, fields, and boxes).
The <property> element specifies a property of the corresponding chart renderer that should be customized. For example, to customize the foreground color of the chart area, specify <property name="foreground"/>.
There is only a limited set of properties for each IlvRuleCustomizerLogic, you cannot specify arbitrary properties that do not exist. In the chart customizer, the <property> element produces a control element (button, text field, check box, list box, and so on) that allows you to edit this property. For example, the specification <property name="foreground"/> in the example above creates a color editor control that allows you to change the foreground color of a chart area. This control appears with a label in the chart customizer. You can specify the label and the tooltip of the control as follows:
 
<property name="foreground" displayedName="foregroundDisplayedName"
tooltip="foregroundTooltip"/>
The keys foregroundDisplayedName and foregroundTooltip are looked up in the resource bundle of the chart customizer form. If the keys are not found, the string foregroundDisplayedName is used as label, and the string foregroundTooltip is used as tooltip.
It might happen that a control of a property should only be enabled if another property has a certain value. This is possible with subspecifications in the properties. For example, the following specification means that the control of the backgroundPaint should only be enabled if the opaque property has the value true.
 
<property name="backgroundPaint">
 <enabled>
  <when property="opaque" value="true"/>
 </enabled>
</property>
XML Tags and Attributes Available in the Specification of a chart customizer describes all XML tags that are available in the specification of a chart customizer.
XML Tags and Attributes Available in the Specification of a chart customizer
Element
Attribute
Description
form
 
Root element.
Defines the chart customizer.
 
bundles
Optional, but recommended.
Defines a list of resource bundles that provide string resources for the form.
The items of the list are separated by a comma and are relative path names. These path names are resolved into full path names using the URL of the form as a reference or the URL resolvers added to the application.
 
title
Optional, but recommended.
Defines a title for the entire chart customizer.
group
 
Parent: form or group.
Defines a group of any combinations of property, help and group elements.
 
title
Optional, but recommended.
Defines the title of the group. Typically, this will be shown either as the name of a tab in a tabbed pane or in the title border of a BorderedPanel.
 
awtLayoutManager
Optional.
Defines the fully-qualified class name of the layout manager to be used for this group instead of the default one in AWT/Swing chart customizers. It must be a public class (accessible in the classpath) implementing java.awt.LayoutManager and providing a default constructor or a constructor taking a java.awt.Container argument (the target panel).
 
dummy
Optional.
If the value is true, the GUI does not show any border around the group nor a title.
 
overlaid
Optional.
If the value is true, the elements contained in this group (subgroups or properties) are displayed in overlaid mode. Typically, this attribute is set when you want only one set of elements to be visible, depending on certain conditions. See also the visible element.
property
 
Parent: form or group.
This element defines one property (usually corresponding to a JavaBean property, but not necessarily) of the customized target.
 
name
Required.
Defines the name of the property. Typically, this is the name of the JavaBean property, but in complex situations it can be a different identifier. This must not be internationalized.
 
targetId
Optional.
Defines an identifier for the target to which the property belongs. Typically, this is used in complex chart customizers where subtargets have their own properties. This must not be internationalized.
 
displayedName
Optional, but recommended.
Defines the string that appears as a label near the GUI component and allows you to customize the property.
 
tooltip
Optional, but recommended.
Defines the string that appears as a tooltip over the GUI component and allows you to customize the property.
 
minValue
Optional for numeric properties, ignored for non-numeric. Defines the minimum value that the user is allowed to enter. If both minValue and maxValue are specified, the GUI will typically show a slider in addition to the text field and the spinner.
 
maxValue
Optional for numeric properties, ignored for non-numeric.
Defines the maximum value that the user is allowed to enter. If both minValue and maxValue are specified, the GUI will typically show a slider in addition to the text field and the spinner.
 
incValue
Optional for numeric properties, ignored for non-numeric.
Defines the increment for the spinner usually associated with the text field.
 
choices
Optional for tagged properties, ignored otherwise.
Defines the list of values to be presented to the user, typically in a combination box. Its value must be a comma-separated list of strings (for example, the names of the combo items) and values. For example: MyResource.FirstItem.Name=3,MyResource.SecondItem.Name=4. Note that, by default, this is retrieved from the property descriptor. You only need the attribute if you want to override this information.
 
displayedNullValue
Optional for properties of non-primitive type, ignored otherwise. Defines the string representation of the null value of the property. For example, it can be "null", "(null)", "(none)", "(unspecified)", or an empty string. If the attribute is not specified, the text is retrieved from propertyEditor.getAsText.
 
index
Optional for indexed properties, ignored otherwise.
It is used when the chart customizer needs to allow the customization of a given element of the array of an indexed property.
 
preferredWidth
Optional.
Defines a preferred width of the GUI control used for the property, to be used instead of the default one. You can specify either the value directly, or a resource key.
 
preferredHeight
Optional.
Defines a preferred height of the GUI control used for the property, to be used instead of the default one. You can specify either the value directly, or a resource key.
 
propertyEditor
Optional.
Defines the fully-qualified class name of the property editor to be used for this property instead of the default one. It must be a public class (accessible in the classpath) implementing java.beans.PropertyEditor and providing a default constructor.
help
 
Parent: form, group, or property.
Defines help contents for its parent element. This can be either a text area directly embedded in the chart customizer, or a button allowing to open a standalone help window to display an HTML file.
 
text
Optional.
Defines the string to be shown embedded in the chart customizer, typically as a text area.
 
title
Optional.
Defines the string to be shown as title of the help window instead of the default title. Ignored if the text attribute is present (that is, for help text in a text area embedded in the chart customizer).
 
page
Optional.
Defines the relative URL of an HTML help page. Ignored if the text attribute is present.
 
buttonIcon
Optional.
Defines the relative URL of the image to be shown instead of the default icon used to open a standalone help window. Ignored if the text attribute is present.
 
tooltip
Optional, but recommended.
Defines the string that is shown as tooltip over the GUI component (text area or button for opening a standalone help window.)
enabled
 
Parent: group or property.
Defines a condition for enabling/disabling a group or a property depending on the value of one or several properties of the target, or depending on some external conditions. It must have the following subelements: when, or, and, or not.
visible
 
Parent: group or property.
Defines a condition for controlling the visibility of a group or of a property depending on the value of one or several properties of the target, or depending on some external conditions. It must have the following subelements: when, or, and, or not.
when
 
Parent: enabled, visible, or, and, or not.
Defines the rules for enabling/disabling or changing the visibility of a group or a property depending on the value of one or several properties of the target, or depending on some external conditions. It must have either the attribute condition, or the attribute property associated with value.
 
condition
Required if property associated with value are not present. Defines the identifier of a condition that is implemented in Java code.
 
property
Required if condition is not present.
Defines the name of the property. The enabled/disabled state or the visibility depends on the value of this property. For properties where a targetId is not specified, use the name attribute. Otherwise, use the targetId attribute.
 
value
Required if condition is not present.
Defines the value of the property specified by the property attribute.
and
 
Parent: enabled, visible, and, or, or not.
Defines an and logical operation for its subelements. It must have the following subelements: when, or, and, or not.
or
 
Parent: enabled, visible, and, or, or not.
Defines an or logical operation for its subelements. It must have the following subelements: when, or, and, or not.
not
 
Parent: enabled, visible, and, or, or not
Defines a not logical operation for its subelements. It must have the following subelements: when, or, and, or not.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.