Rich UI widgets

Rich UI handler parts include widgets, which are customized, on-screen controls. 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.

Table 1. Widget types
Category Type Purpose
Container Box To define a box, which in most cases embeds other widgets.

You can indicate how many columns are in the box. For example, if the number of columns is three, 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 of the embedded widgets are arranged vertically. 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 center, right, or left of the column.

To show empty cells, include text labels that lack text as children of the box.

If necessary, vertical and horizontal scroll bars are displayed 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.
Grouping To display a widget collection in a bordered box. You assign text that is embedded in the top of the border.
Information Grid To define an array of values in a table format. You can use the widget to set 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. You can use the referenced functions to update header-row, body-row, or cell characteristics in response to the user's click of a cell.
HTML To present an HTML fragment, which might 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. This 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 that contains one or more lines of bidirectional text
BidiTextField To define a text box that contains one 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. The user can use this widget to temporarily open a 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 one 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 by invoking a function.
TextArea To define a rectangle that contains one or more lines of text
TextField To define a text box that contains one line of text
Hover GridTooltip To define a special hover help; that is, one or more widgets that are displayed when the user hovers the cursor over a grid widget.
Tooltip To define a hover help: one or more widgets for display when the user hovers the cursor over a widget.
TreeTooltip To define a special hover help: one or more widgets for display when the user hovers the cursor 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 with the RUIHandler stereotype). In this case, the handler code provides a capability that is 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 about the generally available fields and functions, see "Setting widget properties and functions."

For details on the Dojo widgets, see “Developing with the EGL Dojo widgets.”

Widget declarations and package names

When you 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:
widgetName com.ibm.egl.rui.widgets.widgetTypeName;
widgetName
Name of the widget
widgetTypeName
Name of the widget type

The EGL 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 editor."

The second way to identify the package is to include an import statement early in the source code. This format requires that you use either a wild card (*), to reference multiple types, or the name of a specific type in place of widgetTypeName:
import com.ibm.egl.rui.widgets.widgetTypeName;

If you use a wild card in place of widgetTypeName, unnecessary code is added to the generated JavaScript™ output.

When you write source code, you can insert an import statement automatically after you declare a widget:
  1. Hold down Ctrl and Shift and press O
  2. If a window is displayed, choose among same-named widget types; for example, a Button can be from Dojo, Silverlight, or EGL Rich UI

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 with the RUIWidget stereotype.
  • 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 about creating widgets, see "Extending the Rich UI widget set."

Using the Widget type

You can use the EGL Widget type when you define a function that accepts a widget whose specific type is not known at development time. The following example shows how such a function can use the EGL operators isa and as to make type-specific properties and functions available; 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 the Widget type is compatible with both Rich UI widgets and external-type widgets.


Feedback