Rich UI widgets

Rich UI handler parts include widgets. Each is a customized, on-screen control, but the term widget also refers to the variable declaration that creates the control. A widget can contain business data and can respond to events.

Widget types

The product provides a core set of widget types, which you use to declare widgets. The following table lists the main types but does not include the available Dojo widgets, which are listed in another topic.

Table 1. Widget types
Category	Type	Purpose
Container	Box	To define a box, which in most cases embeds other widgets. A box was the primary kind of container in early versions of Rich UI. However, a container of type GridLayout is more flexible, as described in the topic for GridLayout. You can indicate how many columns are in a box. If the number of columns is three, for example, the first three embedded widgets are on the first row in the box, the fourth through sixth are on the second row, and so forth. If the number of columns is one, all the embedded widgets are arranged vertically. In any case, the width of a column equals the width of the largest widget in the column, and you can indicate whether the embedded widgets in a given column are aligned at the column's center, right, or left. If you want to show empty cells, include, as children of the box, text labels that lack text. Vertical and horizontal scroll bars appear if necessary to give the user access to widgets that are out of sight.
	Div	To define a division (HTML DIV tag) on the web page, below the preceding content. The Div widget might be the parent of FloatLeft and FloatRight widgets, providing flexibility in web-page design.
	FloatLeft	To define a division (HTML DIV tag) on the web page; in most cases, as a child of a Div, FloatLeft, or FloatRight widget. The widget uses the CSS element float:left.
	FloatRight	To define a division (HTML DIV tag) on the web page; for example, as a child of a Div, FloatLeft, or FloatRight widget. The widget uses the CSS element float:right.
	GridLayout	To define a container with variably spaced rows and columns that embed child widgets. Each child widget has a layoutData property, and you specify the location of the widget by assigning a value to that property.
	Grouping	To display a widget collection in a bordered box. You assign text that is embedded in the top of the border.
Information	DataGrid	To define an array of values in a table format. The widget lets you specify the following details: Column characteristics such as width, height, and color An array of records whose field values are displayed in the corresponding grid columns, one row per record Behaviors, which are fields that each accept an array of function references. The referenced functions let you update header-row, body-row, or cell characteristics in response to the user's clicking a cell.
	Grid	To define an array of values in a table format. For new development, use the DataGrid widget type, which is superior in performance and capabilities.
	HTML	To present an HTML fragment, which may be provided by a service. The HTML is rendered in a bounded area, with scroll bars if necessary.
	Image	To display a graphic or alternate text.
	Shadow	To create a shadow effect for the widgets that are children of a specified DIV widget.
	Span	To display a string that the user cannot change. The string can include HTML segments (such as <b>this boldfaced code</b>).
	TextLabel	To display a string that the user cannot change. The widget is different from a span because inclusion of an HTML segment (such as <b>this code</b>) is displayed as is, including the angle brackets.
	Tree	To define a tree of displayable nodes.
Interactive	BidiTextArea	To define a rectangle containing one or more lines of bidirectional text.
	BidiTextField	To define a text box containing a single line of bidirectional text.
	Button	To define a button, which elicits a user click and responds to that click by invoking a function.
	Checkbox	To define a check box, which displays a true-false option and responds to the user input by invoking a function.
	Combo	To define a combo box, which presents one of several selectable options and lets the user temporarily open a dropdown list to select a different option.
	Hyperlink	To define a web-page link that, if clicked, displays the page in the browser. The page display is not bounded by a layout.
	List	To define a list from which the user can select a single entry.
	Listmulti	To define a list from which the user can select multiple entries.
	Menu	To define a menu bar entry.
	PasswordTextField	To define an input text field whose value is displayed as bullets, as appropriate for accepting a password.
	RadioGroup	To define a set of radio buttons, each of which responds to a click by deselecting the other radio buttons in the same group and (in the typical case) by invoking a function.
	TextArea	To define a rectangle containing one or more lines of text.
	TextField	To define a text box containing a single line of text.
Hover	GridTooltip	To define a special hover help; that is, one or more widgets that are displayed when the user hovers over a grid widget.
	Tooltip	To define a hover help: one or more widgets for display when the user hovers over a widget.
	TreeTooltip	To define a special hover help: one or more widgets for display when the user hovers over a tree widget.

Although the hover types (ToolTip, GridToolTip, and TreeToolTip) are in our list of widgets, each tooltip type is technically a Rich UI handler (EGL handler part, stereotype RUIHandler). In this case, the handler code provides a capability similar to that of a Rich UI widget. However, the functions and fields that are available for all widgets are not available for tooltips. For details on the generally available fields and functions, see Setting widget properties and functions.

Widget declarations and package names

When you wish to declare a widget, EGL provides two ways to identify the package in which the widget resides. Although those two ways are available when you declare any EGL variable, special automation is available in relation to widgets.

First, you can precede the name of the widget type with the name of the package. Here is the format:

widgetName com.ibm.egl.rui.widgets.widgetTypeName;

widgetName: Name of the widget
widgetTypeName: Name of the widget type

The EGL Rich UI editor uses the preceding format for the widget-declaration statement after you drag a widget from the palette to the Design surface. For an overview, see Introduction to the EGL Rich UI editor.

The second way to identify the package is to include an import statement early in the source code. Here is the format, which requires, in place of widgetTypeName, either a wild card (*) to reference multiple types or the name of a specific type:

import com.ibm.egl.rui.widgets.widgetTypeName;

Use of a wild card in place of widgetTypeName adds unnecessary code to the generated JavaScript output and is not recommended.

When you write source code, you can insert an import statement automatically after you declare a widget:

Hold down Ctrl and Shift and press O
If a dialog is displayed, choose among same-named widget types; for example, a Button can be from Dojo, Silverlight, or EGL Rich UI

Avoiding a null pointer exception

A widget is an EGL reference variable. When declaring a widget statically (without the new operator), remember to specify a set-values block ({}), as in the following example:

myButton Button{};

Creating additional widgets

You can create your own widgets in either of two ways:

You can code a Rich UI widget; that is, a Rich UI handler, stereotype RUIWidget.
You can write an EGL external type that is based on JavaScript. The ability to use EGL external types is useful for accessing preexisting JavaScript libraries.

For details on creating widgets, see Extending the Rich UI widget set.

Using the Widget type

The EGL Widget type is used when defining a function that accepts a widget whose specific type is not known at development time. The following (unrealistic) example shows how such a function can use the EGL operators isa and as to make available type-specific properties and functions; for example, the text property of the TextField type:

import com.ibm.egl.rui.widgets.TextField;

handler MyHandlerPart type RUIhandler{onConstructionFunction = initialization}

   myHelloField TextField{readOnly = true, text = "Hello"};

   function initialization()
      	myInternalFunction(myHelloField);
   end

   function myInternalFunction(theWidget widget in)
     
      case 
         when (theWidget isa TextField)
            myTextField TextField = theWidget as TextField;
            myString STRING = myTextField.text + " World";
            sysLib.writeStdOut(myString);
         when (theWidget isa Button)
            ;
       	 otherwise
       	    ;
      end
   end
end

The handler displays Hello world.

A variable of type Widget must be declared before the widget is referenced in a property; in particular, before the widget is referenced in an initialUI or children property. (That rule does not apply to variables of specific widget types such as Button or TextField.)

A variable of type Widget is compatible with both Rich UI widgets and external-type widgets.