Skip to content

Component ‐ Descriptions

Jump to bottom
Patrick Ziegler edited this page Dec 16, 2025 · 1 revision

Component Description: *.wbp-component.xml

<component>

<component>

The root element in a component description.

<description>

<description>A component that allows the user to select one or more objects from a list.</description>

Sets the description of the component to display on the palette.

<model>

<model class="">

Sets the class of the model – a subclass of JavaInfo.

<order>

<order>last</order>

The following component order parameters are supported:

  • «default» - place the component after any sibling.
  • «last» - place the component after any sibling.
  • «last» - place the component before any sibling, as the first child of the parent.
  • «beforeSibling nextComponentClass» - to place the component before components with given class. For example in table-like components, it is often a requirement that you create columns before items.

<creation>

<!-- CREATION -->
<creation>
	<source><![CDATA[new org.eclipse.swt.widgets.Button(%parent%, org.eclipse.swt.SWT.NONE)]]></source>
	<invocation signature="setText(java.lang.String)"><![CDATA["New Button"]]></invocation>
</creation>
<creation id="empty">
	<source><![CDATA[new org.eclipse.swt.widgets.Button(%parent%, org.eclipse.swt.SWT.NONE)]]></source>
</creation>
<creation id="check" name="Check Button">
	<source><![CDATA[new org.eclipse.swt.widgets.Button(%parent%, org.eclipse.swt.SWT.CHECK)]]></source>
	<invocation signature="setText(java.lang.String)"><![CDATA["Check Button"]]></invocation>
	<invocation signature="setSelection(boolean)"><![CDATA[true]]></invocation>
	<description>Instances of this class represent a selectable user interface object that issues notification when checked and unchecked.</description>
</creation>
<creation id="radio" name="Radio Button">
	<source><![CDATA[new org.eclipse.swt.widgets.Button(%parent%, org.eclipse.swt.SWT.RADIO)]]></source>
	<invocation signature="setText(java.lang.String)"><![CDATA["Radio Button"]]></invocation>
	<description>Instances of this class represent a selectable user interface object that issues notification when selected and unselected.</description>
</creation>

Specifies source code and method invocations that should be used to create this component using the constructor creation support (it is expected that the code in is an object created using the constructor).

Optional tags allow method invocations to be added directly after the component has been added. This is useful when setting the default text, selection, etc.

The «id» attribute can be used with the «creationId» attribute of the , in the in plugin.xml to specify several variants of creating components with the same type. For example, a SWT Button can be a push/check/radio button, but the only difference is the style specified in the constructor.

<standard-bean-properties>

<standard-bean-properties/>

Adds standard bean properties with getters and setters.

Property, is created only if Designer has an editor for this property type. For example, String, Icon, int, etc.

Each «standard» property has an id «signatureOfSetterMethod».

In the following tags, use the «name» attribute to specify property - rules of matching are following:

  • «m:nameOfMethod» - specifies that only the setter should be considered, and the name of the method is given;
  • «f:fieldName» - specifies the exact name of the field;
  • «setText(java.lang.String[])» - specifies the exact signature for setter;
  • «nameOfMethodOrField» - it first tries to find the setter with the given name, then tries to find a field with the given name.

<public-field-properties>

<public-field-properties/>

Adds field based properties.

Property is created only if Designer has an editor for this property type, for example String, Icon, int, etc.

Each «field» property has id «property:field: nameOfField».

<properties-preferred>

<properties-preferred names="text icon"/>

Specifies that the listed properties are preferred, i.e. properties often used with this component. For example text and image on a button. These properties are highlighted in the properties table (by default the bold font is used).

<properties-normal>

<properties-normal names="align valign"/>

Specifies that the listed properties are normal, so undo any special category settings specified in descriptions for superclass.

<properties-advanced>

<properties-advanced names="bounds location size maximumSize minimumSize preferredSize"/>

Specifies that the listed properties are advanced. Advanced properties are not displayed by default in the properties table. They are also painted with a different font and color (defaults to italic font and gray color). Specifying advanced properties reduces the number of properties listed in the properties table, and also speeds up searching.

<properties-hidden>

<properties-hidden names="UI label"/>

Specifies that listed properties should not be used at design time. These can cause some bad effects, so we don't want to show them to the user. There is no way for the user to make them visible.

<properties-noDefaultValue>

<properties-noDefaultValue names="pageLeft pageTop right bottom"/>

Specifies that there is no default value for these properties. This feature is used in GWT libraries, such as GWT-Ext and SmartGWT. These libraries have specific quirks - they create JavaScript object for reading value, and at the same time they don't allow to set many properties after creating object.

<property-tag>

<property-tag name="title" tag="isText" value="true"/>

Sets some tag for standard property. Designer uses these tags to interpret properties in some special way. For example «isText == true» means that this property is displayed as text for this component, so when the user requests direct edit, property «title» should be edited.

See other tag in table below.

<property>

<property id="setComponentOrientation(java.awt.ComponentOrientation)">
	<editor id="staticField">
		<parameter name="class">java.awt.ComponentOrientation</parameter>
		<parameter name="fields">UNKNOWN LEFT_TO_RIGHT RIGHT_TO_LEFT</parameter>
	</editor>
</property>

Specifies the editor for the property.

<property id="setDisplayedMnemonic(char)">
	<category value="preferred"/>
</property>

<property id="setDisplayedMnemonic(int)">
	<category value="advanced"/>
	<editor id="swing.displayedMnemonic"/>
</property>

Specifies category for the property. Possible values are: preferred, normal, advanced and hidden.

<property id="setUseHashlookup(boolean)">
	<defaultValue value="false"/>
</property>
<property id="setLabelAlign(com.gwtext.client.core.Position)">
	<defaultValue value="com.gwtext.client.core.Position.LEFT"/>
</property>

Specifies the default value for the property. This is useful, for example, when some «standard bean property» has only a «set» method, but not a «get» method, so we can not get the default value from the component instance. Any MVEL expression/script can be used, editor ClassLoader is set as context ClassLoader, so classes from the project can be referenced directly.

<property id="setFoo(int)">
	<getter name="getMyFoo"/>
</property>

Specifies the alternative «getter» method. Sometimes a «normal» setter method does not have a corresponding getter method. For example, for «setFoo» we expect «getFoo» as the getter method. To use a different getter method, specify <getter and give the name of the getter method.

<methods-include/exclude>

<methods-include signature="/set\w+\([^,]+\)/"/>
<methods-exclude signature="setVisible(boolean)"/>

Specifies that methods with given signature should be included/excluded in the set of executable methods. Designer executes only the methods included in the executable set, invocations of other methods that are present in the source code are ignored.

If the signature starts with «/» then it is handled as a regular expression.

<method>

<method name="setLocation" order="beforeAssociation">
	<parameter type="int"/>
	<parameter type="int"/>
	<tag name="tagName" value="tagValue"/>
</method>

Specifies executable method with parameters of the given type. See the description for the «parameter» tag below:

«order» - specifies the location for invoking this method. See the «method-order» for a full description.

«tag» element provides a way to set some tag for a method. Known tags are:

  1. «noFactory» used to indicate that this method should not be marked as “extracted” by default, when we open the «Extract Factory» dialog.
  2. and much more... no description yet...

<parameter>

<parameter type="" [name=""] [parent="true/false"] [child="true/false"] [parent2="true/false"] [child2="true/false"] [property="id"] [defaultSource=""]>
	<editor .../>
</parameter>

Describes the parameters for the method or constructor.

  • «type» – the fully qualified type of the parameter, for example «int» or «java.lang.String»;
  • «parent» - is «true» if the parameter is a parent of the component, for example in SWT, the parent is passed in the constructor;
  • «child» - is «true» if parameter is child of this component, for example in Swing the method «add(java.awt.Component)» receives the child.
  • «parent2»/«child2» - if a pair of parameters is defined, the invocation of the method creates a parent/child link. For example, it is possible to create a method like «addInGrid(x, y, parent, child)» that adds the given child on the given parent in the specified grid cell.
  • «property» - specifies the id of property to which this parameter is bound. It is usually used in the constructor description. Oftentimes, in Swing, there are several constructors with text/image/etc properties.
  • «defaultSource» - another attribute that is useful mainly for constructors. When the user asks for «cleaning» property, we use this source (because we can not remove the argument of the constructor). If there is no «defaultSource», «cleaning» will do nothing.
  • «editor» - tag that allows to specify the editor for this parameter, usually in the constructor. If there is no «editor» attribute defined, type based editor will be used.

<method-order>

<method-order>
	<default order="afterAssociation"/>
	<method signature="setScrollPosition(int)" order="last"/>
	<methods order="beforeAssociation">
		<s>setEnabled(boolean)</s>
		<s>setSelected(boolean)</s>
	</methods>
</method-order>

The following order parameters are supported:

  • «last» - after any related statement and any child.
  • «afterCreation» - directly after the creation statement. This order is used by default.
  • «beforeAssociation» - before the statement that associates this component with its parent, for example before panel.add(component) invocation.
  • «afterAssociation» - after the statement that associates this component with its parent. In GWT libraries some properties should be set before, and some – after association.
  • «after methodSignature» - after invocation of a method with the specified signature. If no invocation with such signature, the default association will be used, and when «methodSignature» will be added, it will be added before the method is marked so.
  • «afterLastStatement» - after any related statement, but before any child.

Tags:

  • «default» - specifies default position for any method invocation of this component and its subclasses. Only the following orders can be used as default: afterCreation, beforeAssociation, afterAssociation and afterLastStatement.
  • «method» - specifies the method order for a single method.
  • «methods» and «s» (signature) – convenient way to specify the same order for multiple methods.

<method-property>

<method-property title="text" method="setText(java.lang.String,boolean,boolean)"/>

<property id="setText(java.lang.String,boolean,boolean)">
	<category value="advanced"/>
</property>

<methods>
	<method name="setAlignment">
		<parameter type="int">
			<editor id="staticField">
				<parameter name="class">org.eclipse.swt.SWT</parameter>
				<parameter name="fields">LEFT CENTER RIGHT</parameter>
			</editor>
		</parameter>
		<parameter type="int">
			<editor id="staticField">
				<parameter name="class">org.eclipse.swt.SWT</parameter>
				<parameter name="fields">TOP CENTER BOTTOM</parameter>
			</editor>
		</parameter>
	</method>
</methods>

<method-property title="alignment" method="setAlignment(int,int)"/>

Specifies that complex property for some method with several parameters should be created. The ID for such property is the same as signature of the method (i.e. practically the same as value of the «method» attribute). This property will have a sub-property for each parameter. Title of the sub-property is the same as the name of the corresponding parameter. The ID for the parameter property is «methodSignature parameterIndex».

You can specify the name, default source and editor in the corresponding method parameter description.

<method-single-property>

<method-single-property title="myFoo" method="foo(int)"/>

Specifies that a property with the title «myFoo» should be created. This is the same as the property created by <standard-bean-properties/>, but the method is not a setter, therefore we need to specify it directly. Id of such property is «foo(int)».

<constructors>

<constructors>
	<constructor>
		<parameter type="javax.swing.Icon" property="setIcon(javax.swing.Icon)"/>
	</constructor>
	<constructor>
		<parameter type="java.lang.String" property="setText(java.lang.String)"/>
	</constructor>
	<constructor>
		<parameter type="java.lang.String" property="setText(java.lang.String)"/>
		<parameter type="javax.swing.Icon" property="setIcon(javax.swing.Icon)" defaultSource="null"/>
	</constructor>
</constructors>

Describes one or more constructors, similar to methods with a tag and one or more tags. You don't have to describe all the constructors. Descriptions are useful if you want to bind parameters to properties, specify editors, parent/child attributes, etc.

<exposing-rules>

<exposing-rules>
	<exclude package="java.awt"/>
	<exclude package="javax.swing"/>
	<include method="getContentPane"/>
</exposing-rules>

Describes the rules for exposing children components (similar to getXXX() methods). You can include or exclude a set of methods. Note, that rules are executed in reverse order, so if you later have some rules that includes (enables) using some method, it will be used for exposing, even if previous rules exclude it.

  • «package» accepts any method of classes exactly in the same package, without sub-packages;
  • «method» accepts method with exactly the same name, without parameters in any package. Of course, all these filters will work only for components that correspond to this description or its subclasses.

Clone this wiki locally