TINGUIN Package

Document

311GM041

Author/Editor

T. Himstedt (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.

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 five classes:

TinguinManger

The TinguinManager is a static class or more precisely it contains only static members. Therefor it does not need an instantiation although an initialization will be necessary in order build a menu for the preferences. The TinguinManager is used to create a new display for a session or to delete a display if the session no longer exists. The according methods are:

TinguinDisplay TinguinManger::newSession(String sessionName);
void TinguinManager::closeSession(TinguinDisplay displayToRemove );

Each created session appears in a menu in the TINGUIN so the user is able to select the current viewable session. Since TinguinDisplay is only a Java interface the newSession method actually returns an GraphTinguin object In order to initialize the TINGUIN the

void TinguinManager::init()
method has to be called. In the current version of TINGUIN this creates a toplevel window with an appropriate menu in it. The newSesssion method returns a reference to a TinguinDisplay (currently this is an Object of the class GraphTinguin).

TinguinDisplay

Access control

This display is used for all outputs and inputs of the according session. Since a display can be a critical resource access must be controlled. In order to prevent the managers in the same session context to display their contents simultaneously on the same display a display must be acquired. If it is acquired only one manager has access to it. After displaying something the manager should release the display as soon as possible to ensure that other managers do not have to wait longer than necessary. Example:
// display is a reference to a TinguinDisplay, doc is an instance of 
// a Document or StructDoc 
.... create contents for document 
doc display.acquire();
display.showDocument( doc ); 
display.release(); 

Document based output/input

Currently the TinguinDisplay provides 5 methods for displaying a document.
  1. The simplest method is the
    void TinguinDisplay::showDocument( Document doc );
    method. This clears to current display and displays the document doc. It does not wait for user input or response.
  2. void TinguinDisplay::confirm(Document doc );
    does the same except that it waits for the user to press a confirm button.
  3. In order to get an a yes or no answer from the user the method
    boolean TinguinDisplay::yesNoDialog( Document doc, String yesLabel, String noLabel);
    is appropriate. In case the user pressed the button labeled with yesLabel it returns true otherwise it returns false.
  4. If some kind of selection of an object is necessary the method
    DialogResult TinguinDisplay::selectObject(Document doc, Vector objectList);
    may be invoked. The first argument is as usual the document to be presented. The second argument is a list (or a Vector) of objects which are presented in an option list. The objects in the list will be shown using their toString() method. Example:
    Vector list = new Vector(); 
    list.add(new String("String Object")); 
    list.add(new Integer(5)); 
    list.add(new Dimesnion(20, 20)); 
    DialogResult r = display.selectObject( doc, list); 
    System.out.println("Result is valid: " + r.ok().toString()); System.out.println("Result:" + r.result.toString()); 
  5. To request the user to fill out a simple form the
    DialogResult TinguinDisplay::evalForm(Document doc, Vector fields);
    has to be invoked. Again doc is the document to be presented. The Vector field contains Entrys which will appear as labels for the textfields. The method return an instance of class DialogResult. The method result of that object returns a hashtable containing key/value pairs. The keys are the elements from field and the values are the inputs that the user has entered in the according textfield. Example:
     
    Vector fields = new Vector(); 
    fields.add( new Entry( "Enter firstname")); 
    fields.add( new String( "Enter surname", true, true) ); 
    DialogResult r = display.evalFrom( doc, fields ); 
    System.out.println("User presed ok button:" + r.ok().toString()); 
    Hashtable t = (Hashtable)r.result();
    for (Enumeration e = t.keys(); e.hasMoreElements() ;) { 
    	String key = (String)e.nextToken(); 
    	String value = (String)t.get(key);
    	System.println("Key was " + key + "Value was " + value); 
    } 
    

Simple String dialogs

Besides the document based dialogs there are also simpler message dialogs. Instead of presenting a document they show just a simple multiline string message. Again these methods are elements (implementations) of interface class TinguinDisplay. To confirm a message the method

void TinguinDisplay::confirmMessage( String message, String confirmLabel );
can be used. Moreover to get a yes or no from the user the

void TinguinDisplay::yesNoMessage( Sting message, String yesLabel, String noLabel);
is appropriate. Also similar to the document based dialogs the method
DialogResult TinguinDisplay::formMessage( String message, Vector fields);
works just like the document based equivalent. The string messages may contain '\n''s in order to separate lines in the message.

Results from dialogs

Dialog results will be returned in instance of class DialogResult. This class has two public member
  1. The boolean DialogResult::ok() method returns true if the used selected ok, yes or whatever the ok-button was labeled with, otherwise it will be false returned.
  2. The Object DialogResult::result() method returns the actual result object. In case a form based dialog such as evalForm or formMessage was used this is a reference to a Hastable. In case the selectObject dialog was used this is just the selected object.

Documents

Documents are reflected in the class Document and StructDoc. Presumably most programmers will use only StructDoc since the base class Document is quite low level.

In general documents contain text and layout information such as margins or fonts. All of these layout information's are handled on a stack. So whenever a new font is pushed on the font stack it is valid since the top most font on the stack is valid. After popping a font from the stack this font is not valid anymore but as before the (new and old) top most font is valid.

To make the creation of documents more convenient the subclass StructDoc was introduced. This class offer methods for add ordererd/unordered list, headings with different levels, desorption lists and a simpler font changing mechanism. The methods are: