3.4.6 - Text Table - JdlTextTable

John W. Campbell

3.4.6.1 Introduction

This class provides a text table area for the simple output of text from a program, particularly for tabular data. There is no scrolling. The text may be in bold or normal print in a variety of colours. The program may output text at any character position within the window and areas of the window may be cleared and redrawn as required. A limited series of symbols is also available. There is an option to create a text table with cells defining areas of text which may be highlighted and, when required, selected using the mouse. Though the basic functions of this object are all included in the JdlGraphicsWindow view-object, this object does allow different character sizes and, when it meets the requirements, it is simpler to use.

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Operational Methods
Standard Positioning and Sizing
Add/Remove Action Listener
Get Returned Data
Overriden Superclass Methods

3.4.6.2 Class Details

Package:: Jdl.JdlView;
Class name:: JdlTextTable
Class definition:: public class JdlTextTable
Extends:: JdlDrawPanel
Implements:: MouseListener
MouseMotionListener
JdlViewObject
Actions:: An action event will be generated when a cell is selected. The associated command is the string "cell n" where 'n' is the cell number defined when the cell in question was set up.

3.4.6.3 Accessible Fields

The following accessible fields have been defined:

public final static int FREE: Location Constraint: free.
static final long serialVersionUID

3.4.6.4 Constructor

3.4.6.4.1 Introduction

A single constructor is available.

Constructor:

Standard constructor

3.4.6.4.2 Standard constructor

Constructs a JdlTextTable object with the required resources.

Constructor Definition:

public JdlTextTable (int rows, int cols, Font font, Font bold_font, boolean act, String msg, int ext_w, int ext_h, JdlViewOptions view_opts)

Parameters List:

rows: The required number of rows of characters.
cols: The required number of columns of characters.
font: The font to be used (ignored if using as a view object). A fixed width font is recommended as all character cells will be the same size.
bold_font: The bold font to be used (ignored if using as a view object) This should be roughly the same size as the normal font and, again, should be a fixed width font.
act: Display an active strip (ignored if not a View object). This will normally only be set to true if cells will be selected from the table at some stage.
msg: An initial message for the active strip (ignored if not a View object).
ext_w: Extra width for each character cell (to give more spacing).
ext_h: Extra height for each character cell (to give more spacing).
view_opts: Object to set non-default options for borders, active strip, colours and fonts.

3.4.6.5 Operational Methods

3.4.6.5.1 Introduction

This section contains methods to output text and symbols, to clear areas and to handle active cells.

Methods:

Output text - outputString
Output symbol - outputSymbol
Clear table - clearTable
Clear section - clearTableSection
Define active cell - defineCell
Remove active cell - removeCell
Set highlight handler - setHighlightHandler

3.4.6.5.2 Output text - outputString

This method outputs a text string to the window.

Method Definition:

public void outputString (String str, int row, int col, Color colour, boolean bold)

Parameters List:

str: The string to be output (only printable characters will be displayed).
row: The row number for the start character of the string.
col: The column number for the start character of the string.
colour: The colour for the text (if null, black will be selected).
bold: Bold =true for bold font, false for normal font.

3.4.6.5.3 Output symbol - outputSymbol

This method outputs a symbol to the window.

Method Definition:

public void outputSymbol (int symbol, int row, int col, Color colour, boolean rp)

Parameters List:

symbol: The number of the symbol to be output:
= 1, Open circle(within character)
= 2, Disk (within character)
= 3, Disk with black border (within character)
= 4, Open square (within character)
= 5, Filled square (within character)
= 6, Filled square with black border (within character)
= 7, Open square (full character width)
= 8, Filled square (full character width)
= 9, Filled square with black border (full character width)
= 10, Open rectangle (full character size)
= 11, Filled rectangle (full character size)
= 12, Filled rectangle with black border (full character size)
row: The row number for the start character of the string.
col: The column number for the start character of the string.
colour: The colour for the symbol.
rp: Repaint the window .Normally specify true. If false then the symbol will not be displayed unless a repaint is called because of some other event. However, if many symbols are to be output, then it will be much more efficient to set this flag to false for all but the last symbol being output; this will mean one repaint for the addition of all such symbols.

3.4.6.5.4 Clear table - clearTable

This method clears the text table (removes all stored characters and symbols).

Method Definition:: public void clearTable()
Parameters List:: none

3.4.6.5.5 Clear section - clearTableSection

This method clears a section of the text table (removes stored characters and symbols).

Method Definition:

public void clearTableSection(int row1, int col1, int row2, int col2)

Parameters List:

row1: Row number of top left corner of section to be cleared.
col1: Column number of top left corner of section to be cleared.
row2: Row number of bottom right corner of section to be cleared.
col2: Column number of bottom right corner of section to be cleared.

3.4.6.5.6 Define active cell - defineCell

This method defines an active cell which may be highlighted and selected as needed.

Method Definition:

public void defineCell(int numc, int row1, int col1, int row2, int col2, int highlight, int highlight_nosel, Color bg_colr, Color line_colr)

Parameters List:

numc: Cell number >0 (each cell defined must be given a unique number).
row1: Row number of top left corner of cell.
col1: Column number of top left corner of cell.
row2: Row number of bottom right corner of cell.
col2: Column number of bottom right corner of cell.
highlight: Highlight option (when in input selection mode):
= 1, coloured background
= 2, underline
= 3, surround box
highlight_nosel: Highlight option when not in input selection mode:
= 0, no-highlighting
= 1, coloured background
= 2, underline
= 3, surround box
bg_colr: The colour for cell background highlighting when used.
line_colr: The colour for a cell highlighting line/border when used.

3.4.6.5.7 Remove active cell - removeCell

This method removes an active cell (or all active cells).

Method Definition:

public void removeCell(int numc)

Parameters List:

numc: Cell number (0 = all cells).

3.4.6.5.8 Set highlight handler - setHighlightHandler

This method sets a highlight handler (only one can be set at a time). Its method will be called when an active cell is highlighted or un-highlighted.

Method Definition:

public void setHighlightHandler (JdlTextTableHighlightHandler handler)

Parameters List:

handler: The highlight handler object (null will remove existing handler if present).

3.4.6.6 Standard Positioning and Sizing

3.4.6.6.1 Introduction

This section contains the standard methods for positioning JdlView objects and getting the current minimum height and width values.

Methods:

Set position constraints - setLocationConstraints
Set minimum height - setMinimumHeight
Set minimum width - setMinimumWidth

3.4.6.6.2 Set position constraints - setLocationConstraints

Set constraints on the Jdl object positioning.

Method Definition:

public void setLocationConstraints (int constraint_x, int constraint_y)

Parameters List:

constraint_x: Constrain the Jdl Object 'x' position = the required Jdl Object 'x' position (overrides setLocation method) or FREE if the 'x' position may be set by the setLocation method and hence possibly by the layout manager.
constraint_y: Constrain the Jdl Object 'y' position = the required the Jdl Object 'y'position (overrides setLocation method) or FREE if the 'y' position may be set by the setLocation method and hence possibly by the layout manager.

3.4.6.6.3 Set minimum height - setMinimumHeight

Set the minimum height resource.

Method Definition:

public void setMinimumHeight(int minh)

Parameters List:

minh: The minimum height required for the object (ignored if less than that required by the minimum layout) (default = 0).

3.4.6.6.4 Set minimum width - setMinimumWidth

Set the minimum width resource.

Method Definition:

public void setMinimumWidth(int minw)

Parameters List:

minh: The minimum width required for the object (ignored if less than that required by the minimum layout) (default = 0).

3.4.6.7 Add/Remove Action Listener

3.4.6.7.1 Introduction

This section has methods to add or remove an action listener.

Methods:

Add action listener - addActionListener
Remove action listener - removeActionListener

3.4.6.7.2 Add action listener - addActionListener

This adds the specified action listener to receive action events from this object.

Method Definition:

public void addActionListener(ActionListener listener)

Parameters List:

listener: The action listener to be added.

3.4.6.7.3 Remove action listener - removeActionListener

This removes the specified action listener so that it no longer receives action events from this object.

Method Definition:

public void removeActionListener(ActionListener listener)

Parameters List:

listener: The action listener to be removed.

3.4.6.8 Get Returned Data

3.4.6.8.1 Introduction

This section has methods to get data from the object relating to an action and following that action.

Methods:

Get selected cell - getReturnedData

3.4.6.8.2 Get selected cell - getReturnedData

This method returns the last selected active cell number.

Method Definition:: public int getReturnedData()
Parameters List:: none
Method Return:: Returns the last selected active cell number.

3.4.6.9 Overriden Superclass Methods

3.4.6.9.1 Introduction

This section contains methods which override the corresponding superclass methods. These are basically standard for JdlView objects and comprise methods to set background and foreground colours and to get the minimum and preferred sizes for the object. (The paintComponent is also over-ridden but it is not normally called by the user).

Methods:

Set background - setBackground
Set foreground - setForeground
Get minimum size - getMinimumSize
Get preferred size - getPreferredSize