3.4.4 - Parameter Table - JdlParameterTable

John W. Campbell

3.4.4.1 Introduction

This class provides a parameter table object with rows and columns of parameter names & editable parameter values. As well as text input of a value a drop down menu or step buttons to move up and down a list of values may be defined for a parameter. There is also a special option for parameters with two 'toggle' values Yes/No or On/Off. If required there is an option to disallow changes for selected parameters as needed.

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Operational Methods
Setting Saved Parameters
Error and Message Handling
Test for Input in Progress
Table Selection and Reset
Standard Positioning and Sizing
Add/Remove Action Listener
Get Returned Data
Overriden Superclass Methods

3.4.4.2 Class Details

Package:: Jdl.JdlView;
Class name:: JdlParameterTable
Class definition:: public class JdlParameterTable
Extends:: JdlDrawPanel
Implements:: ActionListener
MouseListener
JdlDrawPanelDrawer
JdlViewObject
Actions:: An action event will be generated when a parameter value is changed. The associated object is the string 'item n m' where 'n' is the number of the parameter item whose value has been changed and 'm' is the table number.

3.4.4.3 Accessible Fields

The following accessible fields have been defined:

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

3.4.4.4 Constructor

3.4.4.4.1 Introduction

Two constructors are available.

Constructor:

Standard constructor
Multiple table constructor

3.4.4.4.2 Standard constructor

Constructs a JdlParameterObject with a given number of rows and columns.

Constructor Definition:

public JdlParameterTable(int ncols, int nrows, String titl, int lab_w, String[] labstr, int nv_disp, boolean allow_buttons, JdlViewOptions view_opts)

Parameters List:

ncols: The number of columns (cannot be changed after creation of the parameter table object).
nrows: The number of rows (cannot be changed after creation of the parameter table object).
titl: The initial title string.
lab_w: A pre-calculated width for the labels text in pixels. If 0 then a label text width will be calculated from the 'labstr' parameter. Once set, the label width remains fixed.
labstr: An initial set of label strings for the parameter table items. If lab_w was zero then the required label width will be determined from the longest string (based on the label font or the label bold font). Once determined, the label width remains fixed. If fewer labels are given than the number of items in the table then some parameter items will remain unlabelled. If more labels are given than the number of items in the table then the excess will not be used as labels but will be included in the calculation of the labels text width (if lab_w==0).
nv_disp: The number of characters to be displayed in the value field. (The stored value string length can exceed this and a scroll policy is implemented).
allow_buttons: Allow popup values menus and/or step-buttons flag. (cannot be changed after creation of the parameter table object).
view_opts: Object to set non-default options for borders, active strip, colours and fonts.

3.4.4.4.3 Multiple table constructor

Constructs a JdlParameterObject with a given number of rows and columns.

Constructor Definition:

public JdlParameterTable(int ncols, int nrows, String[] titl, int ntabs, int lab_w, String[][] labstr, int nv_disp, boolean allow_buttons, JdlViewOptions view_opts)

Parameters List:

ncols: The number of columns (cannot be changed after creation of the parameter table object).
nrows: The number of rows (cannot be changed after creation of the parameter table object).
titl: The initial title strings ('ntabs' values).
ntabs: Number of selectable tables - if >1 (Multiple Tables option) then a table selector will be output in the title strip allowing the selection from the 'ntabs' tables.
lab_w: A pre-calculated width for the labels text in pixels. If 0 then a label text width will be calculated from the 'labstr' parameter. Once set, the label width remains fixed.
labstr: An initial set of label strings for the parameter table items. If lab_w was zero then the required label width will be determined from the longest string (based on the label font or the label bold font). Once determined, the label width remains fixed. If fewer labels are given than the number of items in the table then some parameter items will remain unlabelled. If more labels are given than the number of items in the table then the excess will not be used as labels but will be included in the calculation of the labels text width (if lab_w==0).
nv_disp: The number of characters to be displayed in the value field. (The stored value string length can exceed this and a scroll policy is implemented).
allow_buttons: Allow popup values menus and/or step-buttons flag. (cannot be changed after creation of the parameter table object).
view_opts: Object to set non-default options for borders, active strip, colours and fonts.

3.4.4.5 Operational Methods

3.4.4.5.1 Introduction

This section contains methods to set and get the details for the parameter table items.

Methods:

Set title - setTitle
Set title - setTitle
Set parameter label - setItemLabel
Set parameter value - setItemValue
Set parameter value - setItemValue
Get parameter value - getItemValue
Set menu - setItemMenu
Set menu - setItemMenu
Show step button - setItemUpDown
Set up/down handler - setItemUpDown
Set integer increment - setItemUpDown
Set float increment - setItemUpDown
Clear parameter - clearItem
Clear parameter value - clearValue
Disable edits - disableEdits
Set special mode - resetMode

3.4.4.5.2 Set title - setTitle

This method sets a new title string (first title if more than one present).

Method Definition:

public void setTitle(String title)

Parameters List:

title: The new title string.

3.4.4.5.3 Set title - setTitle

This method sets a new title string.

Method Definition:

public void setTitle(String title, int itab)

Parameters List:

title: The new title string.
itab: The table number.

3.4.4.5.4 Set parameter label - setItemLabel

This method sets a new parameter item label string (for the currently displayed table).

Method Definition:

public void setItemLabel(int item, String str)

Parameters List:

item: The parameter item number.
str: The new label string.

3.4.4.5.5 Set parameter value - setItemValue

This method sets a new parameter value string (for the currently displayed table).

Method Definition:

public void setItemValue(int item, String str)

Parameters List:

item: The parameter item number.
str: The new value string.

3.4.4.5.6 Set parameter value - setItemValue

This method sets a new parameter value string and type or special value (for the currently displayed table).

Method Definition:

public void setItemValue(int item, String str, int type)

Parameters List:

item: The item number.
str: The new value string (ignored if type!=0).
type: The value type flag:
= 0, normal
= 1, on/off toggle on value
= 2, on/off toggle off value
= 3, yes/no toggle yes value
= 4, yes/no toggle no value
= 5, label only

3.4.4.5.7 Get parameter value - getItemValue

This method returns an item value string for a 'normal' parameter (for the currently displayed table).

Method Definition:

public String getItemValue(int item)

Parameters List:

item: The parameter item number.

Method Return:

The parameter value string (null if out of range item no.).

3.4.4.5.8 Set menu - setItemMenu

This method sets a drop down menu for a parameter (The 'allow_buttons' parameter must have been set to true when the JdlParameterTable object was created) (for the currently displayed table).

Method Definition:

public void setItemMenu(int item, String[] strs)

Parameters List:

item: The item number.
strs: The new menu strings (if null, any existing menu will be removed).

3.4.4.5.9 Set menu - setItemMenu

This method sets a drop down menu for a parameter (The 'allow_buttons' parameter must have been set to true when the JdlParameterTable object was created) (for the currently displayed table).

Method Definition:

public void setItemMenu(int item, String[] strs, boolean only)

Parameters List:

item: The item number.
strs: The new menu strings (if null, any existing menu will be removed).
only: If true then only ther menu may be used to change the item values; if false then direct value input (the standard case) is allowed

3.4.4.5.10 Show step button - setItemUpDown

Display an up/down step button for the value item (The 'allow_buttons' parameter must have been set to true when the JdlParameterTable object was created) (for the currently displayed table).

Method Definition:

public void setItemUpDown(int item, boolean upd)

Parameters List:

item: The parameter item number.
upd: Display Up/Down button (if false, Up/Down button will be removed).

3.4.4.5.11 Set up/down handler - setItemUpDown

This method sets a user defined up/down handler. If defined, its jdl_value_updown_handler(..) method will be called so that a new value may be calculated for the parameter in response to selecting the step up or step down button for the parameter (for the currently displayed table).

Method Definition:

public void setItemUpDown(int item, JdlValueUpDownHandler handler)

Parameters List:

item: The parameter item number.
handler: The user defined JdlValueUpDownHandler handler.

3.4.4.5.12 Set integer increment - setItemUpDown

This method sets an internal increment/decrement for integer up/down value handling (for the currently displayed table).

Method Definition:

public void setItemUpDown(int item, int incr)

Parameters List:

item: The parameter item number.
handler: incr the integer increment to be used.

3.4.4.5.13 Set float increment - setItemUpDown

This method sets an internal increment/decrement for floating point up/down value handling (for the currently displayed table).

Method Definition:

public void setItemUpDown(int item, double fpinc)

Parameters List:

item: The parameter item number.
fpinc: The floating point incrementto be used.

3.4.4.5.14 Clear parameter - clearItem

This method clears (removes) a parameter item or all parameter items (for the currently displayed table).

Method Definition:

public void clearItem(int item, boolean silent)

Parameters List:

item: Parameter item number (0 = all items).
silent: Make silent after clearing flag (=true make silent, =false leave unchanged).

3.4.4.5.15 Clear parameter value - clearValue

This method clears (removes) a parameter value or all parameter values (for the currently displayed table) - the labels are left unchanged.

Method Definition:

public void clearValue(int item, boolean silent)

Parameters List:

item: Parameter item number (0 = all items).
silent: Make silent after clearing flag (=true make silent, =false leave unchanged).

3.4.4.5.16 Disable edits - disableEdits

This method allows for the temporary disabling of parameter edits for non-silent items and their re-enabling. This should only be used if the parameter table is being used independently of the JdlViewManager (when it is automatically used when a parameter table is set to its active or inactive state).

Method Definition:

public void disableEdits(boolean disable)

Parameters List:

disable: Set to true to disable edits or false to re-enable edits.

3.4.4.5.17 Set special mode - resetMode

This method sets a special mode for a parameter item or for all parameter items (for the currently displayed table).

Method Definition:

public void resetMode(int item, boolean bold, boolean silent)

Parameters List:

item: Parameter item number (0 = all items).
bold: Make bold flag (=true make bold, = false reset normal font).
silent: Make silent flag (=true make silent, = false make active).

3.4.4.6 Setting Saved Parameters

3.4.4.6.1 Introduction

This section has methods for setting the saved values for parameters for the case where multiple tables are used. The saved values are then only displayed if the parameter table is changed or if it is set using the selectTable(..) method.

Methods:

Set saved parameter label - setSavedItemLabel
Set saved value - setSavedItemValue
Set saved menu - setSavedItemMenu
Set saved menu - setSavedItemMenu
Set saved step button - setSavedItemUpDown
Set saved up/down handler - setSavedItemUpDown
Set saved integer increment - setSavedItemUpDown
Set saved float increment - setSavedItemUpDown
Clear saved parameter - clearSavedItem
Clear saved parameter value - clearSavedValue
Set saved special mode - resetSavedMode

3.4.4.6.2 Set saved parameter label - setSavedItemLabel

This method sets a new parameter item label string for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemLabel(int item, String str, int itabl)

Parameters List:

item: The parameter item number.
str: The new label string.
itabl: Table number (1 for the single table case)

3.4.4.6.3 Set saved value - setSavedItemValue

This method sets a new parameter value string and type or special value for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemValue(int item, String str, int type, int itabl)

Parameters List:

item: The item number.
str: The new value string (ignored if type!=0).
type: The value type flag:
= 0, normal
= 1, on/off toggle on value
= 2, on/off toggle off value
= 3, yes/no toggle yes value
= 4, yes/no toggle no value
= 5, label only
itabl: Table number (1 for the single table case)

3.4.4.6.4 Set saved menu - setSavedItemMenu

This method sets a drop down menu for a parameter (The 'allow_buttons' parameter must have been set to true when the JdlParameterTable object was created) for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemMenu(int item, String[] strs, int itabl)

Parameters List:

item: The item number.
strs: The new menu strings (if null, any existing menu will be removed).
itabl: Table number (1 for the single table case)

3.4.4.6.5 Set saved menu - setSavedItemMenu

Method Definition:

public void setSavedItemMenu(int item, String[] strs, int itabl, boolean only)

Parameters List:

item: The item number.
strs: The new menu strings (if null, any existing menu will be removed).
itabl: Table number (1 for the single table case)
only: If true, only allow menu input; if false standard value input allowed.

3.4.4.6.6 Set saved step button - setSavedItemUpDown

Sets an up/down step button for the value item (The 'allow_buttons' parameter must have been set to true when the JdlParameterTable object was created) for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemUpDown(int item, boolean upd, int itabl)

Parameters List:

item: The parameter item number.
upd: Display Up/Down button (if false, Up/Down button will be removed).
itabl: Table number (1 for the single table case)

3.4.4.6.7 Set saved up/down handler - setSavedItemUpDown

Method Definition:

public void setSavedItemUpDown(int item, JdlValueUpDownHandler handler, int itabl)

Parameters List:

item: The parameter item number.
handler: The user defined JdlValueUpDownHandler handler.
itabl: Table number (1 for the single table case)

3.4.4.6.8 Set saved integer increment - setSavedItemUpDown

This method sets an internal increment/decrement for integer up/down value handling for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemUpDown(int item, int incr, int itabl)

Parameters List:

item: The parameter item number.
handler: incr the integer increment to be used.
itabl: Table number (1 for the single table case)

3.4.4.6.9 Set saved float increment - setSavedItemUpDown

This method sets an internal increment/decrement for floating point up/down value handling for a selected table - displayed table is not updated.

Method Definition:

public void setSavedItemUpDown(int item, double fpinc, int itabl)

Parameters List:

item: The parameter item number.
fpinc: The floating point incrementto be used.
itabl: Table number (1 for the single table case)

3.4.4.6.10 Clear saved parameter - clearSavedItem

This method clears (removes) a parameter item or all parameter items for a selected table - displayed table is not updated.

Method Definition:

public void clearSavedItem(int item, boolean silent, int itabl)

Parameters List:

item: Parameter item number (0 = all items).
silent: Make silent after clearing flag (=true make silent, =false leave unchanged).
itabl: Table number (1 for the single table case)

3.4.4.6.11 Clear saved parameter value - clearSavedValue

This method clears (removes) a parameter value or all parameter values for a selected table - the labels are left unchanged - displayed table is not updated.

Method Definition:

public void clearSavedValue(int item, boolean silent, int itabl)

Parameters List:

item: Parameter item number (0 = all items).
silent: Make silent after clearing flag (=true make silent, =false leave unchanged).
itabl: Table number (1 for the single table case)

3.4.4.6.12 Set saved special mode - resetSavedMode

This method sets a special mode for a parameter item or for all parameter items for a selected table - displayed table is not updated.

Method Definition:

public void resetSavedMode(int item, boolean bold, boolean silent, int itabl)

Parameters List:

item: Parameter item number (0 = all items).
bold: Make bold flag (=true make bold, = false reset normal font).
silent: Make silent flag (=true make silent, = false make active).
itabl: Table number (1 for the single table case)

3.4.4.7 Error and Message Handling

3.4.4.7.1 Introduction

This section has methods relating to parameter value error/information-message handling.

Methods:

Notify error - notifyError
Notify error - notifyError
Notify information - notifyInformation
Get dialogue position - getDialogPosition

3.4.4.7.2 Notify error - notifyError

This method notifies an error condition with a dialogue. If an invalid parameter value is detected, then the program may use this routine to handle the error condition. An error dialogue box will be displayed containing the user defined error message string and a message indicating that the old value will be replaced when the CONTINUE button within the dialogue box is selected.

Method Definition:

public void notifyError(int item, String str)

Parameters List:

item: The parameter item number.
str: An error string for the error dialogue box.

3.4.4.7.3 Notify error - notifyError

This method notifies an error condition silently. If an invalid parameter value is detected, then the program may use this routine to handle the error condition. The old value will be replaced.

Method Definition:

public void notifyError(int item)

Parameters List:

item: The parameter item number.

3.4.4.7.4 Notify information - notifyInformation

This method may be used to inform the user of any further consequences following the input of the new value (e.g. that another parameter will also be updated). An Information message dialogue will be displayed with a single 'OK' button.

Method Definition:

public void notifyInformation(int item, String str)

Parameters List:

item: The parameter item number.
str: A message string for the information dialogue box.

3.4.4.7.5 Get dialogue position - getDialogPosition

Get the position of a parameter item relative to the parameter table origin. This may be used, for example, to position popup dialogues.

Method Definition:

public Point getDialogPosition(int item)

Parameters List:

item: The parameter item number.

Method Return:

The parameter item position (top right hand corner of value field).

3.4.4.8 Test for Input in Progress

3.4.4.8.1 Introduction

This section has methods which may be used to test whether there is currently any uncompleted parameter value input.

Methods:

Is item being input - itemBeingInput
Cancel input - cancelInput

3.4.4.8.2 Is item being input - itemBeingInput

This method may be used to test whether a parameter item value is being input currently.

Method Definition:: public int itemBeingInput()
Parameters List:: none
Method Return:: The number of the item being input, 0 if none.

3.4.4.8.3 Cancel input - cancelInput

This method may be used to test whether a parameter item value is being input currently and if so cancel the input & replace previous value string.

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

3.4.4.9 Table Selection and Reset

3.4.4.9.1 Introduction

This section has methods to select a particular parameter table and to reset the display for the current parameter table when multiple tables are used.

Methods:

Select table data - selectTable
Reset table data - resetTable

3.4.4.9.2 Select table data - selectTable

If multiple tables are available then this method enables one other these tables to be selected.

Method Definition:

public void selectTable(int itabl)

Parameters List:

itabl: The required table number.

3.4.4.9.3 Reset table data - resetTable

If multiple tables are available then method may be used to update the values on the display for the current table following updates of any values updated using one of the 'save' methods e.g. setSavedItemValue(..).

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

3.4.4.10 Standard Positioning and Sizing

3.4.4.10.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.4.10.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.4.10.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.4.10.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.4.10.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.4.11 Add/Remove Action Listener

3.4.4.11.1 Introduction

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

Methods:

Add action listener - addActionListener
Remove action listener - removeActionListener

3.4.4.11.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.4.11.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.4.12 Get Returned Data

3.4.4.12.1 Introduction

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

Methods:

Get item number - getReturnedData
Get item and table number - getReturnedData
Get value string - getReturnedValueString

3.4.4.12.2 Get item number - getReturnedData

This method returns the last selected parameter table item number.

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

3.4.4.12.3 Get item and table number - getReturnedData

This method returns the last selected parameter item and table numbers. This should be used if multiple tables are being used.

Method Definition:

public int getReturnedData(JdlInt itabl)

Parameters List:

itabl: Returns the last selected table number

Method Return:

Returns the last selected parameter table item number.

3.4.4.12.4 Get value string - getReturnedValueString

This method returns the last selected parameter table item value input.

Method Definition:: public String getReturnedValueString()
Parameters List:: none
Method Return:: Returns the last selected parameter table item value input.

3.4.4.13 Overriden Superclass Methods

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