TINGUIN Package

Document
Author/Editor	C. Haag (GMD)
Status	Draft Version 1, SEMPER internal

Abstract

This document describes the programming interface offered by the trusted user interface TINGUIN. The programming interface will be used by the various managers in order to display whatever they want and to get interaction from the user. This is the second version of the TINGUIN. It uses the IFC-Classes from Netscape to build a better looking GUI.

Introduction

The Trusted User Interface TINGUIN provides a user interface to the user for all SEMPER managers. Each (confidential) action might need user interaction, e.g., a payment action or an order has to be confirmed. TINGUIN will provide simple dialog mechanisms to handle the interaction. The public Java interface consists of seven classes:

The TinguinManager is the entry point for the programmer. It handles the various sessions, allocates new (Tinguin) sessions or deallocates sessions which are not existent anymore. It allows to link menus in the main TINGUIN menu. Status messages can be displayed in a window at the bottom of the TINGUIN.
The TinguinSession is a class that manages the InternalWindows of a session. It also handles the access to the TINGUIN.
The HTMLDoc class displays an HTML 1.0 Document in an InternalWindow.
The ConfirmHTML class displays also an HTML 1.0 Document, but this one must be confirmed by the user by pressing a button.
The YesNoHTML class displays also an HTML 1.0 Document, but this time there are two buttons. The user can select which button to press and the default is OK for the left button and Cancel for the right one.
The FreeDialog class can display normal text, HTML 1.0 text, Popups, RadioButton, Buttons, editable textfields and password textfields.
The ProgressBar class displays an InternalWindow which shows the user the state of an action.

TinguinManger

The TinguinManager is a static class or more precisely it contains only static members. Therefore it does not need an instantiation although an initialization will be necessary in order to build a menu for the preferences, a window which holds the buttons for the sessions and a window which shows status messages. The TinguinManager is used to create a new session or to delete a session that is no longer needed. The according methods are:

TinguinSession TinguinManager::newSession(String name); void TinguinManager::endSession(TinguinSession session);

Each created session appears in the "Sessions" menu in the TINGUIN and gets a button in the ButtonWindow at the top of the TINGUIN. The user is able to select the current viewable session by selecting its menuitem in the "Sessions" menu or selecting its button in the ButtonWindow. The endSession method closes all open windows of the session and removes the menuitem and button of the session. In order to initialize the TINGUIN the

void TinguinManager::init()

method has to be called. This creates a toplevel window with an menu, a window for the session buttons and a window for the status messages in it. The init method also loads previously saved preferences for the colors and background images of the elements of the TINGUIN. These preferences can be changed in the "Tinguin" menu. The newSesssion method returns a reference to a TinguinSession . To add your own menues to the TINGUIN menu the

MenuItem TinguinManager::addMenu(String title)

method has to be called. It adds a new menu with the text title an returns the corresponding menuitem under which you can create your own menu structure. Finally the methods

void TinguinManager::setStatusText(String text)
void TinguinManager::addStatusText(String text)

can be called to set/add text to the status window at the bottom of the TINGUIN.

TinguinSession

Access control

Since only one session should display its output or wait for its input at a time, the access to the TINGUIN must be controled. The responsible class is TinguinSession . If a session wants to displays its output it should call

void TinguinSession::acquire()

before displaying output or waiting for input and

void TinguinSession::release()

after it needs no longer control of the TINGUIN. Example:

... create the output doc to be displayed be the TinguinSession ses
ses.acquire();
ses.addWindow(doc, ...);
ses.release();

Windows in TinguinSessions

A TinguinSession can have several InternalWindows which are displayed at the same time in the TINGUIN. If a user switches the session, all windows of the current session are hidden and all windows of the switched session are shown. A user can add windows to a session with

void TinguinSession::addWindow(InternalWindow win)
void TinguinSession::addWindow(InternalWindow win, int placement)

The placement variable decide where and at which size the windows are shown.

AUTO_PLACE_VERT: the windows are maximized in the height and share the width equally.

AUTO_PLACE_HORIZ: the windows are maximized in the width and share the height equally.

AUTO_PLACE_CENTER_AND_MAXED: only the actually added window is centered and also maxed in its size. This is the default for addWindow(InternalWindow win).

AUTO_PLACE_CENTER: only the actually added window is centered, but its size is not changed (useful for ProgressBar).

SELF_PLACE: neither the position nor the size of the actually added window are changed.

To remove a window from a session call

void TinguinSession::removeWindow(InternalWindow win)

or to remove all windows

void TinguinSession::removeAllWindows()

Note: When a session is closed all windows of the session are closed automatically.

Input/Output

All classes for Input/Output on the TINGUIN are subclasses of InternalWindow and can be added to a TinguinSession. All classes can be customized with a color for the background which can be saved in the menu "Tinguin" and is loaded automatically at startup.

HTMLDoc

The HTMLDoc class constructs an InternalWindow with scrollbars which can display HTML 1.0 Documents. The Constructors are

HTMLDoc(String title)
HTMLDoc(String title, int xPos, int yPos, int width, int height)

where title is the title of the window. Optionally can be passed the x- and y-position and the width and height of the window. HTML-Text can be added either by String

void HTMLDoc::HTMLFromString(String html)

or from an URL

void HTMLDoc::HTMLFromUrl(String url)

Here an example:

// Make a session
TinguinSession ses = TinguinManager.newSession("Test");
// Make a HTMLDoc
HTMLDoc doc = new HTMLDoc("Html-Text");
// Add HTML-Text
doc.HTMLFromString("<HTML><HEAD></HEAD><BODY><H1>Hello</H1></BODY></HTML>");
// acquire display
ses.acquire();
// Add the HTMLDoc to the session and show it
ses.addWindow(doc);
// release display
ses.release();
...
// remove HTMLDoc from the session
ses.removeWindow(doc);
// end session
TinguinManager.endSession(ses);

ConfirmHTML

The ConfirmHTML class constructs an InternalWindow with scrollbars which can display HTML 1.0 Documents. It has a button at the bottom. By default the button is labeled "OK". The Constructors are

ConfirmHTML(String html)
ConfirmHTML(String html, String buttonText)
ConfirmHTML(String html, String buttonText, Color htmlBackgroundColor, Color buttonBackgroundColor)
ConfirmHTML(String html, String buttonText, Color htmlBackgroundColor, Color buttonBackgroundColor, int xPos, int yPos, int width, int height)

Optionally can be passed the title of the button, the background color of the Html text, the background color of the button and the position, width and height of the window. The example follows the one above (HTMLDoc):

// Make a session
TinguinSession ses = TinguinManager.newSession("Test");
// Make a ConfirmHTML
ConfirmHTML doc = new ConfirmHTML("<HTML><HEAD></HEAD><BODY><H1>Hello</H1></BODY></HTML>");
// acquire display
ses.acquire();
// Add the HTMLDoc to the session and show it
ses.addWindow(doc);
// wait until the user pressed the button
doc.modally();
// release display
ses.release();
...
// remove HTMLDoc from the session
ses.removeWindow(doc);
// end session
TinguinManager.endSession(ses);

The method

void ConfirmHTML::modally()

returns only if the user pressed the button and is used as shown above. The TINGUIN should be acquired when you call it.

YesNoHTML

The YesNoHTML class constructs an InternalWindow with scrollbars which can display HTML 1.0 Documents. It has two buttons at the bottom. By default the left button is labeled "OK" and the right one "Cancel". The Constructors are

YesNoHTML(String html)
YesNoHTML(String html, String leftButtonText, String rightButtonText)
YesNoHTML(String html, String leftButtonText, String rightButtonText, Color htmlBackgroundColor, Color buttonBackgroundColor)
YesNoHTML(String html, String leftButtonText, String rightButtonText, Color htmlBackgroundColor, Color buttonBackgroundColor, int xPos, int yPos, int width, int height)

Optionally can be passed the title of the buttons, the background color of the Html text, the background color of the buttons and the position, width and height of the window. The Example is nearly identical with the one of ConfirmHTML, except the return value of the method modally():

...
YesNoHTML doc = new YesNoHTML("<HTML><HEAD></HEAD><BODY><H1>Hello</H1></BODY></HTML>");
...
// determine which button was pressed
String result = doc.modally();
if(result.equals("OK") {
  // do something
} else {
  // do another thing
}
...

FreeDialog

The FreeDialog class can hold several types of views in one window. These are ButtonGroup, ContainerGroup, EditField, EditGroup, HTMLText, PopupGroup, RadioGroup and Text. The FreeDialog has always two buttons at the bottom. The Constructors are

FreeDialog(String title)
FreeDialog(String title, int xPos, int yPos, int width, int height)

where title is the title of the window. Optionally can be passed the position, width and height of the window. Example:

FreeDialog doc = new FreeDialog("Order");

You can add the following views to a FreeDialog:

Text:

Text is added by the

void FreeDialog::addText(String text)
void FreeDialog::addText(String text, int fontsize)
void FreeDialog::addText(String text, Color bg, Color fg)
void FreeDialog::addText(String text, Color bg, Color fg2, Font font)

methods. The first one adds text to the FreeDialog with the background color gray, the textcolor black and with the font Helvetica 12. In the second method you can change the fontsize, and in the third one you can change the background color and the textcolor. In the last method you can also change the font.

doc.addText("Size");
doc.addText("Size", 14);
doc.addText("Size", Color.red, Color.white);
doc.addText("Size", Color.red, Color.white, new Font("Helvetica", Font.BOLD, 20));

ButtonGroup:

A ButtonGroup is added by the

void FreeDialog::addButtonGroup(Vector elements, int alignment)

method. This method constructs a ButtonGroup, where the button labels are determined by the toString() method of the elements. The buttons can be ordered vertically (alignment=ButtonGroup.NORTHSOUTH) or horizontally (alignment= ButtonGroup.WESTEAST).

Vector elements = new Vector();
elements.addElement("S");
elements.addElement("M");
elements.addElement("L");
doc.addButtonGroup(elements, ButtonGroup.WESTEAST);

RadioGroup:

A RadioGroup is added by the

void FreeDialog::addRadioGroup(String title, Vector elements, int alignment)

method. This method constructs a RadioGroup, where the button labels are determined by the toString() method of the elements. On top of the buttons the text title is shown. The buttons can be ordered vertically (alignment=ButtonGroup.NORTHSOUTH) or horizontally (alignment= ButtonGroup.WESTEAST).

Vector elements = new Vector();
elements.addElement("Red");
elements.addElement("Blue");
elements.addElement("Green");
doc.addRadioGroup("Choose a color:", elements, ButtonGroup.NORTHSOUTH);

PopupGroup:

A PopupGroup is added by the

void FreeDialog::addPopupGroup(Vector elements)

method. This method constructs a PopupGroup, where the item labels are determined by the toString() method of the elements.

Vector elements = new Vector();
elements.addElement("Red");
elements.addElement("Green");
elements.addElement("Blue");
doc.addPopupGroup(elements);

HTML-Text:

HTML-Text is added by the

void FreeDialog::addHTMLText(String html)

method. This method adds the HTML 1.0 Text html to the FreeDialog.

doc.addHTMLText("<hr><h1>Kundennummer:</h1>");

EditField:

An EditField is added by the

void FreeDialog::addEditField(String text, String edittext)
void FreeDialog::addEditField(String text, String edittext, boolean mustInput)

method. text is shown on the left side and the editable edittext on the right side. If mustInput is true, the dialog is only left when something is entered.

doc.addEditField("Kundennummer: ","123456");

PasswordField:

An PasswordField is added by the

void FreeDialog::addPasswordField(String text, String passtext)
void FreeDialog::addPasswordField(String text, String passtext, boolean mustInput)
void FreeDialog::addPasswordField(String text, String passtext, boolean mustInput, boolean wantsKeyEvents)

methods. This method adds an EditField to the FreeDialog, where the input is shown as "*". If wantsKeyEvents is true, the FreeDialog can be exited by pressing RETURN or ESC in the password. If RETURN is pressed the left button is simulated and if ESC is pressed the right button is simulated.

doc.addPasswordField("secret key: ", "");
doc.addPasswordField("secret key: ", "1234", true);

EditGroup:

An EditGroup is added by the

void FreeDialog::addEditGroup(Vector editFields)

method. An EditGroup can only hold EditFields (and also PasswordFields which are EditFields). It draws a frame around the EditFields and makes them all the same size.

Vector elements = new Vector();
EditField edit1 = new EditField("Name: ", "schmidt");
elements.addElement(edit1);
EditField edit2 = new EditField("secret key: ", "", true);
elements.addElement(edit2);
doc.addEditGroup(elements);

ContainerGroup:

An ContainerGroup is added by the

void FreeDialog::addGroup(Vector views)

method. An ContainerGroup can hold all kind of the above views. It draws a frame around its elements.

Vector elements = new Vector();
EditField edit1 = new EditField("Name: ", "schmidt");
elements.addElement(edit1);

HTMLText html1 = new HTMLText("<hr><h1>Kundennummer:</h1>");
elements.addElement(html1);

Vector elements2 = new Vector();
elements2.addElement("Red");
elements2.addElement("Blue");
elements2.addElement("Green");
RadioGroup radio1 = new RadioGroup("Choose a color:", elements2, ButtonGroup.NORTHSOUTH);
elements.addElement(radio1);

doc.addGroup(elements);

Space:

Space is added by the

void FreeDialog::addSpace(int pixel)

method. It is added between the last added view and the next view.

doc.addSpace(10);

Adding the OK and Cancel buttons

After you have added all views, you must tell the FreeDialog to add the two buttons at the bottom. You do this with the methods

void FreeDialog::endDialog()
void FreeDialog::endDialog(String leftButtonText, String rightButtonText)

The default is "OK" for the left button and "Cancel" for the right one. You can change this with the second method. Now you can add the FreeDialog to a TinguinSession.

Getting the results:

To get the results of the FreeDialog you can call the

Hashtable FreeDialog::getResult()

method. The getResult() method returns a Hashtable with the results of the user interaction. Since getResult() is an implementation of the Result interface, and all the views you can add to a FreeDialog must implement it, you can also call getResult() of each view directly. On RadioGroups and PopupGroups you can also call selected(), which returns the selected Object.

// Make a session
TinguinSession ses = TinguinManager.newSession("Test");
 
FreeDialog doc = new FreeDialog("Order");

Vector elements = new Vector();
EditField edit1 = new EditField("Name: ", "schmidt");
elements.addElement(edit1);

HTMLText html1 = new HTMLText("<hr><h1>Kundennummer:</h1>");
elements.addElement(html1);

Vector elements2 = new Vector();
elements2.addElement("Red");
elements2.addElement("Blue");
elements2.addElement("Green");
RadioGroup radio1 = new RadioGroup("Choose a color:", elements2, ButtonGroup.NORTHSOUTH);
elements.addElement(radio1);

doc.addGroup(elements);

doc.endDialog();
// acquire display
ses.acquire();
// Add the FreeDialog to the session and show it
ses.addWindow(doc);
// wait for user pressing a button
String button = doc.modally();
// release display
ses.release();
// get the results
Hashtable hash = doc.getResult();
System.out.println(User pressed button: " + button);
System.out.println("Name: " + hash.get("Name: "));
System.out.println("Color: " + radio1.selected().toString());
...

ProgressBar

With the help of the ProgressBar class you can show the user how long an action will take, and what the system is doing at the moment. It opens an InternalWindow with a field for an action text, a bar showing the percentage of the action performed, and a field for a subaction text. The Constructors are

ProgressBar(String title)
ProgressBar(String title, int xPos, int yPos)

where title is the title of the InternalWindow and xPos and yPos are the coordinates of the window. You can then set the action and subaction text with

void ProgressBar::setActionText(String text)
void ProgressBar::setSubActionText(String text)

You can now set the percentage of the ProgressBar directly with

void ProgressBar::setProgress(int percentage)

or you can define the number of subactions with

void ProgressBar::setNumberOfActions(int number)

and increase it with

void ProgressBar::incNumberOfActions()

Example:

...
ProgressBar p = new ProgressBar("Get html-page");
p.setActionText("getting html-page...");
p.setSubActionText("contacting host...");
p.setNumberOfActions(3);
ses.addWindow(p, TinguinSession.AUTO_PLACE_CENTERED);
// do something
p.incNumberOfActions();
p.setSubActionText("host contacted, waiting for reply...");
// do something
p.incNumberOfActions();
p.setSubActionText("getting html...");
// do something
p.incNumberOfActions();
p.setSubActionText("done");
ses.removeWindow(p);
...

Entries in _sempconfig

TINGUIN makes several entries in the _sempconfig file. Normally you should not edit these. Here are the meanings of the entries:

#semper.tinguin.imagePath: This is the path to the images of the buttons, ... When you start semper without this entry it uses the Method semper.util.install.Installer.getSEMPERRoot() to calculate this path. The images should reside in the path "semperroot"/data/tinguin. When you get an error about images you should first try to delete this entry in _sempconfig.

#semper.tinguin.backImagePath: This is the path to the background images. When you start semper without this entry it uses the Method semper.util.install.Installer.getSEMPERRoot() to calculate this path. The background images should reside in the path "semperroot"/data/tinguin/background. When you get an error about images you should first try to delete this entry in _sempconfig.

The following entries can all be set with the ColorChooser or ImageChooser per Drag-and-Drop or in the Options-menu. The entries can be saved with the "Save Options"-entry in the Options-menu.

#semper.tinguin.RootView.Color: The negativ value of this entry defines the background color of the main Tinguin-window. If it is not set, the default color is grey.

#semper.tinguin.RootView.Image: Defines the name of an image which is displayed in the main Tinguin-window. The image must reside in the background-images-directory.

#semper.tinguin.StatusWindow.Show: The value of this entry can be 0 or 1. If it is 0 the StatusWindow is NOT shown and if it is 1 the StatusWindow is shown.

#semper.tinguin.StatusWindow.Color: The negativ value of this entry defines the background color of the StatusWindow. If it is not set, the default color is grey.

#semper.tinguin.SessionWindow.Show: The value of this entry can be 0 or 1. If it is 0 the SessionWindow is NOT shown and if it is 1 the SessionWindow is shown.

#semper.tinguin.SessionWindow.Color: The negativ value of this entry defines the background color of the SessionWindow. If it is not set, the default color is grey.

#semper.tinguin.SessionWindow.Image: Defines the name of an image which is displayed in the SessionWindow. The image must reside in the background-images-directory.

#semper.tinguin.AutoSave: The value of this entry can be 0 or 1. If it is 1 the colors, images, ... are saved before the Tinguin is quit. If it is 0 they are not saved.

#semper.tinguin.FreeDialog.Color: The negativ value of this entry defines the background color of FreeDialogs. If it is not set, the default color is grey.

#semper.tinguin.ConfirmHTML.Color: The negativ value of this entry defines the background color of ConfirmHTMLs. If it is not set, the default color is grey.

#semper.tinguin.HTMLDoc.Color: The negativ value of this entry defines the background color of HTMLDocs. If it is not set, the default color is grey.

#semper.tinguin.YesNoHTML.Color: The negativ value of this entry defines the background color of YesNoHTMLs. If it is not set, the default color is grey.