Extension point for defining kit editors.(c) SAP AG 2003-2006. All rights reserved.
Defines a new editor (a collection of related editing elements).The new editor definition.The newly defined editor.<h2>Xml definition of an editor in a configuration file</h2>
<pre>
<CONFIGURE type="EDITORS">
? <HEADER>
? <PRAGMA># Pragmas section</PRAGMA>
? <SCRIPT># Code section. Place here functions\variables
which you want to address from within the editor tags
</SCRIPT>
</HEADER>
<EDITORS>
+ <EDITOR id="com.sap.mypackage:editorId">
# For complete description of editor
definition see <q ref="core.env:KitEditors!EDITOR_DEF">EDITOR_DEF</q>
? <PROPERTIES>
* <propertyName type="[function | ]"/>
# Represents a property of the editor
You can assign the 'type' attribute for
evaluating the value of the property
as a function
</PROPERTIES>
* <GROUP id="[elementId| ]">
# For complete description of group definition
see <q ref="core.env:KitEditors!EDITOR_GROUP">EDITOR_GROUP</q>
? <PROPERTIES>
* <propertyName type="[function | ]"/>
# Represents a property of the group
You can assign the 'type' attribute for
evaluating of the value of the property
as a function
</PROPERTIES>
* <editorElementType id="editorElementId">
# For complete description of editor elements and
properties see <q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q>
* <propertyName type="[function | ]"/>
# Represents a property of the editor element
You can assign the 'type' attribute for
evaluating of the value of the property
as a function
</editorElementType>
</GROUP>
</EDITOR>
</EDITORS>
</CONFIGURE>
</pre>
<h2>Example</h2>
<pre>
<CONFIGURE type="EDITORS">
<EDITORS>
<EDITOR id="core.gml:PROPS_GENERAL">
<PROPERTIES>
<category>PROPERTIES</category>
<priority>100</priority>
</PROPERTIES>
<GROUP>
<PROPERTIES>
<title>General</title>
<toggle>on</toggle>
</PROPERTIES>
<text id="notes">
<label>comments</label>
<height>75</height>
</text>
</GROUP>
</EDITOR>
</EDITORS>
</CONFIGURE>
</pre>
Returns a specified editor definition.Editor Id.The requested editor definition.
Returns the complete editors table.Table of editor definitions, indexed by editor id.Editor id's are stored in uppercase. Use <q ref="core.lib:Basic!UPPER">UPPER</q> macro to convert the editor's id to uppercase
before using it as the index in this table.
Returns the editor definitions that belong to a given category, sorted by priority.The requested editors category.Array of selected editor definitions.
Removes a specified editor definition.The id of the editor definition to remove.
Defines an editor.An editor is a collection of one or more groups of editing elements that are shown or hidden together
<table class="BOTH" width="95%"><tr><td class="H V">Name </td><td class=H>Type </td><td class=H>Description </td></tr><tr><td class=V>id </td><td>QName </td><td>The editor's identifier - must be prefixed with namespace e.g. com.sap.mypackage:id </td></tr><tr><td class=V>category </td><td>String </td><td>The editor's category, used for relating editors to specific tasks or dialogs </td></tr><tr><td class=V>priority </td><td>Number </td><td>The editor's priority, used for calculating the display order of editors within the same category </td></tr><tr><td class=V>visible </td><td>Function </td><td>Dynamic visibility state of the editor: <p style="margin:10"><code>flag = visible(<i>data</i>, <i>definition</i>)</code></p> Where <code>data</code> is the editor's data object, and <code>definition</code> is this editor's definition. If the function returns <code>true</code> the editor will be visible; otherwise, it will be hidden. If the function is omitted, the editor will be visible by default. </td></tr><tr><td class=V>color </td><td>Enum </td><td>The editor's default background color. Can be overridden on the group level. See <q ref="core.env:KitEditors!EDITOR_GROUP">EDITOR_GROUP</q> for the enumeration of the available color values. </td></tr><tr><td class=V>description </td><td>String </td><td>The editor's description </td></tr><tr><td class=V>0..n </td><td><q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q> or <q ref="core.env:KitEditors!EDITOR_GROUP">EDITOR_GROUP</q> </td><td>The elements contained in the editor, listed by display order </td></tr></table>
In addition, the structure has the following methods:
<h2><i>editor</i>.append(elem, after)</h2>
Appends an element just after another element in the editor, where:
<table class="SIMPLE" style="width:70%"><tr><td class="H V">Parameter </td><td class=H>Type </td><td class=H>Description </td></tr><tr><td class=V>elem </td><td><q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q> </td><td>The element to append </td></tr><tr><td class=V>after </td><td>QName </td><td>Optional. The id of the element after which the new element will be appended </td></tr></table>
<ul><li>If <code>after</code> is omitted or not found, the new element will be appended at the end of this editor. </li></ul>
<h2>elem = <i>editor</i>.getItem(id)</h2>
Gets s a specified editor element by Id or by position, where:
<table class="SIMPLE" style="width:70%"><tr><td class="H V">Parameter </td><td class=H>Type </td><td class=H>Description </td></tr><tr><td class=V>id </td><td>QName/Number </td><td>The element id or ordinal position </td></tr><tr><td class=V>elem </td><td><q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q> </td><td>The requested editor element </td></tr></table>
<h2><i>editor</i>.insert(elem, before)</h2>
Inserts an element just before another element in the editor, where:
<table class="SIMPLE" style="width:70%"><tr><td class="H V">Parameter </td><td class=H>Type </td><td class=H>Description </td></tr><tr><td class=V>elem </td><td><q ref="core.env:KitEditors!EDITOR_DEF">EDITOR_DEF</q> </td><td>The element to insert </td></tr><tr><td class=V>before </td><td>QName </td><td>Optional. The id of the element before which the new element will be inserted </td></tr></table>
<ul><li>If <code>before</code> is omitted, the new element will be inserted at the beginning of this editor. </li><li>If <code>before</code> is not found, the new element will be inserted at the end of this editor. </li></ul>
<h2><i>editor</i>.remove(id)</h2>
Removes an element from the editor, where:
<table class="SIMPLE" style="width:70%"><tr><td class="H V">Parameter </td><td class=H>Type </td><td class=H>Description </td></tr><tr><td class=V>id </td><td>QName </td><td>The Id of the element to remove </td></tr></table>
<h2><i>editor</i>.clear(id)</h2>
Clears all elements in the editor
<table class="SIMPLE" style="width:70%"><tr><td class="H V">Parameter </td><td class=H>Type </td><td class=H>Description </td></tr></table><q ref="core.env:KitEditors!EDITOR_GROUP">EDITOR_GROUP</q> | <q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q>
Defines an editor element.<h2>Element Types</h2>
<p style="width:90%">
The editor element definition is a union of a variety of editor element types,
classified as follows:
</p>
<table class="BOTH"><tr><td class="H V">Category </td><td class=H>Type </td><td class=H>Description </td><td class=H>Datatype </td></tr><tr><td class=V>ACTION </td><td>BTN </td><td>Text or image button </td><td>N.A. </td></tr><tr><td class=V> </td><td>LINK </td><td>Text or image link </td><td>N.A. </td></tr><tr><td class=V> </td><td>PUSH </td><td>Pushbutton </td><td>N.A. </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>CHOICE </td><td>RADIO </td><td>Radio buttons group </td><td>String </td></tr><tr><td class=V> </td><td>CHECKLIST </td><td>Checkbox buttons group </td><td>String </td></tr><tr><td class=V> </td><td>SELECT </td><td>Single selection list </td><td>String </td></tr><tr><td class=V> </td><td>MULTISEL </td><td>Multiple selection list </td><td>String </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>CUSTOM </td><td>CUSTOM </td><td>Owner-drawn (custom) element </td><td>Variant </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>DISPLAY </td><td>DISPLAY </td><td>Formatted values display </td><td>Variant </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>DRAG </td><td>DRAG </td><td>Draggable element </td><td>N.A. </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>INPUT </td><td>BOOL </td><td>Boolean input field </td><td>Boolean </td></tr><tr><td class=V> </td><td>COLOR </td><td>Color input field </td><td>String </td></tr><tr><td class=V> </td><td>COMBO </td><td>Combobox input field </td><td>String </td></tr><tr><td class=V> </td><td>DATE </td><td>Date input field </td><td>Date </td></tr><tr><td class=V> </td><td>ENUM </td><td>Dropdown input field </td><td>String </td></tr><tr><td class=V> </td><td>EXPR </td><td>GML expression input field </td><td>String </td></tr><tr><td class=V> </td><td>FLOAT </td><td>Floating-point input field </td><td>Number </td></tr><tr><td class=V> </td><td>HTML </td><td>HTML input field </td><td>String </td></tr><tr><td class=V> </td><td>INT </td><td>Integer input field </td><td>Number </td></tr><tr><td class=V> </td><td>STR </td><td>Simple string input field </td><td>String </td></tr><tr><td class=V> </td><td>TEXT </td><td>Multi-line string field </td><td>String </td></tr><tr><td class=V> </td><td>TIME </td><td>Time input field </td><td>Date </td></tr><tr><td class=V> </td><td>URL </td><td>Url input field </td><td>String </td></tr><tr><td class=V> </td><td>USER </td><td>User-defined input field </td><td>String </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>STATIC </td><td>HTML </td><td>Static html content </td><td>N.A. </td></tr><tr><td class=V> </td><td>SUBTITLE </td><td>Sub-title </td><td>N.A. </td></tr><tr><td class=V> </td><td>DIVIDER </td><td>Dividing line </td><td>N.A. </td></tr><tr><td class=V> </td><td>SPACER </td><td>Spacing line </td><td>N.A. </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>SLIDER </td><td>SLIDER </td><td>Numeric slider </td><td>Number </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>TOGGLE </td><td>CHECK </td><td>Checkbox button </td><td>Boolean </td></tr><tr><td class=V> </td><td>TOGGLE </td><td>Toggle button </td><td>Boolean </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>TREE </td><td>TREE </td><td>Hierarchical tree selector </td><td>String </td></tr><tr><td class=V> </td><td> </td><td> </td><td> </td></tr></table>
<h2>Element Properties</h2>
<p>
The editor element's definition is made of the following properties:
</p>
<table class="BOTH" width="95%">
<tr><td colspan="4" style="background:white"><b>General</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">id</td><td>QName</td><td>ALL</td><td>Element's identifier. The identifier is required for data bound elements, and must be unique within the editor's scope. The identifier can also be optionally provided for static elements.</td></tr>
<tr><td class="V">type</td><td>Enum</td><td>ALL</td><td>Element's type according to the available types listed above</td></tr>
<tr><td class="V">priority</td><td>Number</td><td>ALL</td><td>Element's priority. The element will be positioned according to it's relative priority</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Data</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">domain</td><td><q ref="core.lib:Global!ENUM_DEF">ENUM_DEF</q></td><td>INPUT, CHOICE</td><td>An enumeration that defines the allowed values domain. Dynamic enumerations are allowed only for INPUT elements.</td></tr>
<tr><td class="V">domain</td><td>Array</td><td>TREE</td><td>A recursive array that contains the tree nodes data (or a function returning such an array). Each item in the array is an object {value, text, children} that represents a tree node, where <code>value</code> is the node's value, <code>text</code> is the node's display text label, and <code>children</code> is an nested array (with same structure) representing the child nodes (if any).</td></tr>
<tr><td class="V">min</td><td>Number</td><td>INPUT, SLIDER</td><td>Minimum value for numeric data types</td></tr>
<tr><td class="V">max</td><td>Number</td><td>INPUT, SLIDER</td><td>Maximum value for numeric data types</td></tr>
<tr><td class="V">step</td><td>Number</td><td>INPUT, SLIDER</td><td>Stepping value for numeric data types</td></tr>
<tr><td class="V">popup</td><td>String</td><td>INPUT</td><td>Urn of the custom popup for user-defined data types</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Display</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">label</td><td>String</td><td>ALL</td><td>Label to display near the element</td></tr>
<tr><td class="V">descr</td><td>String</td><td>ALL</td><td>Description to display in the element's tooltip</td></tr>
<tr><td class="V">nonActiveDescr</td><td>String</td><td>ALL</td><td>Description to display in the element's tooltip when element is non-active</td></tr>
<tr><td class="V">icon</td><td>String</td><td>ACTION, DRAG</td><td>Url of icon to display in the element. Typically, ACTION elements use small icons (16x16), and DRAG elements use large icons (32x32).</td></tr>
<tr><td class="V">content</td><td>String</td><td>STATIC</td><td>Html content to display in the element</td></tr>
<tr><td class="V">minLabel</td><td>String</td><td>SLIDER</td><td>Label to display for the minimum value</td></tr>
<tr><td class="V">maxLabel</td><td>String</td><td>SLIDER</td><td>Label to display for the maximum value</td></tr>
<tr><td class="V">expand</td><td>Number</td><td>TREE</td><td>Number of levels to expand when the tree is first displayed (default is 1)</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Style</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">frame</td><td>Enum</td><td>CHOICE, DISPLAY, INPUT, TREE</td>
<td>The element's frame style, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No frame (default for INPUT and CHOICE(RADIO|CHECKLIST) types)</td></tr>
<tr><td>SOLID</td><td>Solid frame drawn around the element (default for CHOICE(SELECT|MULTISEL) and TREE types)</td></tr>
<tr><td>INSET</td><td>Sunken frame drawn around the element</td></tr>
</table>
</td></tr>
<tr><td class="V">flat</td><td>Bool</td><td>CHOICE, TOGGLE</td><td>Indicates whether to use flat or classic buttons style</td></tr>
<tr><td class="V">arrow</td><td>Enum</td><td>INPUT</td>
<td>Indicates when the dropdown arrow should be displayed, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">ALWAYS</td><td>Always show the dropdown arrow (default)</td></tr>
<tr><td>AUTO</td><td>Show the dropdown arrow only when the element receives the input focus</td></tr>
<tr><td>NEVER</td><td>Never show the dropdown arrow</td></tr>
</table>
</td></tr>
<tr><td class="V">style</td><td>String</td><td>ALL</td><td>Custom styling rules to apply on the element </td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Layout</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">outer</td><td>Number</td><td>ACTION(link), CHOICE, DISPLAY, INPUT, SLIDER, STATIC, TOGGLE, TREE</td><td>The element's outer margin (gutter), in grid units. The outer margin defines the indentation of the element's label.</td></tr>
<tr><td class="V">inner</td><td>Number</td><td>CHOICE, DISPLAY, INPUT, SLIDER, STATIC, TREE</td><td>The element's inner margin (indentation), in grid units. The outer margin defines the indentation of the element itself. If the inner margin is equal to or less than the outer margin, then the element will be placed below the label.</td></tr>
<tr><td class="V">columns</td><td>Number</td><td>CHOICE</td><td>Number of displayed columns (default is 1; 0 implies no columns)</td></tr>
<tr><td class="V">height</td><td>Enum</td><td>CHOICE, DISPLAY, STATIC, TREE</td><td>The element's height, if the element is inside a group with flow layout:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">AUTO</td><td>Adjust the element's height to fit its contents (default)</td></tr>
<tr><td><i>nnn</i></td><td>Set the element to fixed height <i>nnn</i>, in pixels</td></tr>
</table>
</td></tr>
<tr><td class="V">width</td><td>Enum</td><td>ACTION</td><td>Element's width, if the element is inside a group with flow layout:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">AUTO</td><td>Standard width according to element's type (default)</td></tr>
<tr><td>SHORT</td><td>Short width</td></tr>
<tr><td>MEDIUM</td><td>Medium width</td></tr>
<tr><td>LONG</td><td>Long width</td></tr>
<tr><td><i>nnn</i></td><td>Fixed width, in pixels</td></tr>
<tr><td><i>nnn</i>%</td><td>Variable width, as percentage of the containing group's width</td></tr>
</table>
</td></tr>
<tr><td class="V">left,<br/>top,<br/>width,<br/>height</td><td>Number</td><td>ALL</td><td>The element's bounding box, if the element is inside a group with absolute layout.<br/><br/>
Each of the values can be specified either as a fixed number of pixels (<i>nnn</i>), or as a percentage of the corresponding dimension of the containing group (<i>nnn</i>%).
</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Constraints</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">getter </td><td>Function</td><td>CHOICE, CUSTOM, DISPLAY, INPUT, SLIDER, TOGGLE, TREE</td><td>
Dynamic value getter for the editor element. If provided, this function will be called whenever a
value needs to be set in the element, using:
<p style="margin:10"><code>value = getter(<i>data</i>, <i>def</i>)</code></p>
Where <code>data</code> is the editor's data object and <code>def</code> is this element's definition.
The <code>getter</code> function should return the value that needs to be represented in the element.</td></tr>
<tr><td class="V">setter</td><td>Function</td><td>CHOICE, CUSTOM, INPUT, SLIDER, TOGGLE, TREE</td><td>
Dynamic value setter for the editor element. If provided, this function will be called whenever
the element's value is changed, using:
<p style="margin:10"><code>actualValue = setter(value, <i>data</i>, <i>def</i>)</code></p>
<p>
Where <code>value</code> is the value to set, <code>data</code> is the editor's data object, and
<code>def</code> is this element's definition.
</p><p>
The <code>setter</code> function may carry out any required actions based on the new value. If these actions
modify other members of the <code>data</code> object, then the <code>sideEffects</code> property must be set to
indicate this fact to the system.
</p><p>
If the <code>setter</code> function returns a value, then this value is considered to be the <code>actualValue</code>
to use in place of the original <code>value.</code> This enables placing constraints on the values
space of the editor element. If the <code>setter</code> function does not return any value, then the
values space will not be constrained.
</p></td></tr>
<tr><td class="V">format</td><td>Function</td><td>DISPLAY, SLIDER</td><td>
Dynamic value formatter for the editor element. If provided, this function will be called whenever
the element's value is displayed, using:
<p style="margin:10"><code>displayValue = format(value, <i>data</i>, <i>def</i>)</code></p>
Where <code>value</code> is the value to format, <code>data</code> is the editor's data object, and
<code>def</code> is this element's definition.
The <code>format</code> function should format the given <code>value</code> and return the result <code>displayValue.</td></tr></code>
<tr><td class="V">visible</td><td>Function</td><td>ALL</td><td>
Dynamic visibility state of the editor element:
<p style="margin:10"><code>flag = visible(<i>data</i>, <i>def</i>)</code></p>
Where <code>data</code> is the editor's data object, and <code>def</code> is this element's definition.
If the function returns <code>true</code> the element will be visible; otherwise, it will be hidden.
If this function is omitted, the element will be visible by default.</td></tr>
<tr><td class="V">active</td><td>Function</td><td>ALL</td><td>
Dynamic activation state of the editor element:
<p style="margin:10"><code>flag = active(<i>data</i>, <i>def</i>)</code></p>
Where <code>data</code> is the editor's data object, and <code>def</code> is this element's definition.
If the function returns <code>true</code> the element will be activated (enabled); otherwise, it will be deactivated (disabled).
If this function is omitted, the element will be active by default.</td></tr>
<tr><td class="V">sideEffects</td><td>Boolean</td><td>CHOICE, CUSTOM, INPUT, SLIDER, TOGGLE, TREE</td><td>
Indicates whether this editor element has side-effects that may require repainting other
elements in the editor. </td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Events</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">signal</td><td><q ref="core.lib:Global!SIGNAL_DEF">SIGNAL_DEF</q></td><td>ACTION</td><td>The signal to raise when the button is clicked</td></tr>
<tr><td class="V">ondrag</td><td>Function</td><td>DRAG</td><td>
This function will be called when the user starts to drag the element, using:
<p style="margin:10"><code>ondrag(dnd, def)</code></p>
Where <code>dnd</code> is the drag and drop object (see <q ref="core.dev:Controller!DND_OBJECT">DND_OBJECT</q>) and <code>def</code> is this definition.
Use this function to perform any setup required prior to the drag and drop operation.</td></tr>
<tr><td class="V">ondrop</td><td>Function</td><td>DRAG</td><td>
This function will be called when the user drops the element, using:
<p style="margin:10"><code>ondrop(dnd, def)</code></p>
Where <code>dnd</code> is the drag and drop object (see <q ref="core.dev:Controller!DND_OBJECT">DND_OBJECT</q>) and <code>def</code> is this definition.
The <code>dnd</code> parameter is provided only if the element was dropped on a valid target (otherwise, <code>dnd</code> will be <code>null).</code>
Use this function to carry out the relevant actions and cleanup the drag and drop operation.</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Rules</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">dragRule</td><td>String</td><td>DRAG</td><td>
Holds the Rule name that can be executed from within the ondrag function implementation.</td></tr>
<tr><td class="V">dropRule</td><td>String</td><td>DRAG</td><td>
Holds the Rule name that can be executed from within the ondrop function implementation.</td></tr>
<tr><td colspan="4" style="background:white"><br/><b>Owner Draw</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Applies to</td><td class="H">Description</td></tr>
<tr><td class="V">paint</td><td>Function</td><td>CUSTOM</td><td>
Custom paint function to use for building the element's HTML markup. This function will be called
when the element is first constructed, using:
<p style="margin:10"><code>elem = paint(def, parent)</code></p>
Where <code>def</code> is this definition and <code>parent</code> is the HTML container into which the new element needs to be added.
The <code>paint</code> function should create the new element under the given parent element, and return the new element to its caller.</td></tr>
<tr><td class="V">repaint</td><td>Function</td><td>CUSTOM</td><td>
Custom value repaint function for the element. This function will be called whenever
the element's value is changed, using:
<p style="margin:10"><code>elem.repaint(value)</code></p>
Where <code>elem</code> is the element's HTML object (can be referenced using the <code>this</code> keyword) and
<code>value</code> is the new element's value (for data bound elements).
The <code>repaint</code> function should repaint the element according to its new value.</td></tr>
<tr><td class="V">capture</td><td>Function</td><td>CUSTOM</td><td>
Custom capture function for the element. This function will be called whenever
the value stored in the element needs to be captured, using:
<p style="margin:10"><code>value = elem.capture()</code></p>
Where <code>elem</code> is the element's HTML object (can be referenced using the <code>this</code> keyword).
The <code>capture</code> function should obtain the element's value and return it to its caller.</td></tr>
<tr><td class="V">setVisible</td><td>Function</td><td>CUSTOM</td><td>
Custom function for setting the element's visiblity state, in the form:
<p style="margin:10"><code>elem.setVisible(visible)</code></p>
Where <code>elem</code> is the element's HTML object (can be referenced using the <code>this</code> keyword) and
<code>visible</code> is the new element's visibility state.</td></tr>
<tr><td class="V">setActive</td><td>Function</td><td>CUSTOM</td><td>
Custom function for setting the element's activation state, in the form:
<p style="margin:10"><code>elem.setActive(active)</code></p>
Where <code>elem</code> is the element's HTML object (can be referenced using the <code>this</code> keyword) and
<code>active</code> is the new element's activation state.</td></tr>
</table>
<h2>Data Binding</h2>
<p>
Data binding is the mechanism by which data is read from or written to the different editor elements.
The data type depends on the element type, according to the <code>Datatype</code> column in the element types table above (<code>N.A.</code> indicates
that the element does not support data binding).
</p><p>
Typically, the editor is bound to a data object which serves as the data source for its
elements. Each editor element corresponds to a member of the data object with the
same name. Whenever the value of an element is changed, the value of the corresponding member
in the data object will be updated to reflect the change, and vice versa. The concrete mechanism by
which the data binding is achieved depends on the implementation of the component that renders the editor
(see, for example, <q ref="core.lib:SmartForm">SmartForm</q>).
</p>
<h2>Dynamic Constraints</h2>
<p>
All dynamic constraints (<code>getter,</code> <code>setter,</code> <code>visible,</code> and <code>active)</code> can be written as a JavaScript function with the specific parameters described above,
or as a string containing a simple JavaScript expression according to the following rules:
<ol><li>Use a single statement that evaluates to the expected return value, or use a statement block ending with an explicit <code>return</code> statement. </li><li>Access the parameters <code>data,</code> <code>value,</code> and <code>definition</code> directly by their names. </li><li>Access members of the data object by prefixing their names with the '@' symbol (i.e., <code>@field</code> is equivalent to <code>data.field).</code> Use @@ to access the current <code>value</code> parameter. </li></ol>
<p>
Dependencies created using the shortcut notation (3) above are detected by the system and thus do not need to
be declared explicitly with the <code>sideEffects</code> property. For example:
</p>
<pre>
{ id:'min', type:'int', sideEffects:true},
{ id:'max', type:'int', sideEffects:true},
{ id:'xyz', type:'int',
setter:function(value, data, definition) {
var minValue = data.min;
var maxValue = data.max;
var theValue = LIMIT(minValue, value, maxValue);
if (theValue % 10 != 0) theValue = ROUND(theValue/10)*10;
return theValue;
}
}
</pre>
is equivalent to:
<pre>
{ id:'min', type:'int'},
{ id:'max', type:'int'},
{ id:'xyz', type:'int', setter:'ROUND(LIMIT(@min, value, @max),10)' }
</pre>
Note how, in the second form, the <code>sideEffects</code> property is inferred from the references made in the <code>setter</code> expression.
</p>
<h2>Cross Reference</h2>
<table class="BOTH"><tr><td class="H V">Property </td><td class=H>ACTION </td><td class=H>CHOICE </td><td class=H>CUSTOM </td><td class=H>DISPLAY </td><td class=H>DRAG </td><td class=H>INPUT </td><td class=H>SLIDER </td><td class=H>STATIC </td><td class=H>TOGGLE </td><td class=H>TREE </td></tr><tr><td class=V>active </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>arrow </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>capture </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>columns </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>content </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td></tr><tr><td class=V>descr </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>domain </td><td> </td><td>! </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td>! </td></tr><tr><td class=V>dragRule </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>dropRule </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>expand </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td></tr><tr><td class=V>flat </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td></tr><tr><td class=V>format </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>frame </td><td> </td><td>+ </td><td> </td><td>+ </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td>+ </td></tr><tr><td class=V>getter </td><td> </td><td>+ </td><td>+ </td><td>+ </td><td> </td><td>+ </td><td>+ </td><td> </td><td>+ </td><td>+ </td></tr><tr><td class=V>height (abs) </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>height (flow) </td><td> </td><td>+ </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td>+ </td></tr><tr><td class=V>icon </td><td>+ </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>id </td><td>+ </td><td>! </td><td>! </td><td>! </td><td>+ </td><td>! </td><td>! </td><td>+ </td><td>! </td><td>! </td></tr><tr><td class=V>inner </td><td> </td><td>+ </td><td> </td><td>+ </td><td> </td><td>+ </td><td>+ </td><td>+ </td><td> </td><td>+ </td></tr><tr><td class=V>label </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>left (abs) </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>max </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>maxLabel </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>min </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>minLabel </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>ondrag </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>ondrop </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>outer </td><td>+ </td><td>+ </td><td> </td><td>+ </td><td> </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>paint </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>popup </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>priority </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>repaint </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>setter </td><td> </td><td>+ </td><td>+ </td><td> </td><td> </td><td>+ </td><td>+ </td><td> </td><td>+ </td><td>+ </td></tr><tr><td class=V>sideEffects </td><td> </td><td>+ </td><td>+ </td><td> </td><td> </td><td>+ </td><td>+ </td><td> </td><td>+ </td><td>+ </td></tr><tr><td class=V>signal </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>step </td><td> </td><td> </td><td> </td><td> </td><td> </td><td>+ </td><td>+ </td><td> </td><td> </td><td> </td></tr><tr><td class=V>style </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>toggle </td><td> </td><td> </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr><tr><td class=V>top (abs) </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>type </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td><td>! </td></tr><tr><td class=V>visible </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>width (abs) </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td><td>+ </td></tr><tr><td class=V>width (flow) </td><td>+ </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr></table>
<p style="padding:0 24;">LEGEND: + optional, ! required</p><q ref="core.env:KitEditors!EDITOR_DEF">EDITOR_DEF</q> | <q ref="core.env:KitEditors!EDITOR_GROUP">EDITOR_GROUP</q>
Defines a group container holding other editor elements.<p style="width:90%">All editor elements always belong to exactly one editor group.
The elements that belong to a group start with the first element following the group,
and continue until the next group, or until the last element in the editor definition.
If the first element in an editor definition is not a group, then a default group
will be implicitly created. The group definition is made of the following properties:</p>
<table class="BOTH" width="95%">
<tr><td colspan="3" style="background:white"><br/><b>General</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Description</td></tr>
<tr><td class="V">id</td><td>QName</td><td>Group identifier (optional)</td></tr>
<tr><td class="V">type</td><td>String</td><td>Always set to <code>group</td></tr></code>
<tr><td class="V">sortBy</td><td>String</td><td>The sortBy holds the name of the attribute to sort the group's properties by. By default it is set to 'label'.</td></tr>
<tr><td colspan="3" style="background:white"><br/><b>Display</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Description</td></tr>
<tr><td class="V">title</td><td>String</td><td>The text to display in the group's titlebar. If omitted, the group's titlebar will not be shown.</td></tr>
<tr><td class="V">descr</td><td>String</td><td>The description to display in the group's tooltip</td></tr>
<tr><td class="V">toggle</td><td>Enum</td>
<td>The group's toggle mode, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>Group has no toggle (default)</td></tr>
<tr><td>ON</td><td>Group has toggle, initially expanded</td></tr>
<tr><td>OFF</td><td>Group has toggle, initially collapsed</td></tr>
<tr><td>LAST</td><td>Group expands/collapses together with the last group that has a toggle</td></tr>
</table>
</td></tr>
<tr><td colspan="3" style="background:white"><br/><b>Styles</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Description</td></tr>
<tr><td class="V">color</td><td>Enum</td>
<td>The group's background color, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No background (default)</td></tr>
<tr><td>WHITE</td><td>White background</td></tr>
<tr><td>GRAY</td><td>Gray background</td></tr>
<tr><td>LIGHT</td><td>Light color background</td></tr>
<tr><td>DARK</td><td>Dark color background</td></tr>
<tr><td>DIALOG</td><td>Default dialog background</td></tr>
</table>
</td></tr>
<tr><td class="V">frame</td><td>Enum</td>
<td>The group's frame style, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No frame (default)</td></tr>
<tr><td>SOLID</td><td>Draw a solid frame inside the group's margins</td></tr>
<tr><td>INSET</td><td>Draw a sunken frame inside the group's margins</td></tr>
<tr><td>TOPLEVEL</td><td>Draw a top-level frame and titlebar around the group's exterior</td></tr>
</table>
</td></tr>
<tr><td class="V">palette</td><td>Enum</td>
<td>The group's palette style for defining how drag elements in the group will be displayed, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">INHERIT</td><td>Inherit global palette style (default)</td></tr>
<tr><td>PAL-I32D</td><td>Display 32x32 icons and full descriptions, arranged in a vertical list</td></tr>
<tr><td>PAL-I32L</td><td>Display 32x32 icons plus names, arranged in a vertical list</td></tr>
<tr><td>PAL-I32N</td><td>Display 32x32 icons plus names, arranged in a grid</td></tr>
<tr><td>PAL-I32</td><td>Display only 32x32 icons, arranged in a grid</td></tr>
<tr><td>PAL-I16L</td><td>Display 16x16 icons plus names, arranged in a vertical list</td></tr>
<tr><td>PAL-I16</td><td>Display only 16x16 icons, arranged in a grid</td></tr>
<tr><td>PAL-LIST</td><td>Display only names, arranged in a vertical list</td></tr>
<tr><td>PAL-BUL</td><td>Display only names, arranged in a vertical list with bullets</td></tr>
</table>
</td></tr>
<tr><td class="V">divider</td><td>Enum</td>
<td>The type of divider(s) to add to the group, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No divider (default)</td></tr>
<tr><td>ABOVE</td><td>Solid line drawn at the top of the group</td></tr>
<tr><td>BELOW</td><td>Solid line drawn at the bottom of the group</td></tr>
<tr><td>BOTH</td><td>Both dividers, above and below the group</td></tr>
</table>
</td></tr>
<tr><td class="V">caption</td><td>Enum</td>
<td>The group's titlebar style, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No title</td></tr>
<tr><td>BOLD</td><td>Show title in bold text (default)</td></tr>
<tr><td>PLAIN</td><td>Show title in normal text</td></tr>
<tr><td>ITALIC</td><td>Show title in italic text</td></tr>
<tr><td>UNDERLINE</td><td>Show title in bold text and with an underline</td></tr>
</table>
</td></tr>
<tr><td class="V">scroll</td><td>Enum</td>
<td>The group's scrolling options, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">NONE</td><td>No scrollbars (default for auto-fit and fixed-size groups)</td></tr>
<tr><td>AUTO</td><td>Show scrollbars when needed (default for variable-size groups)</td></tr>
<tr><td>ALWAYS</td><td>Always show scrollbars</td></tr>
</table>
</td></tr>
<tr><td class="V">style</td><td>String</td><td>Custom styling rules to apply on the group</td></tr>
<tr><td colspan="3" style="background:white"><br/><b>Layout</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Description</td></tr>
<tr><td class="V">layout</td><td>Enum</td>
<td>The group's elements layout, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">FLOW</td><td>Arrange the group's elements in a vertical flow (default)</td></tr>
<tr><td width="75">ABSOLUTE</td><td>Arrange the group's elements using absolute positioning (requires that the group has a fixed height)</td></tr>
</table>
</td>
</tr>
<tr><td class="V">height</td><td>Enum</td>
<td>The group's height, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">FIT</td><td>Automatically fit size to contents (default)</td></tr>
<tr><td><i>nnn</i></td><td>Fixed size, in pixels</td></tr>
<tr><td><i>nnn</i>%</td><td>Variable size, as percentage of available freespace</td></tr>
</table>
When the group has an absolute layout, then the height must be a fixed number of pixels.
</td>
</tr>
<tr><td class="V">align</td><td>Enum</td>
<td>Indicates how to align floating elements (such as buttons or static content) within the group, according to:
<table style="margin:7 14;" cellspacing="0">
<tr><td width="75">LEFT</td><td>Align left (default)</td></tr>
<tr><td>CENTER</td><td>Align center</td></tr>
<tr><td>RIGHT</td><td>Align right</td></tr>
</table>
</td></tr>
<tr><td class="V">outer</td><td>Number</td><td>The group's default outer margin (gutter), in grid units</td></tr>
<tr><td class="V">inner</td><td>Number</td><td>The group's default inner margin (indentation), in grid units</td></tr>
<tr><td colspan="3" style="background:white"><br/><b>Constraints</b></td></tr>
<tr><td class="H">Property</td><td class="H">Type</td><td class="H">Description</td></tr>
<tr><td class="V">visible</td><td>Function</td><td>
Dynamic visibility state of the editor group:
<p style="margin:10"><code>flag = visible(<i>data</i>, <i>definition</i>)</code></p>
Where <code>data</code> is the editor's data object, and <code>definition</code> is this group's definition.
If the function returns <code>true</code> the group will be visible; otherwise, it will be hidden.
If this function is omitted, the group will be visible by default.</td></tr>
<tr><td class="V">active</td><td>Function</td><td>
Dynamic activation state of the editor group:
<p style="margin:10"><code>flag = active(<i>data</i>, <i>definition</i>)</code></p>
Where <code>data</code> is the editor's data object, and <code>definition</code> is this group's definition.
If the function returns <code>true</code> the group will be activated (enabled); otherwise, it will be deactivated (disabled).
If this function is omitted, the group will be active by default.</td></tr>
</table>
<p style="width:90%">
For best visual appearance, it is recommended to group editor elements by their type and cardinality.
</p><q ref="core.env:KitEditors!EDITOR_DEF">EDITOR_DEF</q> | <q ref="core.env:KitEditors!EDITOR_ELEM">EDITOR_ELEM</q>