When you write a Rich UI or external-type widget, you can
specify the complex property @VEWidget. The EGL editor uses
the details of any @VEWidget property in the workspace, adding entries
to the palette when you refresh the palette. You refresh the palette
by clicking the Refresh palette tool on the Design surface, as noted
in “Using the tools on the Design surface.”
The
@VEWidget property has the following fields:
- category (type STRING)
- In the palette, the category in which the widget is listed. The
categories are listed in alphabetical order.
If the category does
not exist, a new category will be created with the name you specify.
The category is particularly useful to distinguish same-named widgets
such as Rich UI buttons and Dojo buttons.
- description (type STRING)
- In the palette, the description that is displayed when the user
hovers over the widget entry.
- displayName (type STRING).
- In the palette, the widget name. The names are listed in alphabetical
order within a category.
The default value is the name of either
the external type or the handler of type RUIWidget.
- template (type STRING)
- The part of the widget type declaration that follows the widget
name, excluding the semicolon. In our example, the declaration includes
a set-values block, as is necessary to avoid an error. Here is an
example declaration:
myH3 my.package.H3{ text="The Heading Text" };
If
you want the EGL system code to specify the widget type and to include
a qualifier (such as
my.package) only if necessary,
start the template string with the
typeName variable.
Here is an example:
template = "${typeName}{}"
Here is a related declaration, assuming that the
widget type shown earlier is in the same package as the handler that
receives the declaration:
myH3 H3{};
Here is another example:
template = "${typeName}{ text=\"The Heading Text\" }"
Here is the related declaration:
myH3 H3{ text="The Heading Text" };
- smallIcon (type STRING)
- The path for the gif file that contains the small icon that is
displayable on the palette. The path is relative to the project directory.
For example, if the project is com.egl, the gif files listed earlier
are in com.egl/icons.
- largeIcon (type STRING)
- The path for the gif file that contains the large icon that is
displayable on the palette. The path is relative to the project directory.
For example, if the project is com.egl, the gif files listed earlier
are in com.egl/icons.
- container (type @VEContainer)
- Specify the container field as follows:
container{@VEContainer{}}
The
presence of
container has the following
implications:
- At run time, the widget can include other widgets.
- At development time, the EGL developer can drag-and-drop other
widgets into the widget being defined.
- The widget must include a field named children.
The field named children must be of type
Widget[] and you must define the property @EGLProperty for
that field, as described later.
In addition,
@VEWidget lets you specify
which RUIWidget properties and events (as well as external-type properties
and events) are to be displayed in the
Properties view.
For example, a displayed entry for
backgroundColor is
provided for any handler of type RUIWidget (or even for a widget provided
by an external type); but
backgroundColor may
not be appropriate for the widget you are defining. Here are the
@VEWidget property
fields that filter the properties and events that are otherwise displayed
by default:
- eventFilter (STRING[])
- An array of event names (such as ["onClick", "OnScroll"])
to include or exclude from display, depending on the value of eventFilterType.
- eventFilterType (type INT)
- One of the following values (either the integer or the related
constant):
- ruiLib.EXCLUDE_ALL excludes all the events defined for RUIWidget
(type egl.ui.rui.RUIWidget) and, in the case of external types, for
Widget (type egl.ui.rui.Widget). In this case, any values for eventFilter are
ignored.
- ruiLib.EXCLUDE_ALL_EXCEPT excludes all the events defined for
RUIWidget and Widget except those specified in the value of eventFilter.
- ruiLib.INCLUDE_ALL includes all the events defined for RUIWidget
and Widget. In this case, values for eventFilter are
ignored.
- ruiLib.INCLUDE_ALL_EXCEPT includes all the events defined for
RUIWidget and Widget except those specified in the value of eventFilter.
- propertyFilter (STRING[])
- An array of property names (such as ["font", "fontSize"])
to include or exclude from display, depending on the value of propertyFilterType.
- propertyFilterType (type INT)
- One of the following values (either the integer or the related
constant):
- ruiLib.EXCLUDE_ALL excludes all the properties defined for RUIWidget
(type egl.ui.rui.RUIWidget) and, in the case of external types, for
Widget (type egl.ui.rui.Widget). In this case, any values for propertyFilter are
ignored.
- ruiLib.EXCLUDE_ALL_EXCEPT excludes all the properties defined
for RUIWidget and Widget except those specified in the value of propertyFilter.
- ruiLib.INCLUDE_ALL includes all the events defined for RUIWidget
and Widget. In this case, values for propertyFilter are
ignored.
- ruiLib.INCLUDE_ALL_EXCEPT includes all the events defined for
RUIWidget and Widget except those specified in the value of propertyFilter.
Here is an example of an external type for which the only displayed
event types are
onScroll and
onChange and
for which the only displayed properties are
color and
backgroundColor:
ExternalType DojoButton extends DojoBase type JavaScriptObject {
relativePath = "dojo/widgets",
javaScriptName = "DojoButton",
includeFile = "dojo/widgets/dojobutton.html",
@VEWidget{
category = "Dojo",
template = "dojo.widgets.DojoButton { text = \"Button\" }",
displayName = "Button",
smallIcon = "icons/ctool16/dijit_button_pal16.gif",
largeIcon = "",
propertyFilterType = ruiLib.EXCLUDE_ALL_EXCEPT,
propertyFilter = ["color", "backgroundColor"],
eventFilterType = ruiLib.EXCLUDE_ALL_EXCEPT,
eventFilterType = ["onScroll", "onChange"]
}