3.4.7 - Cell Window - JdlCellWindow

John W. Campbell

3.4.7.1 Introduction

This class provides a cell window area. This provides an area for the simple output of text from a program, particularly for tabular data. Scrollbars may be used. 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 cell window with cells defining areas of text which may be highlighted and, when required, selected using the mouse. As well as the main scrollable window, a fixed size overlay window is also defined enabling, for example, some fixed position buttons to be output in front of the scrolling area. The object also has an optional command line which will be positioned at the bottom of the area if present. This enables the output of a prompt and input of a reply. The basic definitions are in terms of character positions (row and column) with each character being one column wide and two rows high. The functions of this object basically include all those of the text table object but there is a difference in that the cell size used in the text table depends on the size of the fixed font used (and can therefore use a large character size if required) whereas the characters in the cell window object are always fitted into a cell which is eight pixels wide and sixteen pixels deep. The functions are also basically a subset of those available in the JdlGraphics object.

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.7.2 Class Details

Package:
Jdl.JdlView;
Class name:
JdlCellWindow
Class definition:
public class JdlCellWindow
Extends:
JdlDrawPanel
Implements:
MouseListener
MouseMotionListener
ActionListener
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. If a command line is present, an action will also be generated when a reply string is input; in this case, the associated command string will be the input reply.

3.4.7.3 Accessible Fields

The following accessible fields have been defined:

public final static int PREFERRED
Size Constraint: preferred size.
public final static int FREE
Size/Location Constraint: free.
static final long serialVersionUID

3.4.7.4 Constructor

3.4.7.4.1 Introduction

A single constructor is available.

Constructor:

Standard constructor

3.4.7.4.2 Standard constructor

Constructs a JdlCellWindow object with the required resources.

Constructor Definition:
public JdlCellWindow (int rows, int cols, int rows_d, int cols_d, boolean cline, boolean fix_sz, JdlViewOptions view_opts)
Parameters List:
rows
The start no. of rows in the scrollable window area.
cols
The start no. of columns in the scrollable window area.
rows_d
The required number of rows of cells in displayed area if 0 set to cols; if both this & cols_d = 0 then no scrollbars will be displayed and no size increase will be allowed.
cols_d
The required number of columns of cells in displayed area if 0 set to cols; if both this & rows_d = 0 then no scrollbars will be displayed and no size increase will be allowed.
cline
Output a command line if true, otherwise do not.
fix_sz
If true, fix the size of the text output area; if false, allow the area to expand if the window is expanded when the layout is calculated.
view_opts
Object to set non-default options for borders, active strip, colours and fonts.

3.4.7.5 Operational Methods

3.4.7.5.1 Introduction

This section details the methods used in conjunction with the main functions of the window including, output of text and symbols, output of cell images, defining cells, repositioning the view and handling the command line.

Methods:

Output text string - outputString
Output text string - outputString
Output command line prompt - outputPrompt
Clear command line - clearLine
Output symbol - outputSymbol
Output symbol - outputSymbol
Output cell image - outputCellImage
Output cell image - outputCellImage
General icon/button - outputIconButton
Change icon image - changeIconImage
Clear window - clearWindow
Clear window section - clearWindowSection
Define active cell - defineCell
Remove active cell - removeCell
Reposition visible area - repositionView
Shift visible area - shiftView
Add rows/columns - addRowsColumns
Set highlight handler - setHighlightHandler
Add a cell image - addCellImage

3.4.7.5.2 Output text string - outputString

Output a text string to the window (standard version).

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 (up to second last row only because of two cell height).
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.7.5.3 Output text string - outputString

Output a text string to the window (full version).

Method Definition:
public void outputString (String str, int row, int col, Color colour, boolean bold, boolean act, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, int numc, boolean ovly)
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 (up to second last row only because of two cell height).
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.
act
Treat as a set of active cells if true.
highlight
Highlight option (when in input selection mode).
= 0, no-highlighting
= 1, coloured background
= 2, underline
= 3, surround box
= 4, embolden text
highlight_nosel
Highlight option when not in input selection mode - options as for 'highlight'.
hl_colr
The colour for cell background highlighting when used.
line_colr
The colour for a cell highlighting line/border when used.
numc
Active cell number (unique user defined no. > 0 (see defineCell method)) but may be zero if each cell is to be treated separately.
ovly
Set to true for output to overlay window, false for normal scroll window output.

3.4.7.5.4 Output command line prompt - outputPrompt

This method outputs a text string prompt to the command line window and awaits reply.

Method Definition:
public void outputPrompt (String str)
Parameters List:
str
The prompt string to be output.

3.4.7.5.5 Clear command line - clearLine

This method clears the command line.

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

3.4.7.5.6 Output symbol - outputSymbol

Output a symbol to the window (standard version)

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 symbol (up to second last row only because of two cell height).
col
The column number for the symbol.
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.7.5.7 Output symbol - outputSymbol

Output a symbol to the window (full version).

Method Definition:
public void outputSymbol (int symbol, int row, int col, Color colour, boolean rp, boolean act, Color hl_colr, boolean ovly)
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 symbol (up to second last row only because of two cell height).
col
The column number for the symbol.
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.
act
Treat as an active cell if true (background highlighting only).
hl_colr
The colour for highlighting if required.
ovly
Set to true for output to the overlay window, false for output to the normal scroll window

3.4.7.5.8 Output cell image - outputCellImage

This method outputs a cell image (standard version). The image is defined using the addCellImage(..) method.

Method Definition:
public void outputCellImage (String name, int row, int col, boolean rp)
Parameters List:
name
The cell image name as defined when added via addCellImage(..).
row
The cell row number.
col
The cell column number.
rp
Repaint flag (cf outputSymbol method).

3.4.7.5.9 Output cell image - outputCellImage

This method outputs a cell image (full version). The image is defined using the addCellImage(..) method.

Method Definition:
public void outputCellImage (String name, int row, int col, boolean rp, boolean act, Color hl_colr, boolean ovly)
Parameters List:
name
The cell image name as defined when added via addCellImage(..).
row
The cell row number.
col
The cell column number.
rp
Repaint flag (cf outputSymbol method).
act
Treat as a set of active cells if true.
hl_colr
Colour for highlighting.
ovly
Set to true for output to the overlay window, false for output to the normal scroll window.

3.4.7.5.10 General icon/button - outputIconButton

This method outputs a general purpose opaque icon/button object on the window. When such a button is output the order of drawing on the button is: Image, Text, border, highlight rectangle.

Method Definition:
public void outputIconButton (boolean button, int row, int col, int nr, int nc, Image img, String str, int ir, int ic, Color colr, int brdr_out, int brdr_in, boolean std_hl, int numc, Color solid_brdr, int bw, Color hl_line_colr, boolean ovly)
Parameters List:
button
True if a press button, false if an icon with on/off states.
row
Row number of top left cell of the icon/button.
col
Column number of top left cell of the icon/button.
nr
The number of cell rows (height) for the icon/button.
nc
The number of cell columns (width) for the icon/button.
img
Image to draw on the icon/button when icon/button. state - may be null.
str
Text string to be drawn on the icon/button if required - may be null. Only one of img/str can be used (if both are specified then the image will be ignored).
ir
Row no. within icon/button for start of text (max nrows-1) (normally 2 for a button).
ic
Column no. within icon/button for start of text (normally 2 for a button unless centered text is required).
colr
Text colour.
brdr_out
Border type for icon/button in out/off state (colours based on background colour - see setBackground(..)). Will be drawn after image and after any text.
brdr_in
Border type for icon/button in in/on state (colours based on background colour - see setBackground(..)). Will be drawn after image and after any text.
std_hl
Standard highlighting flag for an icon/button. If true highlight using bold text if a text string was defined or using a surrounding rectangle in colour 'hl_line_colr' if not. If false, no automatic highlighting is done. Note the icon/button method defines an active cell internally and the highlight on/off handler will be called.
numc
A unique user selected cell number used to identify the icon/button.
solid_brdr
Colour for a solid border if required (Black if null).
bw
Border width in pixels (>0).
hl_line_colr
Line colour for the highlighting rectangle if required.
ovly
Set to true for output to the overlay window, false for output to the normal scroll window.

3.4.7.5.11 Change icon image - changeIconImage

This medod changes the image for an icon/button.

Method Definition:
public void changeIconImage (int numc, Image img)
Parameters List:
numc
The cell number associated with the icon/button.
img
The new image.

3.4.7.5.12 Clear window - clearWindow

This method clears the cell window object (removes all stored characters and symbols).

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

3.4.7.5.13 Clear window section - clearWindowSection

This method clears a section of the cell window (removes stored characters and symbols).

Method Definition:
public void clearWindowSection(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.7.5.14 Define active cell - defineCell

This method defines an active cell which may be used, for example, to select items from the window. The cell covers a rectangular area.

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, boolean ovly)
Parameters List:
numc
A user defined 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).
= 0, no-highlighting
= 1, coloured background
= 2, underline
= 3, surround box
= 4, embolden text
highlight_nosel
Highlight option when not in input selection mode - options as for 'highlight'.
bg_colr
The colour for cell background highlighting when used.
line_colr
The colour for a cell highlighting line/border when used.
ovly
Set to true for cell on overlay window, false for cell on normal scroll window.

3.4.7.5.15 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 for active cell to be removed (0 = all active cells).

3.4.7.5.16 Reposition visible area - repositionView

This method repositions the visible area of the scroll window (absolute cell position).

Method Definition:
public void repositionView (int orig_row, int orig_col)
Parameters List:
orig_row
New origin cell row number (from 1 up).
orig_col
New origin cell column number (from 1 up).

3.4.7.5.17 Shift visible area - shiftView

This method shifts the visible area of the scroll window (cells offset).

Method Definition:
public void shiftView (int off_row, int off_col)
Parameters List:
off_row
Row offset (may be +ve or -ve, limits will be checked).
off_col
Column offset (may be +ve or -ve, limits will be checked).

3.4.7.5.18 Add rows/columns - addRowsColumns

This method adds more rows and/or columns of cells to the scroll window.

Method Definition:
public void addRowsColumns (int rows, int cols)
Parameters List:
rows
The number of rows of cells to be added (may be 0).
cols
The number of columns of cells to be added (may be 0).

3.4.7.5.19 Set highlight handler - setHighlightHandler

Set a highlight handler (only one can be set at a time). The highlight handler's processHighlight(..) method will be called when a cell (or icon/button) is highlighted.

Method Definition:
public void setHighlightHandler (JdlCellWindowHighlightHandler handler)
Parameters List:
handler
The highlight handler object (null will remove an existing handler if one is present).

3.4.7.5.20 Add a cell image - addCellImage

This method adds a cell image to the internal list of images. These may then be used by the outputCellImage(..) methods to display an image.

Method Definition:
public void addCellImage (String name, Image img)
Parameters List:
name
The name for the cell image (must be unique).
img
The cell image.

3.4.7.6 Standard Positioning and Sizing

3.4.7.6.1 Introduction

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

Methods:

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

3.4.7.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.7.6.3 Set size constraints - setSizeConstraints

Set constraints on the Jdl Object resizing permitted.

Method Definition:
public void setSizeConstraints (int constraint_w, int constraint_h)
Parameters List:
constraint_w
Constrain the Jdl Object width = the required Jdl Object width, or PREFERRED (default) if the width is to be calculated from the current resources, or FREE if the width may be resized to anything greater than the minimum width required.
constraint_h
Constrain the Jdl Object height = the required Jdl Object height, or PREFERRED (default) if the height is to be calculated from the current resources, or FREE if the height may be resized to anything greater than the minimum height required.

3.4.7.6.4 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.7.6.5 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.7.7 Add/Remove Action Listener

3.4.7.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.7.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.7.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.7.8 Get Returned Data

3.4.7.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.7.8.2 Get selected cell - getReturnedData

This method returns the last selected cell number.

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

3.4.7.9 Overriden Superclass Methods

3.4.7.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 and setSize methods are also over-ridden but they are not normally called by the user).

Methods:

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

3.4.7.9.2 Set background - setBackground

This method sets the background colour resource.

Method Definition:
public void setBackground (Color c)
Parameters List:
c
The color to become this object's background color.

3.4.7.9.3 Set background colours - setBackground

This method sets the background colour resource and brighter and darker shades of that colour (e.g. for 3-D frames).

Method Definition:
public void setBackground (Color c, Color brighter, Color darker)
Parameters List:
c
The background colour.
brighter
A brighter shade of the background colour.
darker
A darker shade of the background colour.

3.4.7.9.4 Set foreground - setForeground

This method sets the foreground colour resource.

Method Definition:
public void setForeground (Color c)
Parameters List:
c
The color to become this object's foreground color.

3.4.7.9.5 Get minimum size - getMinimumSize

This method returns the minimum size of the component.

Method Definition:
public Dimension getMinimumSize()
Parameters List:
none

3.4.7.9.6 Get preferred size - getPreferredSize

This method returns the preferred size of the component.

Method Definition:
public Dimension getPreferredSize()
Parameters List:
none

⇑ Up 3   ⇑ Up 2   ⇑ Up 1   ⇑ Top of this