Grid Contraint Layout

3D PLM Enterprise Architecture	JDialog	Grid Contraint Layout Define a complex layout using Grid Constraint
Use Case

Abstract

This article shows how to define a complex layout using Grid Constraint.

What you will learn with this use case
The CAAGCUseCase use case
Grid Constraint Layout introduction
Used widgets
Layout definition on paper
Detailed GC layout frame by frame
XMLDlg, Controller and CATNls files
In Short
References

What you will learn with this use case

This use case is intended to show you how to use Grid Constraint layout to define a complex layout.

[Top]

The CAAGCUseCase use case

CAAGCUseCase is a use case of the CAAJDialog.edu framework that illustrates CATJDialog framework capabilities.

[Top]

Use case overview

Here is a snapshot of the User Interface we want to build:

[Top]

How to launch CAAGCUseCase

To launch CAAGCUseCase, you will need to set up the build time environment, then compile CAAJdgXMLModels.mj along with its prerequisites, set up the run time environment, and then execute the use case [1].

This use case is made of a unique JDialog command: "CAAGCUseCase"

[Top]

Where to find the CAAGCUseCase code

The CAAGCUseCase use case is made of a single command, without any java controller (that means the command has no behavior). It uses the following resource files:

CAAGCUseCase.XMLDlg in CNext/resources/dialog
CAAGCUseCase.CATNls in CNext/resources/msgcatalog
[Top]

Grid Constraint Layout introduction

The JDialog CATFrame is the only widget that allows positioning its children widgets. It offers this capability through a Grid Constraint Layout implementation.

The Grid Constraint Layout is a flexible layout definition that aligns widgets vertically and horizontally, without requiring that the widgets be of the same size. It allows defining rectangular grid of cells, with each widget occupying one or more cells, called its display area.

Each CATFrame children widget is associated with a set of GC attributes that specify how it is laid out within its display area:

X, Y: specifies the cell at the upper left of the widget's display area.
Width, Height: specifies the number of cells in a row (for Width) or column (for Height) in the widget's display area. The default value is 1.
Alignment: Used when the widget is smaller than its display area to determine where (within the display area) to place the widget.
- horizontally: left, center (default) or right
- vertically: top, middle (default) or bottom
Justification: Used when the widget is smaller than its display area to determine whether (and how) to resize the widget. Possible values are:
- none (default)
- horizontal
- vertical
- both

Note: obviously when a widget is horizontally justified, it's horizontal alignment has no real meaning (since it will spread horizontally through its entire display area).

Another information is required by the Grid Constraint Layout to distribute free space among cells. This is done by defining a weight on rows and columns: free space (if any) is then divided proportionally to columns and rows weight. Default rows and columns weight is 0.

Notes:

weight is used to divide remaining space between columns and rows (proportionally to their weights) and only for that
if all columns (or rows) have a null weight, then they are all considered to have a weight=1 (by the layout algorithm)
when a column (or row) has a null weight, then its width (height) is given by the widest (higher) widget in this column (line)
adding an empty column (or row) with a null weight won't add any blank space in your layout: it won't be visible!

[Top]

Used widgets

Here is the detail of used widgets:

[Top]

Layout definition on paper

Here is a drawing of how widgets are arranged on the panel:

[Top]

Widgets hierarchy

The above drawing gives the following widgets hierarchy:

Frame
  |
  +--Link
  |
  +--Link
  |
  +--Toolbar
  |
  +--Frame
  |   |
  |   +--WebPartFrame
  |   |   |
  |   |   +--Tree
  |   | 
  |   +--WebPartFrame
  |       |
  |       +--Frame
  |           |
  |           +--Label
  |           |
  |           +--TextField
  |           |
  |           +--Label
  |           |
  |           +--DateEditor
  |           |
  |           +--Label
  |           |
  |           +--ComboBox
  |           |
  |           +--Label
  |           |
  |           +--CheckBox
  |
  +--Frame
      |
      +--Button
      |
      +--Button
      |
      +--Button

[Top]

Detailed GC layout frame by frame

We will now have a look into detail at the Grid Constraint layout definition for each frame of the user interface.

[Top]

Detailed GC layout for the top frame

Here is a drawing of the detailed Grid Constraint definition for the top frame:

Explanations:

"help" and "home" links are top-left aligned and do not move when resizing the window.
The toolbar is top-right aligned
In order to place the 3 buttons at the center of the panel, we have to put them in a frame that is center aligned
We want the middle frame to occupy "the rest of the space". So it is horizontally and vertically justified, and its row is affected with all remaining space (non-null weight while other rows has a null weight).

Remarks:

all column weight could also have been given to column 1 without any change.
the buttons frame could be horizontally justified (its inner layout definition would then be different but it can work too).
most of the time, non-null weight values is not important. As long as only one row/column has a non-null value, it will be given all remaining space. Values are taken into account when several rows/columns have a non-null value: remaining space is divided proportionally to the weights.

[Top]

Detailed GC layout for the buttons frame

Here is a drawing of the detailed Grid Constraint definition for the frame containing the buttons:

Explanations:

As the buttons frame is nor horizontally and neither vertically justified in the top frame layout definition, the buttons alignments here may be anything: their display area will anyway fit to their size.

[Top]

Detailed GC layout for the middle frame

Here is a drawing of the detailed Grid Constraint definition for the frame containing the 2 WebPartFrames:

Explanations:

Even if row 0 has here a null weight, it will occupy all available vertical space due to the rule "if all columns (or rows) have a null weight, then they are all considered to have a weight=1 (by the layout algorithm)"
We don't want the tree to expand horizontally when resizing, so all column weight is given to column 1
We want the tree and the form to spread over their whole display area, so they are both horizontally and vertically justified
As a result of the 2 above points, the form will expand horizontally when resizing.

[Top]

Detailed GC layout for the form frame

Here is a drawing of the detailed Grid Constraint definition for the frame containing the textfield, date editor, combo box and checkbox:

Explanations:

labels are all right-top aligned
editors (textfield, date editor, combo and checkbox) are all left-top aligned
has we defined the User Interface, the widgets here may not move relatively to the top-left corner when resizing. The way of defining this is defining a non-null weight on last row (3) and last column (1).

[Top]

XMLDlg, Controller and CATNls files

Here is the XMLDlg file that defines the User Interface with required layout (CAAJDialog.edu/CNext/resources/dialog/CAAGCUseCase.XMLDlg):

<?xml version="1.0"?>
  <Frame Name="LayoutSampleCtrl">
    <Link Name="HelpLink"/>
    <GC A="LT" W="1" Name="HelpLink" H="1" Y="0" X="0"/>
    <Link Name="HomeLink"/>
    <GC A="LT" W="1" Name="HomeLink" H="1" Y="0" X="1"/>
    <Toolbar Name="Toolbar" ModelURL="com.dassault_systemes.caajdialog.caajdgxmlmodels.CATXMLMenuModel@sample/JDialog/SampleToolbarMenu.xml"/>
    <GC A="RT" W="1" Name="Toolbar" H="1" Y="0" X="2"/>

    <Frame Name="MiddleFrame">
      <WebPartFrame Name="TreeWPFrame">
        <Tree Name="Tree" ModelURL="com.dassault_systemes.caajdialog.caajdgxmlmodels.CATXMLTreeModel@sample/JDialog/FoodTree.xml"/>
      </WebPartFrame>
      <GC A="CM" W="1" Name="TreeWPFrame" J="HV" H="1" Y="0" X="0"/>

      <WebPartFrame Name="FormWPFrame">
        <Frame Name="FormFrame">
          <Label Name="TextfieldLbl"/>
          <GC A="RT" W="1" Name="TextfieldLbl" H="1" Y="0" X="0"/>
          <Label Name="DateEditorLbl"/>
          <GC A="RT" W="1" Name="DateEditorLbl" H="1" Y="1" X="0"/>
          <Label Name="ComboLbl"/>
          <GC A="RT" W="1" Name="ComboLbl" H="1" Y="2" X="0"/>
          <Label Name="CheckLbl"/>
          <GC A="RT" W="1" Name="CheckLbl" H="1" Y="3" X="0"/>
          <TextField Name="TextField" ExpectedFormat="."/>
          <GC A="LT" W="1" Name="TextField" H="1" Y="0" X="1"/>
          <DateEditor Name="DateEditor"/>
          <GC A="LT" W="1" Name="DateEditor" H="1" Y="1" X="1"/>
          <ComboBox Name="ComboBox">
	        <Item Title="item1"/>
	        <Item Title="item2"/>
	        <Item Title="item3"/>
	        <Item Title="item4"/>
	        <Item Title="item5"/>
	        <Item Title="item6"/>
	      </ComboBox>
          
          <GC A="LT" W="1" Name="ComboBox" H="1" Y="2" X="1"/>
          <CheckBox Name="CheckBox"/>
          <GC A="LT" W="1" Name="CheckBox" H="1" Y="3" X="1"/>
          <Column W="1" X="1"/>
          <Row W="1" Y="3"/>
        </Frame>
      </WebPartFrame>
      <GC A="CM" W="1" Name="FormWPFrame" J="HV" H="1" Y="0" X="1"/>
      <Column W="1" X="1"/>
    </Frame>
    <GC A="LT" W="3" Name="MiddleFrame" J="HV" H="1" Y="1" X="0"/>

    <Frame Name="ButtonsFrame">
      <Button Name="OkButton"/>
      <GC A="LT" W="1" Name="OkButton" H="1" Y="0" X="0"/>
      <Button Name="ApplyButton"/>
      <GC A="LT" W="1" Name="ApplyButton" H="1" Y="0" X="1"/>
      <Button Name="CancelButton"/>
      <GC A="LT" W="1" Name="CancelButton" H="1" Y="0" X="2"/>
      <Column W="1" X="0"/>
      <Column W="1" X="2"/>
    </Frame>
    <GC A="CT" W="3" Name="ButtonsFrame" H="1" Y="2" X="0"/>

    <Column W="1" X="2"/>
    <Row W="1" Y="1"/>
  </Frame>

Remarks:

Notice that this JDialog command has no controller. Obviously this is not realistic as an application should do something, but it is not our goal in this use case.
The Tree model is directly set from the XMLDlg file (with ModelURL attribute). This model feeds the tree with the content of an xml file (CAAJDialog.edu/CNext/sample/JDialog/FoodTree.xml).
The Toolbar model is directly set from the XMLDlg file (with ModelURL attribute). This model feeds the toolbar with the content of an xml file (CAAJDialog.edu/CNext/sample/JDialog/SampleToolbarMenu.xml).

Here is the associated message catalog file in English (CAAJDialog.edu/CNext/resources/msgcatalog/CAAGCUseCase.CATNls):

// --- links titles
HelpLink.Title = "Help";
HomeLink.Title = "Home";

// --- web frame part titles
MiddleFrame.TreeWPFrame.Title = "Tree";
MiddleFrame.FormWPFrame.Title = "Form";

// --- form label titles
MiddleFrame.FormWPFrame.FormFrame.TextfieldLbl.Title = "Comment: ";
MiddleFrame.FormWPFrame.FormFrame.DateEditorLbl.Title = "Date: ";
MiddleFrame.FormWPFrame.FormFrame.ComboLbl.Title = "Status: ";
MiddleFrame.FormWPFrame.FormFrame.CheckLbl.Title = "Activity: ";
MiddleFrame.FormWPFrame.FormFrame.CheckBox.Title = "";

// --- buttons titles
ButtonsFrame.OkButton.Title = "Ok";
ButtonsFrame.ApplyButton.Title = "Apply";
ButtonsFrame.CancelButton.Title = "Cancel";

[Top]

In Short

Grid Constraint Layout is very powerful but far from being easy. A good advice is: start defining your applications layout on paper.
Grid Constraint Layout gives several ways of defining the same layout.
The layout definition involves 2 questions:
- where are the widgets? It is defining the "static" layout: X, Y, Width, Height and Alignment
- which widget occupies remaining space? Define the resize behavior: Justification, columns and rows weights

[Top]

References

[1]	Building and Launching a CAA V5 JDialog Use Case
[Top]

History

Version: 1 [Jan 2002]	Document created
[Top]

3D PLM Enterprise Architecture

JDialog