3.4.8 - Graphics Window - JdlGraphicsWindow

John W. Campbell

3.4.8.1 Introduction

This class provides a graphics window area. It incorporates the functions of the JdlCellWindow object but in addition it has methods for drawing graphics (lines/circles etc.) and simple graph axes. It also provides for the simple output of text from a program, particularly for tabular data. 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 cells defining areas which may be highlighted and, when required, selected using the mouse. The main window is scrollable and, 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 may be positioned at either the top or the bottom of the area. This enables the output of a prompt and input of a reply. A print button may also be displayed so that the window contents may be printed as required. For text output, the basic definitions are in terms of cell positions (row and column) with each character being one column wide and two rows high. The cells are 8x8 pixels in size. For graphics a user coordinate space can be mapped onto the window.

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Command Line Methods
Graphics Commands
Cell Based Output
Clear/Delete Objects
Scroll Area Positioning
Graph Axes
Set Handler Objects
Keyboard/Mouse Input
Standard Positioning and Sizing
Add/Remove Action Listener
Get Returned Data
Overriden Superclass Methods

3.4.8.2 Class Details

Package:: Jdl.JdlView;
Class name:: JdlGraphicsWindow
Class definition:: public class JdlGraphicsWindow
Extends:: JdlDrawPanel
Implements:: MouseListener

MouseMotionListener
ActionListener
JdlViewObject

FocusListener
KeyListener
JdlButtonDrawer
Printable
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.

Actions will also be generated for single or double mouse clicks outside active cells or for mouse movements if this option is enabled (see the enableMotionActions(..) method). The action commands will be "single_click", "double_click" and "mouse_moved" respectively.

If the option is enabled (see the enableGraphicsKeyinp(..) method) from the keyboard will also generate actions when the graphics area has the keyboard focus. For a general character the action command string wil; be "typed_character". For special characters, the following action commands will be returned: "enter", "cursor_up", "cursor_down", "cursor_left", "cursor_right", "escape", "delete" or "insert" (Backspace characters also return the action command string "delete").

The type of action may be identified by calling the getReturnedData(..) method when an action has been performed. This returns a code identifying the action type.

3.4.8.3 Accessible Fields

The following accessible fields have been defined:

public final static int FULL_SIZE_INITIAL: Mapping type: Based on full initial size.
public final static int FULL_SIZE: Mapping type: Based on current full size.
public final static int UNIT_SQUARE_INITIAL: Mapping type: Based on initial size unit square.
public final static int UNIT_SQUARE: Mapping type: Based on current size unit square.
public final static int SINGLE_POINT: Symbol type: single pixel point.
public final static int POINT: Symbol type: Point (sized).
public final static int VERTICAL_CROSS: Symbol type: Vertical cross.
public final static int DIAGONAL_CROSS: Symbol type: Diagonal cross.
public final static int SQUARE: Symbol type: Square.
public final static int DIAMOND: Symbol type: Diamond.
public final static int HORIZONTAL: Graph axis orientation: horizontal.
public final static int VERTICAL: Graph axis orientation: vertical.
public final static int BUTTON1_SINGLE
public final static int BUTTON2_SINGLE
public final static int BUTTON3_SINGLE
public final static int BUTTON1_DOUBLE
public final static int BUTTON2_DOUBLE
public final static int BUTTON3_DOUBLE
public final static int MOUSE_MOTION
public final static int ENTER_KEY
public final static int ESCAPE_KEY
public final static int DELETE_KEY
public final static int BACKSPACE_KEY
public final static int INSERT_KEY
public final static int TYPED_KEY
public final static int CURSOR_UP
public final static int CURSOR_DOWN
public final static int CURSOR_LEFT
public final static int CURSOR_RIGHT
public final static int CELL_SELECTED
public final static int COMMANDLINE_INPUT: Action codes from mouse/keyboard/other input
public final static int PREFERRED: Size Constraint: preferred size.
public final static int FREE: Size/Location Constraint: free.
static final long serialVersionUID

3.4.8.4 Constructor

3.4.8.4.1 Introduction

A single constructor is available.

Constructor:

Standard constructor

3.4.8.4.2 Standard constructor

Constructs a JdlCellWindow object with the required resources.

Constructor Definition:

public JdlGraphicsWindow (int nxpix, int nypix, int nxpix_d, int nypix_d, boolean cline, boolean pbut, boolean top, boolean fix_sz, JdlViewOptions view_opts)

Parameters List:

nxpix: The start no. of 'x' pixels in the scrollable window area (horizontal).
nypix: The start no. of 'y' pixels in the scrollable window area (vertical).
nxpix_d: The required number of 'x' pixels in displayed area if 0 set to nxpix; if both this & next 0 then no scrollbars.
nypix_d: The required number of 'y' pixels in displayed area if 0 set to nypix; if both this & previous 0 then no scrollbars and no size increase allowed.
cline: Output a command line if true, otherwise do not.
pbut: Output print button if true, otherwise do not.
top: If command line and/or print button are present, output them at the top of the graphics window if true; otherwise they will output at the bottom.
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.8.5 Command Line Methods

3.4.8.5.1 Introduction

This section has methods to initiate a command line prompt/reply sequence and to clear the command line.

Methods:

Output prompt - outputPrompt
Clear command line - clearLine

3.4.8.5.2 Output prompt - outputPrompt

Output a text string prompt to the command line window and await reply.

Method Definition:

public void outputPrompt (String str)

Parameters List:

str: The prompt string to be output.

3.4.8.5.3 Clear command line - clearLine

This method clears the command line.

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

3.4.8.6 Graphics Commands

3.4.8.6.1 Introduction

This section has methods to define the coordinate mapping for graphics and to output graphics lines, rectangles, circles etc. Where appropriate, the shapes may be filled if required. Text and symbol strings may be output and active cell areas defined, all based on user coordinates.

Methods:

Set coordinate mapping - setMapping
Draw line - drawLine
Draw poly-line - drawPolyLine
Draw rectangle - drawRectangle
Draw polygon - drawPolygon
Draw arc - drawArc
Draw text - drawString
Draw symbol - drawSymbol
Draw symbol string - drawPolySymbol
Define active area - defineActiveArea
Block repaint - blockRepaint

3.4.8.6.2 Set coordinate mapping - setMapping

This method sets the mapping between coordinate space and display space.

Method Definition:

public void setMapping (double x_left, double x_right, double y_top, double y_bottom, double dx_min, double dx_max, double dy_min, double dy_max, int type, boolean rsz)

Parameters List:

type: The required mapping type code:
= 0, 0.0 to 1.0 in the displayed 'x' and the displayed 'y' represent the full size of the graphics window when the graphics window object was created. (FULL_SIZE_INITIAL)

= 1, 0.0 to 1.0 in the displayed 'x' and the displayed 'y' represent the current full size of the graphics window (FULL_SIZE)

= 2, 0.0 to 1.0 in the displayed 'x' and the displayed 'y' represent the unit square of the requested graphics window size when the graphics window object was created. (UNIT_SQUARE_INITIAL)

= 3, 0.0 to 1.0 in the displayed 'x' and the displayed 'y' represent the unit square of the requested graphics window based on the current size. (UNIT_SQUARE)
rsz: If true then the graphics will be re-scaled if the size of the graphics window is changed; note, for type 1 the aspect ratio will be preserved whereas for type 0 it will not, in general, be preserved.

3.4.8.6.3 Draw line - drawLine

This method draws a line using the current mapping.

Method Definition:

public void drawLine (double x_start, double y_start, double x_end, double y_end, Color colr, int id, boolean ovly)

Parameters List:

x_start: The start 'x' coordinate of the line in user coordinates.
y_start: The start 'y' coordinate of the line in user coordinates.
x_end: The end 'x' coordinate of the line in user coordinates.
y_end: The end 'y' coordinate of the line in user coordinates.
colr: The line colour.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.4 Draw poly-line - drawPolyLine

This method draws a poly-line using the current mapping.

Method Definition:

public void drawPolyLine (int np, double[] x, double[] y, Color colr, int id, boolean ovly)

Parameters List:

np: Number of points including end points (minimum of 2).
x: An array of the 'x' coordinates of the line in user coordinates.
y: An array of the 'y' coordinates of the line in user coordinates.
colr: The line colour.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.5 Draw rectangle - drawRectangle

This method draws a rectangle using the current mapping (May be filled).

Method Definition:

public void drawRectangle (double x_start, double y_start, double x_end, double y_end, Color colr, Color fill, int id, boolean ovly)

Parameters List:

x_start: The start 'x' coordinate of the rectangle in user coordinates.
y_start: The start 'y' coordinate of the rectangle in user coordinates.
x_end: The opposite corner 'x' coordinate in user coordinates.
y_end: The opposite corner 'y' coordinate in user coordinates.
colr: The line colour (null if no outline required).
fill: The fill colour (null if no fill required).
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.6 Draw polygon - drawPolygon

This method draws a polygon using the current mapping (may be filled).

Method Definition:

public void drawPolygon (int np, double[] x, double[] y, Color colr, Color fill, int id, boolean ovly)

Parameters List:

np: Number of points including end points (minimum of 3). The final point will be joined to the first point.
x: An array of the 'x' coordinates of the polygon in user coordinates.
y: An array of the 'y' coordinates of the polygon in user coordinates.
colr: The line colour (may be null if no outline required).
fill: The fill colour (null if no fill required).
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.7 Draw arc - drawArc

This method draws an arc using the current mapping (May be filled).

Method Definition:

public void drawArc (double x_cen, double y_cen, double x_r, double y_r, double ang_start, double ang_extent, int closure, Color colr, Color fill, int id, boolean ovly)

Parameters List:

x_cen: The centre 'x' coordinate of the arc in user coordinates.
y_cen: The centre 'y' coordinate of the arc in user coordinates.
x_r: The 'x' semi-axis in user coordinates (i.e. radius for circle, or ellipse 'a').
y_r: The 'y' semi-axis in user coordinates (i.e. radius for circle, or ellipse 'b').
ang_start: Start angle of arc in degrees (+ve is anti-clockwise, starting from 0 at 3 o'clock).
ang_extent: Angle extent of arc in degrees (+ve is anti-clockwise.)
closure: Closure type Arc2D.OPEN, Arc2D.CHORD or Arc2D.PIE.
colr: The line colour (null if no outline required).
fill: The fill colour (null if no fill required).
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.8 Draw text - drawString

This method outputs a text string object to the window using the current mapping.

Method Definition:

public void drawString (String str, double x, double y, int font_opt, double font_h, Color colr, double orient, int id, boolean ovly)

Parameters List:

str: The string to be output.
x: The 'x' position for the start character of the string (top left corner prior to any rotation) in user coordinates.
y: The 'y' position for the start character of the string. (top left corner prior to any rotation) in user coordinates.
font_opt: The font option =1,2,3 Serif plain, bold, italic; =4,5,6 SansSerif plain, bold, italic; =7,8,9 Monospaced plain, bold, italic.
font_h: The character height in normalised unit square units.
colr: The text colour.
orient: Rotate text around x,y corner by 'orient' degrees. The text string is rotated clockwise by this angle.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.9 Draw symbol - drawSymbol

This method outputs a symbol to the window using the current mapping.

Method Definition:

public void drawSymbol (int symb, double x, double y, double h, Color colr, int id, boolean ovly)

Parameters List:

symb: The symbol type:
= 0, point (single pixel) (SINGLE_POINT)
= 1, variable sized point (POINT)
= 2, vertical cross (VERTICAL_CROSS)
= 3, diagonal cross (DIAGONAL_CROSS)
= 4, square (SQUARE)
= 5, diamond (DIAMOND)
x: The 'x' position for symbol centre in user coordinates.
y: The 'y' position for symbol centre in user coordinates.
h: The symbol height in normalised unit square units.
colr: The symbol colour.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.10 Draw symbol string - drawPolySymbol

This method outputs a string of symbols to the window using the current mapping.

Method Definition:

public void drawPolySymbol (int nsymb, int symb, double[] x, double[] y, double h, Color colr, int id, boolean ovly)

Parameters List:

nsymb: The number of symbols to be output.
symb: The symbol type:
= 0, point (single pixel) (SINGLE_POINT)
= 1, variable sized point (POINT)
= 2, vertical cross (VERTICAL_CROSS)
= 3, diagonal cross (DIAGONAL_CROSS)
= 4, square (SQUARE)
= 5, diamond (DIAMOND)
x: The 'x' positions for symbol centres in user coordinates.
y: The 'y' positions for symbol centres in user coordinates.
h: The symbol height (in normalised unit square units).
colr: The symbol colour.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: True if output to overlay window, false if output to main scroll window.

3.4.8.6.11 Define active area - defineActiveArea

This method defines an active area in user coordinate space.

Method Definition:

public void defineActiveArea(int numc, double xmin, double ymin, double xmax, double ymax, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, boolean ovly)

Parameters List:

numc: Active area (active cell) number >0 (each area/cell defined must be given a unique number).
xmin: 'x' coordinate of top left corner of cell in user coordinates.
ymin: 'y' coordinate of top left corner of cell in user coordinates.
xmax: 'x' coordinate of bottom right corner of cell in user coordinates.
ymax: 'y' coordinate of bottom right corner of cell in user coordinates.
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.
ovly: Set to true for cell on overlay window, false for cell on normal scroll window.

3.4.8.6.12 Block repaint - blockRepaint

If many graphics objects are to be added in succession, then this method may be called to block the repaint requests which are normally generated when each object is added. It is IMPORTANT to reset the repaint option after the items have been added so that normal processing can continue.

Method Definition:

public void blockRepaint(boolean block)

Parameters List:

block: If true then block the repaints, if false then return to normal processing.

3.4.8.7 Cell Based Output

3.4.8.7.1 Introduction

This section has a series of methods for outputting text, symbols, buttons, icons and cell based images and defining active cells based on cell positions within the output window. Each cell is 8x8 pixels in size. Text characters are one cell wide and two cells high.

Methods:

Output cell text - outputCellText
Output cell text - outputCellText
Output cell symbol - outputCellSymbol
Output cell symbol - outputCellSymbol
Add cell image - addCellImage
Output cell image. - outputCellImage
Output cell image. - outputCellImage
General icon/button - outputIconButton
Change icon image - changeIconImage
Define an active cell - defineActiveCell

3.4.8.7.2 Output cell text - outputCellText

This method outputs a 'cell text' string to the window (standard version).

Method Definition:

public void outputCellText (String str, int col, int row, boolean bold, Color colr, boolean opaque, int id, boolean ovly)

Parameters List:

str: The string to be output.
col: The cell column number for the start character of the string.
row: The cell row number for the start character of the string. (Note: each character is TWO cells high).
bold: Bold =true for bold font, false for normal font.
colr: The text colour.
opaque: If true output character on an opaque background 1 cell wide by 2 cells deep in background colour; if false no opaque background added.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for main scroll window.

3.4.8.7.3 Output cell text - outputCellText

This method outputs a 'cell text' string to the window (full version).

Method Definition:

public void outputCellText (String str, int col, int row, boolean bold, Color colr, boolean act, int numc, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, boolean opaque, int id, boolean ovly)

Parameters List:

str: The string to be output.
col: The start cell column number for the string.
row: The cell row number for the top cells of the characters (Note: each character is TWO cells high).
bold: If true use Bold text, otherwise Plain text.
colr: The text colour.
act: Treat as a set of active cells if true.
numc: Active cell number (unique user defined no. > 0 (see defineCell method) - ignored if not an active 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'.
hl_colr: The colour for cell background highlighting when used.
line_colr: The colour for a cell highlighting line/border when used.
opaque: If true output character on an opaque background 1 cell wide by 2 cells deep in background colour; if false no opaque background added.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for main scroll window.

3.4.8.7.4 Output cell symbol - outputCellSymbol

This method outputs a 'cell' symbol character using (standard version).

Method Definition:

public void outputCellSymbol (int symbol, int col, int row, Color colr, boolean opaque, int id, boolean ovly)

Parameters List:

symbol: The number of the symbol to be output.
col: The column number for the symbol.
row: The row number for the symbol (Note: each symbol character is TWO cells high).
colr: The symbol colour.
opaque: If true output character on an opaque background 1 cell wide by 2 cells deep in background colour; if false no opaque background added.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for main scroll window.

3.4.8.7.5 Output cell symbol - outputCellSymbol

Output a 'cell' symbol character to the window (full version).

Method Definition:

public void outputCellSymbol (int symbol, int col, int row, Color colr, boolean act, int numc, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, boolean opaque, int id, boolean ovly)

Parameters List:

symbol: The number of the symbol to be output.
col: The column number for the symbol
row: The row number for the symbol
colr: The symbol colour
act: Treat as an active cell if true (background highlighting only).
numc: Active cell number (unique user defined no. > 0 (see defineCell method) - ignored if not an active 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'.
hl_colr: The colour for cell background highlighting when used.
line_colr: The colour for a cell highlighting line/border when used.
opaque: If true output character on an opaque background 1 cell wide by 2 cells deep in background colour; if false no opaque background added.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window

3.4.8.7.6 Add cell image - addCellImage

Add a cell image to the internal list of images.

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.8.7.7 Output cell image. - outputCellImage

This method outputs a single cell image (standard version).

Method Definition:

public void outputCellImage (String name, int col, int row, int id, boolean ovly)

Parameters List:

name: The cell image name (as defined when added via addCellImage(..).
col: The cell column number.
row: The cell row number.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.

3.4.8.7.8 Output cell image. - outputCellImage

This method outputs a single cell image (full version).

Method Definition:

public void outputCellImage (String name, int col, int row, boolean act, int numc, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, int id, boolean ovly)

Parameters List:

name: The cell image name (as defined when added via addCellImage(..).
col: The cell column number.
row: The cell row number.
act: Treat as a set of active cells if true.
numc: Active cell number (unique user defined no. > 0 (see defineCell method) - ignored if not an active 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'.
hl_colr: The colour for cell background highlighting when used.
line_colr: The colour for a cell highlighting line/border when used.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.

3.4.8.7.9 General icon/button - outputIconButton

This method outputs a general purpose opaque icon/button oobject 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 col, int row, int nc, int nr, Image img, String str, int ic, int ir, Color colr, int brdr_out, int brdr_in, boolean std_hl, int numc, Color solid_brdr, int bw, Color hl_line_colr, int id, boolean ovly)

Parameters List:

button: True if a press button, false if an icon with on/off states.
col: Column number of top left cell of the icon/button.
row: Row number of top left cell of the icon/button.
nc: The number of cell columns (width) for the icon/button.
nr: The number of cell rows (height) 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).
ic: Column no. within icon/button for start of text (normally 2 for a button unless centered text is required).
ir: Row no. within icon/button for start of text (max nrows-1) (normally 2 for a button).
colr: String 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 (>0)
hl_line_colr: Line colour for highlighting rectangle if required.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.

3.4.8.7.10 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.8.7.11 Define an active cell - defineActiveCell

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 defineActiveCell(int numc, int xpix1, int ypix1, int xpix2, int ypix2, int highlight, int highlight_nosel, Color hl_colr, Color line_colr, boolean ovly)

Parameters List:

numc: Cell number >0 (each cell defined must be given a unique number).
xpix1: Pixel 'x' offset of top left corner of cell.
ypix1: Pixel 'y' offset of top left corner of cell.
xpix2: Pixel 'x' offset of bottom right corner of cell.
ypix2: Pixel 'y' offset 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'.
hl_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.8.8 Clear/Delete Objects

3.4.8.8.1 Introduction

This section has methods to clear and delete selected windows and graphics objects.

Methods:

Clear windows - clearWindow
Clear main window - clearMainWindow
Clear overlay window. - clearOverlayWindow
Remove graphics objects - removeGraphicsObject
Remove active cell - removeCell

3.4.8.8.2 Clear windows - clearWindow

This method clears the graphics windows (main and overlay). All active cells will also be removed.

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

3.4.8.8.3 Clear main window - clearMainWindow

This method clears the main graphics window.

Method Definition:

public void clearMainWindow(boolean cl)

Parameters List:

cl: If true remove the active cell definitions for the main window as well as the displayed items, otherwise leave the active cell definitions in place.

3.4.8.8.4 Clear overlay window. - clearOverlayWindow

This method clears the overlay graphics window.

Method Definition:

public void clearOverlayWindow(boolean cl)

Parameters List:

cl: If true remove the active cell definitions for the overlay window as well as the displayed items, otherwise leave the active cell definitions in place.

3.4.8.8.5 Remove graphics objects - removeGraphicsObject

This method removes (deletes) a graphics object (or group of objects). The object(s) are removed from the stored objects list as well as being removed from the display.

Method Definition:

public void removeGraphicsObject(int id)

Parameters List:

id: The user defined id for the object (or group of objects).

3.4.8.8.6 Remove active cell - removeCell

This method removes (deletes) an active cell which was created using the defineCell(..) method. (All other active cells defined indirectly are removed via their object id's e.g. for a button/icon).

Method Definition:

public void removeCell(int numc)

Parameters List:

numc: cell number.

3.4.8.9 Scroll Area Positioning

3.4.8.9.1 Introduction

This section has methods relating to ther positioning of the visible area of the scrolled window.

Methods:

Get 'x' origin - getScrollOriginX
Get 'y' origin - getScrollOriginY
Reposition visible area - repositionView
Reposition visible area - repositionCellView
Add rows/columns - addColumnsRows
Increase window size - increaseGraphicsWindow

3.4.8.9.2 Get 'x' origin - getScrollOriginX

Get current origin 'x' position in scroll area.

Method Definition:: public int getScrollOriginX()
Parameters List:: none
Method Return:: The origin 'x' absolute pixel offset position.

3.4.8.9.3 Get 'y' origin - getScrollOriginY

Get current origin 'y' position in scroll area.

Method Definition:: public int getScrollOriginY()
Parameters List:: none
Method Return:: The origin 'y' absolute pixel offset position.

3.4.8.9.4 Reposition visible area - repositionView

This method repositions the visible area (absolute pixel offset position).

Method Definition:

public void repositionView (int orig_xpix, int orig_ypix)

Parameters List:

orig_xpix: New origin 'x' pixel offset (from 0 up).
orig_ypix: New origin 'y' pixel offset (from 0 up).

3.4.8.9.5 Reposition visible area - repositionCellView

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

Method Definition:

public void repositionCellView (int orig_col, int orig_row)

Parameters List:

orig_col: New origin cell column number (from 1 up).
orig_row: New origin cell row number (from 1 up).

3.4.8.9.6 Add rows/columns - addColumnsRows

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

Method Definition:

public void addColumnsRows (int cols, int rows)

Parameters List:

cols: The number of columns of cells to be added (may be 0).
rows: The number of rows of cells to be added (may be 0).

3.4.8.9.7 Increase window size - increaseGraphicsWindow

This method increases the scrollable graphics window area size.

Method Definition:

public void increaseGraphicsWindow (int nx, int ny)

Parameters List:

nx: The number of 'x' pixels to be added (may be 0)
ny: The number of 'y' pixels to be added (may be 0)

3.4.8.10 Graph Axes

3.4.8.10.1 Introduction

This section has methods to draw annotated axes for graphs.

Methods:

Draw simple graph axis - drawGraphAxis
Draw simple graph axis - drawGraphAxis
Draw simple graph axis - drawGraphAxis
Draw graph axis - drawGraphAxis

3.4.8.10.2 Draw simple graph axis - drawGraphAxis

Draw an annotated graphics axis (Simplified version - internally generated axis tick mark labels based on required no. of divisions and default settings for other parameters).

Method Definition:

public void drawGraphAxis (int orient, double x_orig, double y_orig, double axis_len, String title, int ndiv, int nd, int id, boolean ovly)

Parameters List:

orient: Orientation =0 horizontal, =1 vertical (HORIZONTAL, VERTICAL).
x_orig: The 'x' origin for the axis in user coordinates.
y_orig: The 'y' origin for the axis in user coordinates.
axis_len: The axis length in user coordinate space ('x' if horizontal, 'y' if vertical axis).
title: Axis title (may be null if not required).
ndiv: No. of divisions for labels annotation.
nd: No. of decimal places for axis value labels.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.
Note: The position & scaling may should be set via a call to setMapping(..).

3.4.8.10.3 Draw simple graph axis - drawGraphAxis

Draw an annotated graphics axis (Simplified version - internally generated axis tick mark labels based on axis division and default settings for other parameters).

Method Definition:

public void drawGraphAxis (int orient, double x_orig, double y_orig, double axis_len, String title, double axis_div, int nd, int id, boolean ovly)

Parameters List:

orient: Orientation =0 horizontal, =1 vertical (HORIZONTAL, VERTICAL).
x_orig: The 'x' origin for the axis in user coordinates.
y_orig: The 'y' origin for the axis in user coordinates.
axis_len: The axis length in user coordinate space ('x' if horizontal, 'y' if vertical axis).
title: Axis title (may be null if not required).
axis_div: Division length along axis for tick marks in user coordinate space. (If axis_div==0.0 then the axis division will be calculated from the axis length and number of divisions).
nd: No. of decimal places for axis value labels.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.
Note: The position & scaling may should be set via a call to setMapping(..).

3.4.8.10.4 Draw simple graph axis - drawGraphAxis

Draw an annotated graphics axis (Simplified version - use supplied axis tick mark labels and default settings for other parameters).

Method Definition:

public void drawGraphAxis (int orient, double x_orig, double y_orig, double axis_len, String title, int ndiv, String[] labels, double axis_div, int id, boolean ovly)

Parameters List:

orient: Orientation =0 horizontal, =1 vertical (HORIZONTAL, VERTICAL).
x_orig: The 'x' origin for the axis in user coordinates.
y_orig: The 'y' origin for the axis in user coordinates.
axis_len: The axis length in user coordinate space ('x' if horizontal, 'y' if vertical axis).
title: Axis title (may be null if not required).
ndiv: No. of divisions for labels annotation.
labels: List of annotation labels for the tick marks (ndiv+1) values. May be null if labels are to be generated internally. Note: May contain the character ^ prior to a power value at the end of a labels string e.g. 3.12x10^3. The power will be superscripted on the plot.
axis_div: Division length along axis for tick marks in user coordinate space. (If axis_div==0.0 then the axis division will be calculated from the axis length and number of divisions).
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.
Note: The position & scaling may should be set via a call to setMapping(..).

3.4.8.10.5 Draw graph axis - drawGraphAxis

Draw an annotated graphics axis (full version).

Method Definition:

public void drawGraphAxis (int orient, double x_orig, double y_orig, double axis_len, Color line_colr, String title, int tfont_opt, double tfont_h, Color tcolr, double tt, int lfont_opt, double lfont_h, Color lcolr, double ll, double tick_siz, int ndiv, String[] labels, double axis_div, int nd, int id, boolean ovly)

Parameters List:

orient: Orientation =0 horizontal, =1 vertical (HORIZONTAL, VERTICAL).
x_orig: The 'x' origin for the axis in user coordinates.
y_orig: The 'y' origin for the axis in user coordinates.
axis_len: The axis length in user coordinate space ('x' if horizontal, 'y' if vertical axis).
line_colr: Colour for the axis lines and tick marks.
title: Axis title (may be null if not required).
tfont_opt: The title font option =1,2,3 Serif plain, bold, italic; =4,5,6 SansSerif plain, bold, italic; =7,8,9 Monospaced plain, bold, italic.
tfont_h: The title font height in normalised unit square units.
tcolr: The title colour.
tt: Shift title away from labels by 'tt' in normalised unit square units (if negative then the shift will be towards the labels) Set to 0.0 for default positioning.
lfont_opt: The labels font option =1,2,3 Serif plain, bold, italic; =4,5,6 SansSerif plain, bold, italic; =7,8,9 Monospaced plain, bold, italic.
lfont_h: The labels font height in normalised unit square units.
lcolr: The labels colour.
ll: Shift labels away from axis ticks by 'll' in normalised unit square units (if negative then the shift will be towards the axis ticks) Set to 0.0 for default positioning.
tick_siz: Tick mark size in normalised unit square units.
ndiv: No. of divisions for labels annotation.
labels: List of annotation labels for the tick marks (ndiv+1) values. May be null if labels are to be generated internally. Note: May contain the character ^ prior to a power value at the end of a labels string e.g. 3.12x10^3. The power will be superscripted on the plot.
axis_div: Division length along axis for tick marks in user coordinate space. (If axis_div==0.0 then the axis division will be calculated from the axis length and number of divisions).
nd: No. of decimal places for axis value labels.
id: A user selected identifier for this object, or the group of objects to which it belongs.
ovly: Set to true for output to overlay window, false for normal scroll window.
Note: The position & scaling may should be set via a call to setMapping(..).

3.4.8.11 Set Handler Objects

3.4.8.11.1 Introduction

This section has methods to set drawer and highlight handler objects.

Methods:

Set window drawer - setDrawer
Set highlight handler - setHighlightHandler

3.4.8.11.2 Set window drawer - setDrawer

This method sets the JdlGraphicsWindowDrawer object resource. This object may be used to draw directly on the graphics window. The drawer method will be invoked after all other main graphics window drawing has been done.

Method Definition:

public void setDrawer (JdlGraphicsWindowDrawer dr, int id)

Parameters List:

dr: A JdlGraphicsWindowDrawer interfaced object to carry out direct drawing on the Graphics window (default = null). Set to null to remove a previously defined drawer. Its jdl_graphics_window_drawer method is called from the paint routine for the main scroll window after any other defined objects have been drawn.
id: Identifier to be passed to the drawing method when called.

3.4.8.11.3 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 (JdlGraphicsWindowHighlightHandler handler)

Parameters List:

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

3.4.8.12 Keyboard/Mouse Input

3.4.8.12.1 Introduction

This section has methods to enable/disable actions from keyboard and mouse input.

Methods:

Enable keyboard input - enableGraphicsKeyinp
Enable mouse input - enableMotionActions

3.4.8.12.2 Enable keyboard input - enableGraphicsKeyinp

Enable keyboard input to the graphics area of the window (when command line input is inactive).

Method Definition:

public void enableGraphicsKeyinp (boolean b)

Parameters List:

b: =true enable input, =false do not accept keyboard input.

3.4.8.12.3 Enable mouse input - enableMotionActions

Enable mouse motion actions (outside active cells) to be generated.

Method Definition:

public void enableMotionActions (boolean b)

Parameters List:

b: =true enable, =false do not.

3.4.8.13 Standard Positioning and Sizing

3.4.8.13.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.8.13.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.8.13.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.8.13.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.8.13.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.8.14 Add/Remove Action Listener

3.4.8.14.1 Introduction

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

Methods:

Add action listener - addActionListener
Remove action listener - removeActionListener

3.4.8.14.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.8.14.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.8.15 Get Returned Data

3.4.8.15.1 Introduction

This section has methods to get data from the object relating to an action and following that action. There is also a method to determine whether or not caoomand line input is currently in progress.

Methods:

Get action code - getReturnedData
Get selected cell - getReturnedCell
Get command string - getReturnedCommand
Get character - getReturnedCharacter
Get mouse position - getMousePositionAbsolute
Get mouse position - getMousePositionScroll
Get mouse position - getMousePositionOverlay
Get mouse moved - getMouseMovedAbsolute
Get mouse moved - getMouseMovedScroll
Get mouse moved - getMouseMovedOverlay
Command input status - isCommandActive

3.4.8.15.2 Get action code - getReturnedData

Get returned data (last action option code).

Method Definition:: public int getReturnedData()
Parameters List:: none
Method Return:: Returns the last action option code. = 0 Not set = 1 Button 1 single click = 2 Button 2 single click = 3 Button 3 single click = 4 Button 1 double click = 5 Button 2 double click = 6 Button 3 double click = 7 Mouse motion = 8 Enter key = 9 Cursor up = 10 Cursor down = 11 Cursor left = 12 Cursor right = 13 Escape = 14 Delete = 15 Backspace = 16 Insert = 20 Typed key = 100 Cell selected = 200 Command line input

3.4.8.15.3 Get selected cell - getReturnedCell

Get the last selected cell number.

Method Definition:: public int getReturnedCell()
Parameters List:: none
Method Return:: Returns the last selected cell number (after action option code 100).

3.4.8.15.4 Get command string - getReturnedCommand

Get the last command line input string(after action option code 200) .

Method Definition:: public String getReturnedCommand()
Parameters List:: none
Method Return:: Returns the last command line input string.

3.4.8.15.5 Get character - getReturnedCharacter

Get the returned character when the option is eanbles and when the command line is inactive and the graphics window has the keyboard focus. (after action option code 200).

Method Definition:: public char getReturnedCharacter()
Parameters List:: none
Method Return:: Returns the last input character when graphics screen has focus.

3.4.8.15.6 Get mouse position - getMousePositionAbsolute

Get the last mouse pressed position as an absolute position on the window.

Method Definition:: public Point getMousePositionAbsolute()
Parameters List:: none
Method Return:: Returns the last mouse pressed position.

3.4.8.15.7 Get mouse position - getMousePositionScroll

Get the last mouse pressed position relative to the scrolled window area.

Method Definition:: public Point getMousePositionScroll()
Parameters List:: none
Method Return:: Returns the last mouse pressed position relative to the scrolled window area.

3.4.8.15.8 Get mouse position - getMousePositionOverlay

Get the last mouse pressed position relative to the overlay window area.

Method Definition:: public Point getMousePositionOverlay()
Parameters List:: none
Method Return:: Returns the last mouse pressed position relative to the overlay window area.

3.4.8.15.9 Get mouse moved - getMouseMovedAbsolute

Get the last mouse moved position (absolute) if the option is enabled.

Method Definition:: public Point getMouseMovedAbsolute()
Parameters List:: none
Method Return:: Returns the last mouse moved position.

3.4.8.15.10 Get mouse moved - getMouseMovedScroll

Get the last mouse moved position relative to the scrolled window area.

Method Definition:: public Point getMouseMovedScroll()
Parameters List:: none
Method Return:: Returns the last mouse moved position relative to the scrolled window area.

3.4.8.15.11 Get mouse moved - getMouseMovedOverlay

Get the last mouse moved position relative to the overlay window area.

Method Definition:: public Point getMouseMovedOverlay()
Parameters List:: none
Method Return:: Returns the last mouse moved position relative to the overlay window area.

3.4.8.15.12 Command input status - isCommandActive

See if command input is currently in progress.

Method Definition:: public boolean isCommandActive()
Parameters List:: none
Method Return:: true if command input in progress, otherwise false.

3.4.8.16 Overriden Superclass Methods

3.4.8.16.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