Creating a Command

3D PLM Enterprise Architecture	JDialog	Creating a Command How to make a command with JDialog
Use Case

Abstract

This article shows how to create a command with JDialog, through the CAAJdgSmartDictionary use case.

What You Will Learn With This Use Case
The CAAJdgSmartDictionary Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to create a JDialog command. It presents two ways of programming a command:

full-dynamic (similar to Java/AWT programming),
using static declarative files (the JDialog way).

[Top]

The CAAJdgSmartDictionary Use Case

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

[Top]

What Does CAAJdgSmartDictionary Do

CAAJdgSmartDictionary is a dictionary command, able to translate anything from any language to any language. It is composed of:

a combo-box to choose the source language,
a combo-box for the destination language,
a text field for the text to translate,
a button for asking for the translation,
and a label for displaying the result of the translation.

It looks like this:

[Top]

How to Launch CAAJdgSmartDictionary

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

Actually, this use case contains two JDialog commands:

"SmartDictionary1", which illustrates the "full-dynamic" way of programming a JDialog command,
"SmartDictionary2", which illustrates the JDialog way of programming, using static declarative files.

Although those commands are programmed in a different way, the result (runtime behavior) is strictly identical.

[Top]

Where to Find the CAAJdgSmartDictionary Code

The CAAJdgSmartDictionary use case is made of two classes located in the CAAJdgSmartDictionary.mj module of the CAAJDialog.edu framework:

Windows	`InstallRootDirectory\CAAJDialog.edu\CAAJdgSmartDictionary.mj\`
Unix	`InstallRootDirectory/CAAJDialog.edu/CAAJdgSmartDictionary.mj/`

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

The CAAJdgSmartDictionary.mj module includes two java files:

CATSmartDictionaryController1.java	The controller of the "full-dynamic" version
CATSmartDictionaryController2.java	The controller of the "static declarative files" version

SmartDictionary1 uses the following resource file:

SmartDictionary1.XMLDlg in CNext/resources/dialog

SmartDictionary2 uses the following resource files:

SmartDictionary2.XMLDlg in CNext/resources/dialog,
SmartDictionary2.CATNls in CNext/resources/msgcatalog

[Top]

Step-by-Step

Defining the command layout "on paper"
Declaring the SmartDictionary1 command
Writing the SmartDictionary1 command controller
Declaring the SmartDictionary2 command
Creating the message catalog file for SmartDictionary2
Writing the SmartDictionary2 command controller

[Top]

Defining the command layout "on paper"

The preliminary step in writing a command should always be to define its layout on paper. Layout is not a trivial thing, and spending a few minutes in drawing your application on paper and thinking about its resize behavior may save you a lot of time in debugging a badly constrained layout.

Remark:

Until now, the only layout manager provided by JDialog is a "Grid Layout" implementation.

Every graphical component is associated to a GC object, defining its layout in its father container. The GC object gives the following controls:

x, y: the position of the component on the grid,
w, h: the width and eight (in cells) occupied by the component,
alignment: defines the component alignment inside its cells (combination of left/right/center and top/bottom/center),
justification: defines the spreading of the component in its cells (none/horizontal/vertical/both).

Grid layout is very powerful and should allow you to create almost any layout. So if you don't manage to reproduce the desired layout, it means a constraint must be missing somewhere. In order to have a good understanding of Grid Layout, you should be aware of a few things:

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

According to the SmartDictionary screen shot (see above), we want the following layout:

[Top]

Declaring the SmartDictionary1 command

Obviously, JDialog gives the possibility to build applications dynamically. The only thing to do is to declare the command in the JDialog environment. This is done by adding an XML file (with extension XMLDlg) in the runtime view.

Here is the resource file "SmartDictionary1.XMLDlg", declaring the "SmartDictionary1" command:

<?xml version="1.0"?>
  <Frame Attribute="_frame" onCreate="onCreate" Controller="com.dassault_systemes.catjdialog.smartdictionary.
CATSmartDictionaryController1">
  </Frame>

The first role of this file is to declare "SmartDictionary1" as a JDialog command (a file "MyCommand.XMLDlg" would declare a "MyCommand" command).

Its content defines that the "SmartDictionnary1" command is a Frame whose controller class is "com.dassault_systemes.catjdialog.smartdictionary.CATSmartDictionaryController1" which has a public attribute named "_frame" (of type CATFrame), and a method "onCreate" (with a given signature).

When the command "SmartDictionary1" is activated, then the JDialog infrastructure does the following:

instantiates a Frame object (CATFrame),
instantiates a controller object (CATSmartDictionaryController1),
initializes its "_frame" attribute with the Frame object,
callbacks the controller object on its "onCreate" method to warn it that the Frame was just created.

To know more about callbacks, please have a look at CATCallbackSource.

[Top]

Writing the SmartDictionary1 command controller

package com.dassault_systemes.catjdialog.smartdictionary;

import com.dassault_systemes.catjdialog.CATFrame;
import com.dassault_systemes.catjdialog.CATButton;
import com.dassault_systemes.catjdialog.CATComboBox;
import com.dassault_systemes.catjdialog.CATLabel;
import com.dassault_systemes.catjdialog.CATDialog;
import com.dassault_systemes.catjdialog.CATNotification;
import com.dassault_systemes.catjdialog.CATTextField;
import com.dassault_systemes.catjdialog.GC;

/**
 * JDialog controller for the 'SmartDictionary' command.
 **/
public class CATSmartDictionaryController1
{
  // --- this attribute contains the command's CATFrame
  public CATFrame _frame;
  
  // --- private attributes
  private CATComboBox _srcLangCombo;
  private CATComboBox _destLangCombo;
  private CATTextField _wordZone;
  private CATLabel _resultZone;
  
  private static String[] languages = {"English", "Francais", "Espagnol", "Italiano", "Deutch"};
  
  /**
   * Callback on panel creation
   **/
  public void onCreate( CATDialog iSource, CATNotification iNotification, Object iData )
  {
    // --- create the components
    // -------------------------
    CATLabel smartDictionaryTitle = new CATLabel(_frame, "SmartDictionaryTitle", 1);

    CATLabel sourceLangLabel = new CATLabel(_frame, "SourceLangLabel");
    _srcLangCombo = new CATComboBox(_frame, "SourceLangCombo");
    // --- listen to _srcLangCombo changes
    _srcLangCombo.addCallback(_srcLangCombo.getComboActivatedNotification(), this, "onSourceLanguage", null);

    CATLabel destLangLabel = new CATLabel(_frame, "DestLangLabel");
    _destLangCombo = new CATComboBox(_frame, "DestLangCombo");
    // --- listen to _destLangCombo changes
    _destLangCombo.addCallback(_destLangCombo.getComboActivatedNotification(), this, "onDestLanguage", null);

    CATLabel enterTextLabel = new CATLabel(_frame, "EnterTextLabel");
    _wordZone = new CATTextField(_frame, "WordZone");
    _wordZone.setWidth(32);
    
    CATButton translateButton = new CATButton(_frame, "TranslateButton");
    // --- listen to translateButton events
    translateButton.addCallback(translateButton.getButtonActivatedNotification(), this, "onTranslate", null);
    
    CATLabel resultLabel = new CATLabel(_frame, "ResultLabel");
    _resultZone = new CATLabel(_frame, "ResultZoneLabel");
    
    // --- set component texts
    // -----------------------
    smartDictionaryTitle.setTitle("Smart Dictionary v1");
    sourceLangLabel.setTitle("Source Language :");
    destLangLabel.setTitle("Destination Language :");
    enterTextLabel.setTitle("Enter text :");
    translateButton.setTitle("Translate!");
    resultLabel.setTitle("Result :");
    
    // --- layout the command
    // ----------------------
    _frame.setConstraints(smartDictionaryTitle, new GC(0, 0, 2, 1, GC.CENTER, GC.NOFILL));
    _frame.setConstraints(sourceLangLabel,       new GC(0, 1, 1, 1, GC.RIGHT, GC.NOFILL));
    _frame.setConstraints(_srcLangCombo,         new GC(1, 1, 1, 1, GC.LEFT, GC.NOFILL));
    _frame.setConstraints(destLangLabel,         new GC(0, 2, 1, 1, GC.RIGHT, GC.NOFILL));
    _frame.setConstraints(_destLangCombo,        new GC(1, 2, 1, 1, GC.LEFT, GC.NOFILL));
    _frame.setConstraints(enterTextLabel,        new GC(0, 3, 1, 1, GC.RIGHT, GC.NOFILL));
    _frame.setConstraints(_wordZone,             new GC(1, 3, 1, 1, GC.LEFT, GC.NOFILL));
    _frame.setConstraints(translateButton,       new GC(1, 4, 1, 1, GC.LEFT, GC.NOFILL));
    _frame.setConstraints(resultLabel,           new GC(0, 5, 1, 1, (GC.RIGHT | GC.TOP), GC.NOFILL));
    _frame.setConstraints(_resultZone,           new GC(1, 5, 1, 1, (GC.LEFT | GC.TOP), GC.NOFILL));
    
    _frame.setColumnResizable(1, 1);
    _frame.setRowResizable(5, 1);

    // --- initialize
    // --------------
    _srcLangCombo.setItems(languages);
   	_destLangCombo.setItems(languages);
  }

  /**
   * Callback on "source language" ComboBox modification
   **/
  public void onSourceLanguage( CATDialog iSource, CATNotification iNotification, Object iData )
  {
  }

  /**
   * Callback on "destination language" ComboBox modification
   **/
  public void onDestLanguage( CATDialog iSource, CATNotification iNotification, Object iData )
  {
  }

  /**
   * Callback on "translate" button pressed
   **/
  public void onTranslate( CATDialog iSource, CATNotification iNotification, Object iData )
  {
    _resultZone.setTitle("translate "+_wordZone.getText()+" from "+_srcLangCombo.getSelection()+" to "+_destLangCombo.getSelection());
  }

}

As you can see, the controller builds up the whole user interface in its "onCreate" method (which is called right after the command is activated). Creating the user interface is divided into 4 steps:

create the components,
set components strings (not localized here: hard coded in English),
layout the command,
other initializations (source and destination combos).

Remark: While creating the components, the controller makes several registrations:

registration to "ComboActivated" from the source language combo box,
registration to "ComboActivated" from the destination language combo box,
registration to "ButtonActivated" from the button.

[Top]

Declaring the SmartDictionary2 command

In our example, the SmartDictionary command is static (it never changes). It is very common that a large part of application user interfaces remains static. For those cases, JDialog gives the possibility to declare the static part of the user interface inside the XMLDlg file.

Here is the resource file "SmartDictionary2.XMLDlg", in which all static components and their layout are declared:

<?xml version="1.0"?>
  <Frame onCreate="onCreate" Controller="com.dassault_systemes.catjdialog.smartdictionary.CATSmartDictionaryController2">
    <!-- create the components --/>
    <Label Name="SmartDictionaryTitle" Level="1"/>
    <Label Name="SourceLangLabel"/>
    <ComboBox Name="SourceLangCombo" Attribute="_srcLangCombo" onComboActivated="onSourceLanguage"/>
    <Label Name="DestLangLabel"/>
    <ComboBox Name="DestLangCombo" Attribute="_destLangCombo" onComboActivated="onDestLanguage"/>
    <Label Name="EnterTextLabel"/>
    <TextField Name="WordZone" Width="32" Attribute="_wordZone"/>
    <Button Name="TranslateButton" onButtonActivated="onTranslate"/>
    <Label Name="ResultLabel"/>
    <Label Name="ResultZoneLabel" Attribute="_resultZone"/>

    <!-- layout the command --/>
    <GC Name="SmartDictionaryTitle"  X="0" Y="0" W="2" H="1" A="C"/>
    <GC Name="SourceLangLabel"       X="0" Y="1" W="1" H="1" A="R"/>
    <GC Name="SourceLangCombo"       X="1" Y="1" W="1" H="1" A="L"/>
    <GC Name="DestLangLabel"         X="0" Y="2" W="1" H="1" A="R"/>
    <GC Name="DestLangCombo"         X="1" Y="2" W="1" H="1" A="L"/>
    <GC Name="EnterTextLabel"        X="0" Y="3" W="1" H="1" A="R"/>
    <GC Name="WordZone"              X="1" Y="3" W="1" H="1" A="L"/>
    <GC Name="TranslateButton"       X="1" Y="4" W="1" H="1" A="L"/>
    <GC Name="ResultLabel"           X="0" Y="5" W="1" H="1" A="RT"/>
    <GC Name="ResultZoneLabel"       X="1" Y="5" W="1" H="1" A="LT"/>
    <Column X="1" W="1"/>
    <Row Y="5" W="1"/>
  </Frame>

As you can see, this new XMLDlg does most of the job that was done dynamically in the "onCreate" method in the previous Controller code. More precisely, it handles the following steps:

create the components (and makes appropriate registrations),
layout the command.

This is much less job for the controller!

[Top]

Creating the message catalog file for SmartDictionary2

JDialog provides a way of defining the component strings into a static message catalog (text file with extension CATNls).

Here is the message catalog "SmartDictionary2.CATNls":

// --- Message catalog for SmartDictionary version 2
SmartDictionaryTitle.Title = "Smart Dictionary v2";
SourceLangLabel.Title = "Source Language :";
DestLangLabel.Title = "Destination Language :";
EnterTextLabel.Title = "Enter text :";
TranslateButton.Title = "Translate!";
ResultLabel.Title = "Result :";

The great advantage of defining component strings in message catalog files is that JDialog manages automatically the localization for you. All you need to do is to provide different versions of your CATNls file (one for each supported language):

English CATNls file should be created in [myFrameWork]/CNext/resources/msgcatalog/[command name].CATNls
French CATNls file should be created in [myFrameWork]/CNext/resources/msgcatalog/French/[command name].CATNls
German CATNls file should be created in [myFrameWork]/CNext/resources/msgcatalog/German/[command name].CATNls
and so on...

Once again, this is a job the controller doesn't need to do anmore!

[Top]

Writing the SmartDictionary2 command controller

Now, the Controller code can be drastically reduced:

package com.dassault_systemes.catjdialog.smartdictionary;

import com.dassault_systemes.catjdialog.CATComboBox;
import com.dassault_systemes.catjdialog.CATLabel;
import com.dassault_systemes.catjdialog.CATDialog;
import com.dassault_systemes.catjdialog.CATNotification;
import com.dassault_systemes.catjdialog.CATTextField;

/**
 * JDialog controller for the 'SmartDictionary' command.
 **/
public class CATSmartDictionaryController2
{
  // --- attributes declared in the XMLDlg file
  public CATComboBox _srcLangCombo;
  public CATComboBox _destLangCombo;
  public CATTextField _wordZone;
  public CATLabel _resultZone;
  // --- end
  
  // --- private attibutes
  private static String[] languages = {"English", "Francais", "Espagnol", "Italiano", "Deutch"};
  
  /**
   * Callback on panel creation
   **/
  public void onCreate( CATDialog iSource, CATNotification iNotification, Object iData )
  {
    _srcLangCombo.setItems(languages);
    _destLangCombo.setItems(languages);
  }

  /**
   * Callback on "source language" ComboBox modification
   **/
  public void onSourceLanguage( CATDialog iSource, CATNotification iNotification, Object iData )
  {
  }

  /**
   * Callback on "destination language" ComboBox modification
   **/
  public void onDestLanguage( CATDialog iSource, CATNotification iNotification, Object iData )
  {
  }

  /**
   * Callback on "translate" button pressed
   **/
  public void onTranslate( CATDialog iSource, CATNotification iNotification, Object iData )
  {
    _resultZone.setTitle("translate "+_wordZone.getText()+" from "+_srcLangCombo.getSelection()+" to "+_destLangCombo.getSelection());
  }

}

The only thing the controller has to do in its "onCreate" method is to make initializations.

Remark: even filling combo-boxes could be done statically in the XMLDlg file!

[Top]

In Short

Creating a JDialog command involves 4 steps:

defining its layout (preferably on paper),
declaring the command, and defining its static part in a XMLDlg file,
creating associated message catalogs,
writing the controller class.

[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