TINGUIN Package

Abstract

Introduction

• The TinguinManager is the entry point for the programmer. It handles the various sessions, allocates new (Tinguin) displays or deallocates displays which are not existent anymore.
• The TinguinDisplay is an interface class that represents a display for a (business) session. It offers mechanisms to display simple dialogs which request interaction from the user. A display is presumably shared among the different managers and therefor it has to be acquired and released after usage.
• The Document and StructDoc classes define layouted text which are shown via a TinguinDisplay
• The DialogResult class is used for returning the results of user interaction

TinguinManger

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

To build the preferences menu the menu the method:
void TinguinManger::buildPrefs() has to be invoked. This should probably renamed to init(). The newSesssion method returns a reference to a TinguinDisplay (currently this is an Object of the class GraphTinguin).

TinguinDisplay

Access control

// 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

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 there 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

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

1. The boolean DialogResult::ok() method return 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.

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:

• void StructDoc::beginOrderedList() to start an ordered list. The list items are then added with the method void StructDoc::addItem(String itemToAdd). To complete the list close it with void StructDoc::endOrderedList(). To handle unorderd list just use beginUnorderedList, endOrderedList . instead of beginOrderedList, endOrderdList
• To add a heading with a given level use void StructDoc::addHeading(String headingString, int level). The level may be in the range of 1 to 5 whereat 1 is the biggest size.
• To add a description of an item use void StructDoc::describeItem(String item, String descripton). This will print the item in one line. Then next line contains the indented descrition.
• To change the following text use one of beginItalic(), beginBold() or beginFixed(). All following text which is then added with void Document::addFlowingData(String text) or void Document::addLiteralData(String text) is then printed in that font. To use the old font again invoke endBIF(). In order to print just singe a string in a different font invoke one of addBoldFlowing(String text), addItalicFlowing(String text) or addFixedFlowing(String text)