@VEWidget

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):
  1. 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.
  2. ruiLib.EXCLUDE_ALL_EXCEPT excludes all the events defined for RUIWidget and Widget except those specified in the value of eventFilter.
  3. ruiLib.INCLUDE_ALL includes all the events defined for RUIWidget and Widget. In this case, values for eventFilter are ignored.
  4. 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):
  1. 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.
  2. ruiLib.EXCLUDE_ALL_EXCEPT excludes all the properties defined for RUIWidget and Widget except those specified in the value of propertyFilter.
  3. ruiLib.INCLUDE_ALL includes all the events defined for RUIWidget and Widget. In this case, values for propertyFilter are ignored.
  4. 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"]
    }

Feedback