GridLayout widget and related types

A Rich UI grid layout is a container with variably spaced rows and columns.

Each widget embedded in the grid layout has a layoutData field, and you specify the location of the widget by assigning a value to that field. Your layoutData settings also can align the widget horizontally and vertically within the position and can cause the widget to span multiple rows and columns.

The grid layout supports the following fields:

Other supported fields are described in “Rich UI widget fields,” in the EGL Programmer’s Guide.

A child widget can affect the layout as a whole:
The Rich UI editor gives you a lot of help in working with a grid layout. In particular, you can do the following tasks:
For details on the editor capabilities just mentioned, see the following topics:
Use of the grid layout typically requires all of the following statements:
import org.eclipse.edt.rui.widgets.GridLayout;
import org.eclipse.edt.rui.widgets.GridLayoutData;
import org.eclipse.edt.rui.widgets.GridLayoutLib;

Example

Consider the following user interface:



Rich UI GridLayout example

Here is an outline of the Rich UI handler that forms the interface:
handler SingleGridlayout type RUIhandler {initialUI = [ myGridLayout ]... }

   myGridLayout GridLayout{ 
      rows = 4, columns = 4, cellPadding = 4,
      children = [ Button3, Button1, Button2 ]
   };
   ...
end

The myGridLayout layout includes four rows, four columns, and a four-pixel padding around each cell. Three children are specified, and the order in which they are listed in the children array is not important. However, if multiple widgets have layoutData values that cause the widgets to occupy the same location, the first-listed of those widgets is displayed.

For each widget, the value of the layoutData field is of type ANY. At this time, the field always takes a record of type GridLayoutData, which is described later.

The myLayoutData record is assigned to the layoutData field of the Button1 button. Here is the record declaration:
myLayoutData GridLayoutData{ row = 1, column = 2 };

The record declarations needed for the layoutData fields of Button2 and Button3 are in the widget declarations themselves. Here are the declarations of all three buttons:

Button1 Button{ layoutData = myLayoutData, text = "Button1", onClick ::= respond };
Button2 Button{ layoutData = new GridLayoutData{ row = 2, column = 3 },
                text = "Button2" };
Button3 Button{ layoutData = new GridLayoutData{ row = 3, column = 4 },
                text = "Button3" };

If a record of type GridLayoutData is assigned to the layoutData field of a widget that is embedded in a grid layout, the row and column fields of the record must be set, and their values must be appropriate for the layout. However, you can assign a null to the layoutData field, in which case the embedded widget is not displayed and is not included in the width and height calculations that customize the layout as a whole.

Runtime updates to the layouts

You can update the layout dynamically. For example, you might want the user's click of Button1 to cause the following display:



Rich UI GridLayout example 2

Here is the function that causes that display when the user clicks Button1:
function respond(e Event in)
   Button2.layoutData = null;
end	

After the respond function runs, the height of the second row and the width of the second column include only the padding specified in the grid layout definition. The third button (Button3) moves up and to the left, but its position relative to Button1 does not change.

Alternatively, you might want the user's click of Button1 to cause the following display:



Rich UI GridLayout example 3

Here is a revised respond function:
function respond(e Event in)
   myLabel TextLabel {text="replace button 2"};
   myLabel.layoutData = new GridLayoutData {row=2, column=3};
   Button2.layoutData = null;
   myGridLayout.appendChild(myLabel);
end	

In this case, the nulling of the layoutData field of Button2 is necessary to replace the current content at row 2, column 3. The new content is wider and shorter than Button2, and the third button moves up and to the right.

In general, always null the layoutData field for a widget that you are excluding from the grid layout. When you are replacing a child widget that spans columns or rows, the nulling of that widget can avoid a runtime error.

Example with spanning and alignment

Consider the following user interface:



Rich UI GridLayout example 4, preview

As shown in the Design tab of the Rich UI editor, the grid layout has four rows and three columns:



Rich UI GridLayout example 4, design

Consider the following aspects of the interface:
  • In row 1, the label is in the first column, and the text field extends horizontally from the second to the third column.
  • In row 2, the checkbox is in the second column, but extends vertically to the third row.
  • In row 3, the button extends horizontally from the first to the second column and is centered in those two columns.
Here is the Rich UI handler that forms the interface:
handler SingleGridlayout type RUIhandler {initialUI = [ myGridLayout ]... }

  myGridLayout GridLayout{ 
      rows = 4, columns = 3, cellPadding = 4,
      children = [ myLabel, myTextField, myCheckBox, myButton ]
   };

  myLabel TextLabel{ layoutData = new GridLayoutData{ row = 1, column=1},
                     text = "Label: " };

  myTextField TextField{ layoutData = new GridLayoutData{ row = 1, column = 2,
                         horizontalSpan = 2 }, text = "Text field"};
	
  myCheckBox CheckBox{ layoutData = new GridLayoutData{ row = 2, column = 2, 
                       verticalSpan = 2 }, text="Check box" };

  myButton Button{ layoutData = new GridLayoutData{ row = 4, column = 1,
                       horizontalSpan = 2, 
                       horizontalAlignment = GridLayoutLib.Align_Center }, 
                       text="Button" };
end

The next section gives details on the GridLayoutData fields.

GridLayoutData

The GridLayoutData fields are as follows:
row
An integer that represents the topmost layout row where the widget resides.
column
An integer that represents the leftmost layout column where the widget resides.
cellPadding
An integer that represents the number of pixels that are in the top, bottom, left, and right border of the area that the widget reserves for itself.
horizontalspan
The number of columns that the widget takes, including the column specified in the column field.
verticalspan
The number of rows that the widget takes, including the row specified in the row field.
horizontalAlignment
The widget's horizontal position within the columns that the widget reserves for itself. One of the following values:
GridLayoutLib.ALIGN_LEFT
At the left of the columns.
GridLayoutLib.ALIGN_CENTER
At the center of the columns.
GridLayoutLib.ALIGN_RIGHT
At the right of the columns.
verticalAlignment
The widget's vertical position within the rows that the widget reserves for itself. One of the following values:
GridLayoutLib.VALIGN_TOP
At the top of the rows.
GridLayoutLib.VALIGN_MIDDLE
At the middle of the rows.
GridLayoutLib.VALIGN_BOTTOM
At the bottom of the rows.