ELSID Software Systems LTD.
 

Trellis™

Screen Shot - trellis3.jpg Screen Shot - trellis4.jpg

Trellis API Manual (Java 1.3)

Updated, June28, 2001

Table of Contents

Introduction

Trellis is a user interface building tool designed around the Java Swing classes. It has been designed to simplify the createon of graphical user interfaces build around the Swing construct of a JFrame that contains several JInternalFrames. The framework handles all menu and tool bar creation and exception handling and allows modules, JInernalFrames, to ba added and removed without having to rebuild or restart the base Trellis application.

Trellis itself is a JFrame that dynamicly loads user created internal frames build by extending the Trellis BaseModule as they are selected by the Start menu. As each module is loaded it has its own menu bar and tool bar created and assigned to it. These are then displayed in the Trellis home frame whenever they are selected. (See above)

toc...

The Trellis Framework provides:

  • a menu management system that is pre loaded with the basic file and edit menu entries
  • a tool bar management system that is pre loaded with the basic file and edit tools
  • a data sharing manager so that modules can share data between themselves
  • default access to the system clipboard for String objects
  • console window for module debug output
  • system status line for modules to display information to the user
  • a Start button with menu for launching modules
toc...

Module Creation

All modules are an extension of the BaseModule which is itself an extension of the JInternalFrame. The BaseModule contains a collection of private, public, and final methods that are used to interface it with the framework.

The private methods have to do with the internal workings of the module and its relationship to the Framework. The final methods are accessible by the module designer and perform functions that interface with the framework. The public methods are essentially method stubs that can be overloaded by the module designer. These are mainly menu and tool bar actions.

Each module has its own Menu Bar and Tool Bar. This will contain the Trellis framework menu items, the basic module items and any additional menu items or tool bar buttons defined by the module. As each module is selected it's menu or tool bar will be displayed on the framework.

Including a Module In the Trellis Framework

To include a new module in the Trellis Framework edit the file called Trellis.modules. It has the following format:

    Start Menu name , module or package name

    For example:

    	Editor	,	com.elsid.editor.Edit
    	Draw	,	MyDrawProg
    

    When ever the Start button is selected this file is read in and displayed as a pop up menu. Once the selection is made the corresponding class file is loaded and executed.

toc...

Trellis Properties File

When the a Trellis application starts it will load this file in order to initialize its menu strings and messages.
# Trellis properties file
# Main Frame Title
frame_title = Trellis Version 1.0
# Start Menu Modules File
modules_file = trellis.modules
#Start Button Caption
start = Start
# Common Menu Entries
file = File
new = New
open = Open
close = Close
save = Save
save_as = Save As...
exit = Exit
edit = Edit
cut = Cut
copy = Copy
paste = Paste
tools = Tools
console = Console
help = Help
about = About
# ToolBar Images
new.img = new.gif
open.img = open.gif
save.img = save.gif
copy.img = copy.gif
cut.img = cut.gif
paste.img = paste.gif
# Messages
exit_msg = Close all Modules and exit?
help_msg = Please see the Readme file.
about_msg = Trellis\nVersion 0.1\n
		Copyright (c) 2001\n
		ELSID Software Systems LTD. Ottawa, CANADA
toc...

Example Module

/*
	GetRandom.java
*/

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

import com.elsid.basegui.*;

public class GetRandom extends BaseModule
{
	private static final String ACTION_GET_NUMBER = "random";
	private static final String TITLE_ENTRY = "Create Random Numbers";
	private static final String MENU_ENTRY = "Make Random Number";
	private static final String ITEM_ENTRY = "Do It";
	
	JTextField label;
	
	// Constructors
	
	public GetRandom( BaseGUI base_gui  )
	{
		super( base_gui );
		JButton fetch;
		
		setTitle(  TITLE_ENTRY  );		
		setSize( 200, 100 );	
		getContentPane().setLayout( new BorderLayout() );		
		getContentPane().add( "North", fetch = new JButton( MENU_ENTRY ));
		fetch.addActionListener( new ActionListener()
		{
			public void actionPerformed( ActionEvent e )
			{
				doGetRandom();
			}
		});
		
		label = new JTextField();
		label.setHorizontalAlignment( JTextField.CENTER );
		label.setBackground( Color.white );	
		label.setBorder( BorderFactory.createLoweredBevelBorder() );
		
		getContentPane().add( "Center", label );
	
		// Set up the menu bar
		
		// Add a new menu and an item.
		addMenuItem( MENU_ENTRY, ITEM_ENTRY, 
				ACTION_GET_NUMBER );	
		
		// Create the menu bar
		initMenuBar();

		// Disable the basic menu set.
		enableBasicMenus( false );

		// Enable the Edit - Copy menu item.
		enableMenuItemName( Menus.get(Menus.EDIT), 
				Menus.get(Menus.COPY), true );
		
		// Set up the tool bar
		
		addToolSeparator();

		// Add a new tool to generate the random number.

		addTool( null, ACTION_GET_NUMBER, MENU_ENTRY );

		// Create the tool bar.
		initToolBar();

		// Disable the basic tool set, we don' t need them.
		enableBasicTools( false );

		//  Enable the Copy Tool
		enableToolAction(Tools.get( Tools.COPY_ACTION ), true );
				
		setVisible( true );
	}
	
	// Public Methods Overloaded from super class
	
	public void doClose()
	{
		setVisible( false );
		dispose();
	}
	
	public void doCopy()
	{
		String str = null;
		
		str = label.getSelectedText();
		if( str != null && str.length() > 0 )
			setClipboardString( str );
	}
	
	public void doLocalMenuCommand( String command )
	{
		if( command.equals( ACTION_GET_NUMBER ) )
			doGetRandom(); 
	}
	
	public void doAbout()
	{
		JOptionPane.showMessageDialog( base_gui,
				"Generate Unique ID's\nVersion 0.1\nCopyright (c)" + 
				"2001\nELSID Software Systems LTD. Ottawa," +  
				"CANADA", Strings.get( Strings.MENU_ABOUT ), 
				JOptionPane.PLAIN_MESSAGE);
	}
	
	public void doHelp()
	{
		JOptionPane.showMessageDialog( base_gui, "Produces a random key." ,
				Strings.get( Strings.MENU_HELP ), 
				JOptionPane.PLAIN_MESSAGE);
	}
	
	// Other public methods	
	
	public void doGetRandom()
	{
		label.setText( "" + (int)(Math.random() * 100000) );		
	}	
}
toc...

BaseModule Methods

File IO

public final boolean doSaveWriteText( String file_name, String text, int mode )

    This method will write out the given String text to the file file_name. The file_name is selected based on the mode.

    • Trellis.SAVE_AS a file dialog will be displayed.

    • Trellis.SAVE then the text will be saved to the currently selected file name or if non exists then a file dialog will be displayed.

    If the operation was successful it will return true else it will return false.

public final FileData doOpenReadText( String file_name )

    This method will return a FileData object that will contain the actual name of the file that was opened for reading and its contents as a String. It will display a file dialog prior to opening the file.

    If the Open File dialog was exited without a file being selected null will be returned.

toc...

Message Display

public final void addConsoleMessage( String message )

    The message will be displayed in the Trellis Console window.

public final void setStatusMessage( String message )

    The message is displayed on the Trellis Status line. the previous message will be erased.

toc...

Toolbar Manipulation

public final void addToolSeparator()

    Add a separator to the tool bar.

public final void addTool( String image_file, String action )

    Add a new tool to the Trellis tool bar. The image to be displayed is contained in the image_file.

    When the tool is selected the modules doLocalMenuCommand method will be called with the action passed as an argument.

public final void addTool( String image_file, String action, String name )

    Add a new tool to the Trellis tool bar. The image to be displayed is contained in the image_file. A name may be attached to the toll image. If the image_file is 'null' then only the tool name is displayed.

    When the tool is selected the modules doLocalMenuCommand method will be called with the action passed as an argument.

public final void enableToolAction( String action, boolean enable )

  • If enable is true the tool is enabled. I
  • f enable is false the tool is disabled.

public void initToolBar()

    This method must be called after the last addTool method to create the module tool bar and before any enabling methods.

public void enableBasicTools( boolean enable )

  • If enable is true the basic tool set is enabled.
  • If enable is false the basic tool set is disabled.

toc...

Menu Manipulation

public void addMenuSeparator( String menu )

    Add a separator to the menu.

public final void addMenuItem( String menu_name, String item_name, String action )

    Creates a menu entry.

    If the action string is defined, not null, it will be passed to the doLocalMenuCommand when this item is selected. If the action is null then the item name will be passed to the doLocalMenuCommand .

public final void initMenuBar()

    This method must be called after the last addMenuItem method to create the module menu bar and before any enabling methods.

public boolean addMenuMnemonic( String menu_name, char mnemonic )

    This method will under line the given letter in the menu name allowing that character to be pressed along with the ALT key to activate the menu.

public boolean addMenuItemMnemonic( String menu_name, String item_name, char mnemonic )

    This method will under line the given letter in the menu item name allowing that character to be pressed to activate the menu item.

    public boolean addMenuItemAccelarator( String menu_name, String item_name, char accelerator, int modifier)

    This method assigns an accelerator character to a given menu item. In addition to the accelerator character a modifier may be assigned to the accelerator key.

    • Trellis.ALT_KEY
    • Trellis.CTRL_KEY
    • Trellis.SHIFT_KEY

public final void enableMenu( String menu_name, boolean enable )

  • If enable is true the menu is enabled.
  • If enable is false the menu is disabled.

public final void enableMenuItemName( String menu_name, String item_name, boolean enable )

  • If enable is true the menu item is enabled.
  • If enable is false the menu item is disabled.

public final void enableMenuItemAction( String menu, String action, boolean enable )

  • If enable is true the menu action is enabled.
  • If enable is false the menu action is disabled.

public void enableBasicMenus( boolean enable )

  • If enable is true the basic tool set is enabled.
  • If enable is false the basic tool set is disabled.

toc...

Clipboard Operations

public final String getClipboardString()

    Returns the current String object in the system clipboard. If no string is their then null is returned.

public final void setClipboardString( String str )

    Places the passed string into the system clipboard.

toc...

Shared Data Storage

public final void addData( Object key, Object data )

    Add this Object to the data sorage manager.

public final void removeData( Object key )

    Remove this Object from the data storage manager.

public final Object getData( Object key )

    Get the reference to the Object from the data storage manager.

toc...

Module Activation Methods

public void doWhenActivated()

    This method is processed when the module is activated or gains focus.

public void doWhenDeactivated()

    This method is processed when the module is deactivated or looses focus.

public void doWhenClosing()

    This method is processed prior to the module being closed.

public void doWhenClosed()

    This method is processed after the module has been closed but before it has been disposed of.

toc...

Pre-programmed menu / toolbar functions

public void doClose()

    Processed when the menu File Close is selected.

public void doNew()

    Processed when the menu File New or the Tool Bar New is selected.

public void doOpen()

    Processed when the menu File Open or the Tool Bar Open is selected.

public void doSave()

    Processed when the menu File Save or the Tool Bar Save is selected.

public void doSaveAs()

    Processed when the menu File Save As is selected.

public void doCut()

    Processed when the menu Edit Cut or the Tool Bar Cut is selected.

public void doCopy()

    Processed when the menu Edit Copy or the Tool Bar Copy is selected.

public void doPaste()

    Processed when the menu Edit Paste or the Tool Bar Paste is selected.

public void doHelp()

    Processed when the menu Help Help is selected.

public void doAbout()

    Processed when the menu Help About is selected.

toc...

User Defined Menu / Tool Bar Selection

public void doLocalMenuCommand( String action_command )

    This menu is call when ever a user defined menu entry or tool bar toll is selected.

    If the selected item has an action string assigned to it the string will be passed as the argument if not then the name of the item will be passed.

toc...

Basic Menu Actions

    New
    executes the doNew() method
    Open
    executes the doOpen() method
    Close
    executes the doClose() method
    Save
    executed the doSave() method
    Save As
    executed the doSaveAs() method
    Cut
    executes the doCut() method
    Copy
    executes the doCopy() method
    Paste
    executes the doPaste() method
toc...

Basic Tool Bar Actions

    New
    executes the doNew() method
    Open
    executes the doOpen() method
    Save
    executed the doSave() method
    Cut
    executes the doCut() method
    Copy
    executes the doCopy() method
    Paste
    executes the doPaste() method
toc...
ELSID Home Page.
Copyright(c) 2001, ELSID Software Systems LTD.
ELSID is a registered trademark of ELSID Software Systems LTD.