This post describes how to link a property from the propertyDescriptorSet.xml (PDS) to a component in an Abeille form.
The simplest way to do the link is to set the name of the property as the name of the component in Abeille. When the form is loaded the names of the components are compared to the properties defined in the PDS. If there is a match then the type of component(label, text, table etc.) is checked to see if there is a way to display the data type of the property (STRING, NUMBER, etc.). Not all components are supported with all data types. For instance, the SCRIPT type value isn't editable so it doesn't make any since to show it in a text field which is editable. See the table below for a mapping of data types to components. If the type of data can be displayed in the component and the component is Character Sheet Component (CSC) then the onLoadScript is executed. The onLoadScript has no character data available to it. It can only set values on the component that could not be set by Abeille's editor.
The component names linked to properties should follow the normal
parent-name.
child-name notation for properties that aren't in the root of the PDS. Components without a name are ignored. If a component name is required for scripts but isn't needed to link the component to a property, then add an underscore to the beginning of the name. This can useful if a script on one component needs to find the instance of another component on the form. If the name starts with an underscore it isn't linked to a property, but the onLoadScript for CSC's is still executed. If a component has a name that isn't a defined property name and it doesn't start with an underscore an error message will be displayed on the console showing the problem.
The following list shows which components can display a given data type:
- BOOLEAN: JToggleButton, JCheckBox, JRadioButton, CharSheetCheckBox, & CharSheetRadioButton. The boolean value can be edited by all of these components.
- NUMBER: JLabel, JETALabel, JTextField, JTextArea, JEditorPane, JTextPane, JComboBox, CharSheetComboBox, CharSheetEditorPane, CharSheetLabel, CharSheetTextArea. & CharSheetTextField. The number value can be edited in all components except the JLabel & JETALabel components.
- STRING: JLabel, JETALabel, JTextField, JTextArea, JEditorPane, JTextPane, JComboBox, CharSheetLabel, CharSheetComboBox, CharSheetEditorPane, CharSheetLabel, CharSheetTextArea, & CharSheetTextField. The string value can be edited in all components except the JLabel & JETALabel components.
- MAP: CharSheetTable can display the entire map and edit child properties of types BOOLEAN, NUMBER & STRING. CharSheetLabel, CharSheetButton & CharSheetJideButton will accept map data but it is not displayed. It is used in scripts.
- LIST: CharSheetTable can display the entire list and edit child properties of types BOOLEAN, NUMBER & STRING. CharSheetLabel will accept list data but it is not displayed. It is used in scripts. The values in a list may be shown as the contents of the drop-down on CharSheetComboBox components even if the component isn't linked directly to the combo box.
- SLOT: A slot supports the same components as a MAP except that only BOOLEAN, NUMBER & STRING type properties defined as slot modifiable can be edited. Also, the CharSheetComboBox will allow the value of the SLOT itself to be modified.
- IMAGE: JLabel, JETALabel & CharSheetLabel can display an image. CharSheetImage can display and edit an image.
- SCRIPT: JLabel, JETALabel & CharSheetLabel can display script results. JButton, CharSheetButton & CharSheetJideButton can execute scripts defined in the PSD to perform special tasks and output messages to the user.
Once the components and properties are linked the component values are populated. They are populated every time the character sheet changes. This is because a change to a property may change the values of all scripts that depend on the modified property value. The population is performed automatically if the value is edited directly by a component. If a script edits something it must call the method rpController.setFields() to have the values updated. Every time the component value is set the onSetValue script is executed. This script will have the parent of the linked property as its context and has complete access to all character data. The onSetValue script must set the value of its component before it exits as the CSC's won't do the work when a script is defined. Also note that the onSetValue script is not called if the CSC does not have a linked property. Therefore the name of the component should be set to an appropriate property (root will always work) to make sure it is called on all changes of the character data. This allows for values not in the PDS to be calculated and displayed and makes sure they are updated when character data changes. The RPScript function setText(rpComponent,
text) can be called to calculate simple values for components that show text (JLabel, JETALabel, JTextField, JTextArea, JEditorPane, CharSheetLabel, CharSheetTextField, CharSheetTextArea, & CharSheetEditorPane). There are also RPScript functions that can set colors (setBackground(rpComponent,
color) & setForeground(rpComponent,
color)) and enable or disable the component (setEnabled(rpComponent,
boolean)). In JavaScript no special methods are needed since they can be called directly on the component using the rpComponent variable.
Some of the other CSC components have other scripts that can be executed. CharSheetButton, CharSheetJideButton CharSheetRaidoButton & CharSheetCheckBox have an actionScript that is executed when the button is pressed. CharSheetComboBox has an actionScript that is executed when the user selects anything in the drop down list. CharSheetTable has a doubleClickScript which is called when a user double clicks a row in the table and selectionScript which is called when the user modifies the selected rows in the table. There is also an onColumnRender script that can be used to modify the renderer used to paint a cell. The combo box and table CSC's have special methods that can be used to get the selected value as a property. All of the scripts listed here have the linked property value's parent node as its context so there is access to all of the character data.
All scripts are entered as plain text into a component property with the given name. Start JavaScript scripts with the string JavaScript:: so that the proper parser is used on it. RPScript is the default so no name is required for those scripts. I will provide more details on what variables are available to all components scripts in a later post.
The CharSheetComboBox has special properties on it that are used to control what is shown in the drop down. The property named comboBoxModelProp controls where the data for the drop-down is located. If it is empty then the values in comboBoxModelRows are the individual strings displayed in the drop-down. If the comboBoxModelProp contains the name of a MAP or SLOT property then the value in comboBoxModelRows contains the names of the properties whose values are shown in the drop-down. If the comboBoxModelProp contains a LIST then the comboBoxModelRows contains the index of each item in the list that is shown. If the comboBoxModelTable is set the individual rows are read from one of the database tables in the game settings file. The comboBoxModelProp & comboBoxModelRows are ignored when this property is set. The other property unique to the CharSheetComboBox is comboBoxModelEmpty which is the string that is displayed when the value of the property linked to the component is empty.
The CharSheetTable also has special properties. The rows property contains the list child property names of the linked property that define the rows of the table, if that linked property is a MAP or SLOT. If it is a LIST then each element in the list is a row in the table. The columns property contains the names of the properties in each row to be displayed as columns. To restrict the size of a column follow the name with (###) where the ### is the fixed width of the column in pixels. The header for the columns will either contain the names in this component property or it will contains the display names if the columns can be attached to property descriptors from the PDS. Columns that are BOOLEAN, NUMBER or STRING data types as defined by the PDS will be editable if the linked component property is a MAP or a SLOT and the column is slot modifiable. The CharSheetTable columns are sortable and resizable (if width not fixed). The sort columns and columns sizes can be saved it he preferencesName property is set to something unique to the form. If it isn't unique then the preferences may be overwritten by other tables.
If some (all?
) of this isn't clear please ask and I'll try to clarify.