-
Notifications
You must be signed in to change notification settings - Fork 32
Designer 2.0 Component Parameters
<parameters>
<parameter name="dontCacheDescription">true</parameter>
</parameters>Specifies that description for this component should not be cached even if the package has «.wbp-cache-descriptions» file, so it requires caching by default.
<parameters>
<parameter name="layout.has" value="false"/>
</parameters>Parameter «layout.has» specifies if this component has layout manager (supported by Swing and eSWT).
<parameters>
<parameter name="variable.name" value="tree"/>
<parameter name="variable.acronym" value="tree"/>
</parameters>Parameters «variable.name» and «variable.acronym» specify default variable name and acronym for this component. So, component developer can tweak code generation. For example for javax.swing.JTree we can specify that acronym «tree» should be used, not auto generated «tr».
<parameter name="variable.validateID"><![CDATA[
import com.instantiations.designer.core.model.variable.description.*;
if (id == FieldInitializerVariableDescription.ID) {
id = FieldUniqueVariableDescription.ID;
}
return id;
]]></parameter>Parameter "variable.validateID" is script that can validate that given variable «id» can be used for this component, and return alternative variable.
<parameter name='visible.inTree'>false</parameter>
<parameter name='visible.inGraphical'>false</parameter>These parameters specify if component should be visible in components tree and design canvas.
<parameter name="objectReadyValidator">component.parent != null</parameter>ExpressionAccessor's get default values from component object, but sometimes just fact that component has object is not enough to allow invocation of getters and reading from fields. For example GWT-Ext requires that component should be bound to parent (so its DOM Element rendered) before we can invoke most of its methods. So, we need some way to allow component specify that it is ready. Following variables are defined for script:
- «component» - the toolkit object.
<parameters>
<parameter name="gridLayout.grabHorizontal" value="true"/>
<parameter name="gridLayout.grabVertical" value="true"/>
<parameter name="gridLayout.rightAlignment.isLabel" value="true"/>
<parameter name="gridLayout.rightAlignment.isTarget" value="true"/>
</parameters>In grid-based layouts (such as SWT GridLayout, Swing GridBagLayout and Jgoodies FormLayout), components may be automatically aligned when dropped into layout.
- «gridLayout.grabHorizontal» means that component's column will grab excess space, and component fills the column horizontally.
- «gridLayout.grabVertical» means that component's row will grab excess space, and component fills the row vertically.
- «gridLayout.rightAlignment.isLabel» means that this component is «label» like component (Label in SWT, Jlabel in Swing), so when it is on the same row as «text» like component, and directly on left of it, then «label» should be aligned right.
- «gridLayout.rightAlignment.isTarget» means that this component is «text» like component, for example Text in SWT, JtextField in Swing.
<parameters>
<parameter name="tabOrder.isNotOrdered" value="true"/>
</parameters>Mark components that does not accept focus using this parameter, so they will be excluded from setting the tab order.
<parameter name="tabOrder.disable">true</parameter>Disables displaying «tab order» property for this component.
<parameter name="databinding.disable">true</parameter>Disables displaying «bindings» property for this component.
<parameters>
<parameter name="double-click.listener" value="action/performed"/>
</parameters>Specifies that on double click on component, event listener with name «action» and its method «performed» will be opened. So, you can easily configure your custom components to generate/open often used event listener using double click.
<parameter name="events: no listeners of class">javax.swing.JPanel</parameter>WindowBuilder automatically discovers methods «addXListener» and «addXHandler» using reflection and shows them as event listeners. Using this parameter you specify that you don't want to show user listeners declared in specified class and any of its superclasses. This is useful if you build specialized component and don't want to overload user with bunch of listeners inherited from Swing (for example).
<parameters>
<parameter name="viewer.control.method" value="getTable"/>
</parameters>For JFace Viewer, specifies name of method (without arguments) that returns Control.
<parameters>
<parameter name="layoutData.exclude-properties" value="Class Constructor"/>
</parameters>For SWT «layout data» objects, we may exclude some properties, because they don't add any new information. For example «class» is not needed for LayoutData, it is already displayed as text. Also for RowData all constructor properties are mapped to fields, so no need to show «Constructor» property. So, we can perform some «fine tuning». It's not important, just nice to have.
<parameters>
<parameter name="layout-data.has" value="true"/>
<parameter name="layout-data.class" value="org.eclipse.swt.layout.RowData"/>
</parameters>For SWT Layout, specifies that this layout has LayoutData, and its type.
<parameters>
<parameter name="directEdit.location.insets" value="5 25 0 0"/>
<parameter name="directEdit.location.horizontalAlignment" value="left"/>
<parameter name="directEdit.location.verticalAlignment" value="top"/>
</parameters>Parameters for direct edit.
- «directEdit.location.insets» insets for component bounds;
- «directEdit.location.horizontalAlignment» horizontal alignment of text widget, possible values: «center» (or empty, i.e. no alignment specified), «left».
- «directEdit.location.verticalAlignment» vertical alignment of text widget, possible values: «center» (or empty, i.e. no alignment specified), «top». For buttons, labels, texts - «center» is good default. For JFrame, Shell and other windows - «left» and «top» alignments with reasonable insets can be used.
<!-- flip expanded -->
<parameter name="double-click.flipBooleanProperty">expanded</parameter>Flips given boolean property between true/false values when user double clicks component on design canvas. If no such property, double click is ignored. If property value is not boolean, double click is ignored. Note that you can specify «/» separated path, not just title of property.
<!-- select it on double click -->
<parameter name="double-click.runScript">doSelect()</parameter>Runs specified MVEL script with model as context.
<!-- flow container (canvas and tree) -->
<parameter name="flowContainer">true</parameter>
<parameter name="flowContainer.horizontal">true</parameter>
<parameter name="flowContainer.association">%parentAccess%add(%child%)</parameter>
<!-- flowContainer for design canvas -->
<parameter name="flowContainer.canvas">true</parameter>
<parameter name="flowContainer.horizontal">true</parameter>
<parameter name="flowContainer.canvas.association">%parentAccess%add(%child%)</parameter>
<!-- two containers – for TableColumn and TableItem -->
<parameter name="flowContainer.1">true</parameter>
<parameter name="flowContainer.1.horizontal">true</parameter>
<parameter name="flowContainer.1.component">TableColumn</parameter>
<parameter name="flowContainer.1.reference">TableColumn</parameter>
<parameter name="flowContainer.2">true</parameter>
<parameter name="flowContainer.2.horizontal">false</parameter>
<parameter name="flowContainer.2.component">TableItem</parameter>
<parameter name="flowContainer.2.reference">TableItem</parameter>
<!-- flowContainer for tree -->
<parameter name="flowContainer.tree">true</parameter>
<parameter name="flowContainer.tree.association">%parentAccess%add(%child%)</parameter>
<!-- flowContainer defaults -->
<parameter name="flowContainer.defaultComponent">com.google.gwt.user.client.ui.Widget</parameter>
<parameter name="flowContainer.defaultReference">com.google.gwt.user.client.ui.Widget</parameter>
<!-- list of types -->
<parameter name="flowContainer.component">org.eclipse.nebula.widgets.grid.GridColumn org.eclipse.nebula.widgets.grid.GridColumnGroup</parameter>
<!-- MVEL script as validator -->
<parameter name="flowContainer.component-validator"><![CDATA[
isComponentType('org.eclipse.nebula.widgets.grid.GridColumn') ||
isComponentType('org.eclipse.nebula.widgets.grid.GridColumnGroup')
]]></parameter>
<parameter name="flowContainer.reference-validator"><![CDATA[
isReferenceType('org.eclipse.nebula.widgets.grid.GridColumn') ||
isReferenceType('org.eclipse.nebula.widgets.grid.GridColumnGroup')
]]></parameter>WindowBuilder supports declarative flow based containers, i.e. containers where children components can be placed before/after each other. Flow containers may be horizontal or vertical, accept some type of components, user same or different type of existing children components as references to add/move before them.
When just «flowContainer» is specified, then flow container for both design canvas and components tree is declared. When «flowContainer.canvas» and «flowContainer.tree» you can specify separate settings for design canvas and components tree.
You can use «.number» prefix to specify up to 10 separate flow containers with different types or components and references. For example for SWT Table you need to use two – for TableColumn and TableItem.
Parameter «flowContainer.horizontal» specifies if container is horizontal on design canvas. In components tree, items are always layed out vertically, so «flowContainer.horizontal» is ignored for the tree. You can use not only static values «true» or «false», but also MVEL expressions, such as «isHorizontal()» that will be evaluated using JavaInfo model for container as context.
Parameters «flowContainer.component» or «flowContainer.reference» specify what kind of components can be dropped on this container and can be used as reference to drop before. You can use single name of type or space separated list of them. When only «flowContainer.component» is specified, the same validator is used for references.
If you need to perform more complex check for component/reference, you can specify «flowContainer.component-validator» and «flowContainer.reference-validator». In these scripts you can use variables «container», «component» and «reference». Also, you can use methods «isComponentType()» and «isReferenceType()» to check that component or reference are subclasses of given one. You can also call any methods of «container», «component» and «reference».
Often all containers in the same toolkit accept same type of components and references, for example «org.eclipse.swt.widgets.Control» is SWT or «com.google.gwt.user.client.ui.Widget» in GWT. So, it is convenient to use «flowContainer.defaultComponent» and «flowContainer.defaultReference» for superclass of all containers and don’t specify them separately in each place (but you may if you want). Note, that defaults are used only when you don't specify both – component and reference validators.
Parameter «flowContainer.association» specifies the child component's association with this flow container. It is required for add/move operations in JavaInfoUtils. The following types of associations are supported:
- «invocationChild» - usual association in Swing and GWT, when a child is passed into the «add» method, it requires exact specification of method after the space «%parentAccess%add(%child%)». Since this type of association is often used, it does not require a separate «invocationChild» prefix, you can just write the invocation itself.
<!-- simple container -->
<parameter name="simpleContainer">true</parameter>
<parameter name="simpleContainer.association">%parentAccess%setWidget(%child%)</parameter>WindowBuilder supports declarative «simple» containers, i.e. containers that accept only one component.
When «simpleContainer» (without specifying canvas or tree) is specified, then simple container for both the design canvas and components tree is declared. When «simpleContainer.canvas» and «simpleContainer.tree» you can specify separate settings for design canvas and components tree.
Parameter «simpleContainer.component» specifies what kind of components can be dropped on this container. You can use a single name of type or a space-separated list of types.
Oftentimes, all containers in the same toolkit accepts the same type of components and references, for example «org.eclipse.swt.widgets.Control» in SWT or «com.google.gwt.user.client.ui.Widget» in GWT. So, it is convenient to use «simpleContainer.defaultComponent» for superclass of all containers and don’t specify it separately in each place (but you may if you want).
Parameter «simpleContainer.association» specifies the child component's association with this flow container. It is required for add/move operations in JavaInfoUtils. The following types of associations are supported:
- «invocationChild» - the usual association in Swing and GWT, when a child is passed into the «add» method. It requires an exact specification of the method after a space «%parentAccess%add(%child%)». Since this type of association is often used, it does not require any separate «invocationChild» prefix, you can just write the invocation itself.
<!-- bounds for DialogBox -->
<parameter name="applyTopBoundsScript"><![CDATA[
widget.getWidget().setSize(size.width, size.height);
widget.show();
]]></parameter>
<!-- bounds for Composite -->
<parameter name="applyTopBoundsScript"><![CDATA[
rootPanel.add(widget);
widget.setSize(size.width, size.height);
]]></parameter>For some components in GWT you can not set the size directly. See http://code.google.com/p/google-web-toolkit/issues/detail?id=2595, on how to write a script to do this. The following variables are defined in the script:
- «DOM» - the GWT DOM class;
- «rootPanel» - the instance of RootPanel;
- «widget» - the instance of the top level widget;
- «size» - the size of the widget requested by the user; has properties «width» and «height»;
<parameter name="setTopBoundsScript"><![CDATA[
content = model.getWidget();
if (content != null) {
panelSize = model.bounds.size;
contentSize = content.bounds.size;
newContentWidth = size.width - (panelSize.width - contentSize.width);
newContentHeight = size.height - (panelSize.height - contentSize.height);
model.widget.setSize(newContentWidth, newContentHeight);
}
]]></parameter>Allows some operations to be performed when user resizes this top level component.
The following variables are defined in the script:
- «DOM» - the GWT DOM class;
- «rootPanel» - the instance of RootPanel;
- «widget» - the instance of the top level widget;
- «size» - the size of the widget requested by the user; has properties «width» and «height»;
<parameter name="copyChildPropertyTop from=Association/direction to=Direction category=system(7)"/>
<parameter name="copyPropertyTop from=Constructor/columnWidth to=width category=normal"/>Adds copying of given property (usually part of some complex property) as the top level. The following attributes are supported:
- «from» - the «/» separated path to the source property;
- «to» - the name of the top level target property;
- «category» - the category of the target property, may be «preferred», «normal», «advanced», «hidden» or «system(int)»;
<parameter name="modelMethodProperty getter=getAnchor setter=setAnchor type=java.lang.String title=anchor"/>
<parameter name="modelMethodChildProperty getter=getWidth setter=setWidth title=Width category=system(7) type=java.lang.String child=com.instantiations.designer.gwt.model.widgets.Widget_Info"/>Adds a new property to component/its_child that is bound to getter/setter method in JavaInfo model.
<parameter name="GEF.requestValidator.parent">true</parameter>
<parameter name="GEF.requestValidator.child"><![CDATA[
isComponentType(parent, 'org.eclipse.swt.widgets.Table') && parent.object.itemCount <= 2
]]></parameter>Sometimes, you need to add limitations on what children can be dropped on a parent (during create/paste/move/add operations).
So, you can specify two MVEL scripts:
- «GEF.requestValidator.parent» - for parent, to check all possible children. If no such script, then «true».
- «GEF.requestValidator.child» - for child, to check that this child can be dropped only on some specific parents. For example, here we check that «parent» is a SWT Table that has no more than 2 items. If no such script, then «true».
Following variables and functions can be used:
- «parent» - the parent where we are going to drop the child;
- «child» - the child to drop;
- «isComponentType(javaInfo, componentClassName)» - checks that given object is JavaInfo and its component type is instance of given one.
- «ReflectionUtils» - class with many Class/Method/Field utils.
In addition, WindowBuilder, always checks that constructor/factory of the child is compatible with the parent (i.e. you can pass the parent as a parameter into the constructor/factory, if needed).
If one of the conditions (compatibility or parent/child scripts) is false, then parent becomes «transparent» for this child, so request will be passed to the parent.
<parameter name="GEF.transparentOnBorders.always">true</parameter>Specifies that EditPart for this model is «transparent» on borders, in 3 pixels. This is useful when we know that the container places these children without a gap between them, so to hit container between children we need to make them transparent.
NOTE: may be we should replace this with some parameter for container, because container knows how it lays out its children.
<parameter name="refresh_afterCreate"><![CDATA[
import com.google.gwt.user.client.ui.*;
if (object.getItemCount() == 0) {
object.addItem("Empty Tree.");
object.addItem("Drop items in structure.");
}
]]>
</parameter>Script «refresh_afterCreate» allows you to tweak created component object, for example show some message if the component can accept some children or some properties should be set.
<parameter name="parser.preferredRoot">true</parameter>Sometimes after parsing we have more than one possible root JavaInfo. Usually we select the root that has the biggest hierarchy. However, sometimes we know that there is a better choice. For example, GWT 1.6 examples use RootPanel and also create DialogBox. We want to show the RootPanel, because it is the entry point, and DialogBox is something dynamic. So, we mark the RootPanel with this tag and it is always selected as the preferred root. Note, that if there are more than one preferred roots, the actual root will be selected by size of hierarchy.
<parameter name="GEF.clickToParent">true</parameter>If some model is marked with this parameter, then clicking on it on the design canvas will move the selection request to the parent. In most cases, this will cause parent selection instead of this model selection. This is used for example in ApplicationWindow, where, because of binary execution flow we have several model for the same Shell object – window itself, «parent» parameter for method «createContents()». Without this parameter, clicking on window header will cause a «parent» selection. But the user expects the ApplicationWindow to be selected (for example to resize it).
<parameter name="topBounds.pack">true</parameter>Specifies that the superclass of this Swing Window has pack() invocation which means the default size (450x300) should not be applied to this Window.
<parameter name="Wrapper.method">getControl</parameter>Specifies the method used to access wrapped component of the viewer.
<parameter name="Wrapper.noWrapped.inConstructors">true</parameter>Specifies that this viewer (and its subclasses) has no constructors that accept wrapped component (for example CellEditor-s have no such constructors, but Jface Viewer-s have them). Or you can use "Wrapper.notWrapped" tag for single constructor or factory parameter.
<parameter name="liveComponent.forcedSize.use"><![CDATA[
isStrict && isExplorer
]]></parameter>
<parameter name="liveComponent.forcedSize.width">100px</parameter>
<parameter name="liveComponent.forcedSize.height">auto</parameter>WindowBuilder needs to create «live component image» when you drop component on absolute based containers/layouts. However, some components don't have reasonable preferred size, so user have to force it in description. In GWT, size can be any string that is a valid CSS size. Other toolkits support only integer. Also in GWT, you can use a script «liveComponent.forcedSize.use» to check if size should be applied, if problem happens only with specific OS/Browser.