3.10.12 - Parameter Value Input - JdlValue

John W. Campbell

3.10.12.1 Introduction

This class provides a parameter value object which is used to display a parameter value which may be changed by the user when required. The object displays a parameter name (label) at the left hand side and a value field at the right hand side. When the value field has been selected, a new value may be input. Pressing the Return or Enter keys completes the input of the new value. The JdlValue object also allows a drop down menu to be associated with the parameter value if required or an up/down arrow control. Special options include on/off or yes/no toggle values and a label only display.

Class, fields, constructor and methods:

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

3.10.12.2 Class Details

Package:: Jdl.JdlView;
Class name:: JdlValue
Class definition:: public class JdlValue
Extends:: JPanel
Implements:: JdlFramedPanelDrawer
JdlDialogReturns
MouseListener
MouseMotionListener
ActionListener
FocusListener
KeyListener
Actions:: When value input is completed an action event is generated. The action command string is "value_input". Action events are also posted when value input is first requested (action command string "replace_started") or if the Escape key is pressed (action command string "escape"). Changing a toggle value will also generate an action with the action command string "value_input". The method returnInputString(..) is used to retrieve the input value.

3.10.12.3 Accessible Fields

The following accessible fields have been defined:

public final static int NO_BUTTON: Button - no button.
public final static int MENU_BUTTON: Button - menu button.
public final static int UP_DOWN_BUTTON: Button - up/down button button.
public final static int RESERVE_SPACE: Reserve space for button.
public final static int PREFERRED: Size Constraint: preferred size.
public final static int FREE: Size/Location Constraint: free.
static final long serialVersionUID

3.10.12.4 Constructor

3.10.12.4.1 Introduction

Two constructors are available.

Constructor:

Default constructor
Standard constructor

3.10.12.4.2 Default constructor

Construct a JdlValue object with default parameters.

Constructor Definition:: public JdlValue()
Parameters List:: none

3.10.12.4.3 Standard constructor

Construct a JdlValue object of requested mimimum dimensions allowing or disallowing drop-down menu input.

Constructor Definition:

public JdlValue(int minw, int minh, int button)

Parameters List:

minw: The minimum width requested (only used if greater than the minimum needed for the layout.
minh: The minimum height requested (only used if greater than the minimum needed for the layout.
button: Allow/disallow a drop down menu or an up/down button for item value selection:
= 0, no button
= 1, menu button
= 2, up/down button
= 3, reserve space for button
(may use NO_BUTTON, MENU_BUTTON, UP_DOWN_BUTTON, RESERVE_SPACE)

3.10.12.5 Operational Methods

3.10.12.5.1 Introduction

This section contains the main methods used with normal operation of the object.

Methods:

Set label - setLabelString
Get label - getLabelString
Set menu - setMenuStrings
Get menu - getMenuStrings
Set value - setValueString
Get value - getValueString
Notify error - notifyError
Notify error - notifyError
Notify information - notifyInformation
Cancel current input - cancelInput
Get input string - returnInputString
Is item being input - isItemBeingInput

3.10.12.5.2 Set label - setLabelString

This method sets the label string.

Method Definition:

public void setLabelString(String str)

Parameters List:

str: The required label (parameter name) string (default = null).

3.10.12.5.3 Get label - getLabelString

This method returns the label string.

Method Definition:: public String getLabelString()
Parameters List:: none
Method Return:: Returns the label string.

3.10.12.5.4 Set menu - setMenuStrings

This method sets the menu strings. strs An array of strings for a drop down menu of valid values (default = null for no such menu). To be used, the menu allowed flag must also be set to true (see setMenuAllowed(..) method).

Method Definition:

public void setMenuStrings(String[] strs)

Parameters List:

strs: An array of the required menu strings.

3.10.12.5.5 Get menu - getMenuStrings

Get the menu strings.

Method Definition:: public String[] getMenuStrings()
Parameters List:: none
Method Return:: Returns an array of menu strings (A reference not a copy).

3.10.12.5.6 Set value - setValueString

This method sets the value string.

Method Definition:

public void setValueString (String str)

Parameters List:

str: The parameter value string (default = null).

3.10.12.5.7 Get value - getValueString

Get the value string.

Method Definition:: public String getValueString()
Parameters List:: none
Method Return:: Returns the parameter value string (A reference not a copy).

3.10.12.5.8 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 method 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(String str)

Parameters List:

str: An error string for the error dialogue box.

3.10.12.5.9 Notify error - notifyError

This method notifies an error condition (silently).

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

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

3.10.12.5.10 Notify information - notifyInformation

This method outputs an information dialogue to tell the user for example about further consequences of the parameter update. The dialogue box has a single 'OK' button.

Method Definition:

public void notifyInformation(String str)

Parameters List:

str: An error string for the error dialogue box.

3.10.12.5.11 Cancel current input - cancelInput

This method cancels the current input (if any) & replaces the value with the previous value string.

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

3.10.12.5.12 Get input string - returnInputString

This method returns the last input string.

Method Definition:: public String returnInputString()
Parameters List:: none
Method Return:: Returns the last parameter value string which has been input via the value field.

3.10.12.5.13 Is item being input - isItemBeingInput

This method may be called to determine whether or not an item is currently being input.

Method Definition:: public boolean isItemBeingInput()
Parameters List:: none
Method Return:: true if item being input, otherwise false.

3.10.12.6 Resource Methods

3.10.12.6.1 Introduction

This section has methods to set/get the resources associated with the object determining its appearance and mode of action.

Methods:

Set arrow separator - setArrowSeparator
Get arrow separator - getArrowSeparator
Set cursor colour - setCursorColor
Get cursor colour - getCursorColor
Set cursor type - setCursorType
Get cursor type - getCursorType
Set horizontal expand - setExpandValueHorizontal
Get horizontal expand - getExpandValueHorizontal
Set vertical expand - setExpandValueVertical
Get vertical expand - getExpandValueVertical
Set label alignment - setLabelAlignment
Get label alignment - getLabelAlignment
Set label font - setLabelFont
Get label font - getLabelFont
Set bold label font - setLabelBoldFont
Get bold label font - getLabelBoldFont
Stored value characters - setMaximumValueCharacters
Get stored value characters - getMaximumValueCharacters
Set menu allowed - setMenuAllowed
Get menu allowed - getMenuAllowed
Set menu only - setMenuOnly
Get menu only - getMenuOnly
Set label size - setFixedLabelTextSize
Get label size - getFixedLabelTextSize
Set up/down handling - setUpDownHandling
Set up/down handler - setUpDownHandling
Set integer increment - setUpDownHandling
Set double increment - setUpDownHandling
Get up/down allowed - getUpDownAllowed
Displayed value characters - setNumberValueDisplayedCharacters
Get displayed value characters - getNumberValueDisplayedCharacters
Set surround height - setSurroundHeight
Get surround height - getSurroundHeight
Set surround width - setSurroundWidth
Get surround width - getSurroundWidth
Set value font - setValueFont
Get value font - getValueFont
Set value freeze - setValueFreeze
Get value freeze - getValueFreeze
Set value separator - setValueSeparator
Get value separator - getValueSeparator
Set shadow thickness - setValueShadowThickness
Get shadow thickness - getValueShadowThickness
Set value type - setValueType
Get value type - getValueType
Set variable label - setVariableLabelSize
Get variable label - getVariableLabelSize

3.10.12.6.2 Set arrow separator - setArrowSeparator

This method sets the arrow separator resource.

Method Definition:

public void setArrowSeparator(int sep)

Parameters List:

sep: The minimum separation width between the value field and the arrow button (if present) which indicates the presence of a drop down menu (default = 2).

3.10.12.6.3 Get arrow separator - getArrowSeparator

This method returns the arrow separator resource.

Method Definition:: public int getArrowSeparator()
Parameters List:: none
Method Return:: Returns the value of thr arrow separator resource.

3.10.12.6.4 Set cursor colour - setCursorColor

This method sets the cursor colour resource.

Method Definition:

public void setCursorColor(Color colr)

Parameters List:

colr: The required cursor colout.

3.10.12.6.5 Get cursor colour - getCursorColor

This method returns the cursor colour resource.

Method Definition:: public Color getCursorColor()
Parameters List:: none
Method Return:: Returns the current cursor colour.

3.10.12.6.6 Set cursor type - setCursorType

This method sets the cursor type resource.

Method Definition:

public void setCursorType(int type)

Parameters List:

type: The required cursor type:
= 0, a horizontal cursor at the foot of the new character position (the default)
= 1, a vertical line at the left hand side of the new character position
= 2, a solid block of colour covering the new character position

3.10.12.6.7 Get cursor type - getCursorType

This method returns the cursor type resource.

Method Definition:: public int getCursorType()
Parameters List:: none
Method Return:: Returns the cursor type flag.

3.10.12.6.8 Set horizontal expand - setExpandValueHorizontal

This method sets the expand value horizontally resource.

Method Definition:

public void setExpandValueHorizontal(boolean e)

Parameters List:

e: Allow or do not allow (the default) the value area to be expanded horizontally if the JdlValue object is resized.

3.10.12.6.9 Get horizontal expand - getExpandValueHorizontal

This method returns the expand value horizontally resource.

Method Definition:: public boolean getExpandValueHorizontal()
Parameters List:: none
Method Return:: Returns the value of the flag.

3.10.12.6.10 Set vertical expand - setExpandValueVertical

This method sets the expand value vertically resource.

Method Definition:

public void setExpandValueVertical(boolean e)

Parameters List:

e: Allow or do not allow (the default) the value area to be expanded vertically if the JdlValue object is resized.

3.10.12.6.11 Get vertical expand - getExpandValueVertical

This method returns the expand value vertically resource.

Method Definition:: public boolean getExpandValueVertical()
Parameters List:: none
Method Return:: Returns the value of the flag.

3.10.12.6.12 Set label alignment - setLabelAlignment

This method sets the label alignment resource.

Method Definition:

public void setLabelAlignment(int align)

Parameters List:

align: The label alignment within the parameter name (label) field, =0 center the label in the field, =1 align to the left of the field (the default), =2 align to the right of the field.

3.10.12.6.13 Get label alignment - getLabelAlignment

This method returns the label alignment resource.

Method Definition:: public int getLabelAlignment()
Parameters List:: none
Method Return:: Returns the label alignment flag.

3.10.12.6.14 Set label font - setLabelFont

This method sets the label font resource.

Method Definition:

public void setLabelFont (Font font)

Parameters List:

font: The required font for the label (parameter name) (Default = null for default AWT label font).

3.10.12.6.15 Get label font - getLabelFont

This method returns the label font resource.

Method Definition:: public Font getLabelFont()
Parameters List:: none
Method Return:: Returns the current label font.

3.10.12.6.16 Set bold label font - setLabelBoldFont

This method sets the label bold font resource.

Method Definition:

public void setLabelBoldFont (Font font)

Parameters List:

font: Used in dialog error messages.

3.10.12.6.17 Get bold label font - getLabelBoldFont

This method returns the label bold font resource.

Method Definition:: public Font getLabelBoldFont()
Parameters List:: none
Method Return:: Returns the current label bold font.

3.10.12.6.18 Stored value characters - setMaximumValueCharacters

This method sets the maximum number of stored value characters resource.

Method Definition:

public void setMaximumValueCharacters(int n)

Parameters List:

n: The maximum no. of characters allowed in the value string (default = 50).

3.10.12.6.19 Get stored value characters - getMaximumValueCharacters

This method sets the maximum value characters resource.

Method Definition:: public int getMaximumValueCharacters()
Parameters List:: none
Method Return:: Returns the maximum no. of characters allowed in the value string.

3.10.12.6.20 Set menu allowed - setMenuAllowed

This method sets the menu allowed resource.

Method Definition:

public void setMenuAllowed(boolean men)

Parameters List:

men: This indicates whether or not the value field may have a drop down menu associated with it. If true, the space will be allocated for the arrow button for the menu though the arrow button will not be displayed unless a menu has been defined by setting the menuStrings resource (see setMenuStrings method). (default = false). Cannot be turned on if up/down button is currently allowed.

3.10.12.6.21 Get menu allowed - getMenuAllowed

This method returns the menu allowed resource.

Method Definition:: public boolean getMenuAllowed()
Parameters List:: none
Method Return:: Returns the value of the menu allowed flag.

3.10.12.6.22 Set menu only - setMenuOnly

This method sets a flag which gives the option of allowing the input of a new value using only the menu. It only takes effect when a menu is defined for the value item.

Method Definition:

public void setMenuOnly(boolean only)

Parameters List:

only: If true set the 'input from menu only' option, if false disable this option and allow normal input via the value area.

3.10.12.6.23 Get menu only - getMenuOnly

This method returns the value of the 'input from menu only' option.

Method Definition:: public boolean getMenuOnly()
Parameters List:: none
Method Return:: The 'input from menu only' flag.

3.10.12.6.24 Set label size - setFixedLabelTextSize

This method sets the label fixed label text size resource. The variable label size resource is automatically set to false by this method (see setVariableLabelSize(..)) and must remain so for this size to be used.

Method Definition:

public void setFixedLabelTextSize(int w, int h)

Parameters List:

w: The required label text width in pixels.
h: The required label text height in pixels.

3.10.12.6.25 Get label size - getFixedLabelTextSize

This method returns the label fixed label text size resource.

Method Definition:: public Dimension getFixedLabelTextSize()
Parameters List:: none
Method Return:: Returns fixed label text size resource.

3.10.12.6.26 Set up/down handling - setUpDownHandling

This method sets the up/down button handling options. This version will post an action event (command "up" or "down") when the respective button is pressed.

Method Definition:

public void setUpDownHandling(boolean but)

Parameters List:

but: If true, an up/down button will be displayed; if false any existing up/down button will be removed. Cannot be turned on if the menu allowed button is currently enabled.

3.10.12.6.27 Set up/down handler - setUpDownHandling

This method sets the up/down button handling options. This version will use the user defined handler to change the value as required.

Method Definition:: public void setUpDownHandling(JdlValueUpDownHandler handler)
Parameters List:: none

3.10.12.6.28 Set integer increment - setUpDownHandling

This method sets the up/down button handling options. This version sets an internal option to increment/decrement an integer value.

Method Definition:: public void setUpDownHandling(int incr)
Parameters List:: none

3.10.12.6.29 Set double increment - setUpDownHandling

This method sets the up/down button handling options. This version sets an internal option to increment/decrement a floating point value.

Method Definition:: public void setUpDownHandling(double fp)
Parameters List:: none

3.10.12.6.30 Get up/down allowed - getUpDownAllowed

This method returns the up/down button allowed resource.

Method Definition:: public boolean getUpDownAllowed()
Parameters List:: none
Method Return:: Returns the value of the up/down button allowed flag.

3.10.12.6.31 Displayed value characters - setNumberValueDisplayedCharacters

This method sets the number of displayed value characters resource.

Method Definition:

public void setNumberValueDisplayedCharacters (int n)

Parameters List:

n: The number of parameter value characters to be displayed i.e. the width of the parameter value field. The number of characters which may be stored for the parameter value may exceed this if required (see the maximum value characters resource). If the current parameter value string exceeds the displayed length available then a scrolling mechanism is invoked.

3.10.12.6.32 Get displayed value characters - getNumberValueDisplayedCharacters

This method returns the number of displayed value characters resource.

Method Definition:: public int getNumberValueDisplayedCharacters()
Parameters List:: none
Method Return:: Returns the requested number of displayed value characters.

3.10.12.6.33 Set surround height - setSurroundHeight

This method sets the surround height resource.

Method Definition:

public void setSurroundHeight(int minh)

Parameters List:

minh: Surround border height (top & bottom) added to the minimum requirements for the label, value area etc.

3.10.12.6.34 Get surround height - getSurroundHeight

This method returns the surround height resource.

Method Definition:: public int getSurroundHeight()
Parameters List:: none
Method Return:: Returns the surround height.

3.10.12.6.35 Set surround width - setSurroundWidth

This method sets the surround width resource.

Method Definition:

public void setSurroundWidth(int minw)

Parameters List:

minw: Surround border width (left and right) added to the minimum requirements for the label, value area etc.

3.10.12.6.36 Get surround width - getSurroundWidth

This method returns the surround width resource.

Method Definition:: public int getSurroundWidth()
Parameters List:: none
Method Return:: Returns the surround width.

3.10.12.6.37 Set value font - setValueFont

This method sets the value font resource.

Method Definition:

public void setValueFont(Font font)

Parameters List:

font: The font for the parameter value string (default = null, uses label font). Note: should normally be a fixed width font.

3.10.12.6.38 Get value font - getValueFont

This method returns the value font resource.

Method Definition:: public Font getValueFont()
Parameters List:: none
Method Return:: Returns the font for the parameter value string.

3.10.12.6.39 Set value freeze - setValueFreeze

This method sets the value freeze resource.

Method Definition:

public void setValueFreeze(boolean frz)

Parameters List:

frz: Flag to freeze (disable) the input of a new value. The input is frozen if the flag is true and the normal value input mode operates if the flag is false (the default).

3.10.12.6.40 Get value freeze - getValueFreeze

This method returns the value freeze resource.

Method Definition:: public boolean getValueFreeze()
Parameters List:: none
Method Return:: Returns the value of the 'value freeze' flag.

3.10.12.6.41 Set value separator - setValueSeparator

This method sets the value separator resource.

Method Definition:

public void setValueSeparator(int sep)

Parameters List:

sep: The separation required between the parameter label and the parameter value fields (default = 2).

3.10.12.6.42 Get value separator - getValueSeparator

This method returns the value separator resource.

Method Definition:: public int getValueSeparator()
Parameters List:: none
Method Return:: Returns the value separator width.

3.10.12.6.43 Set shadow thickness - setValueShadowThickness

This method sets the value shadow thickness resource.

Method Definition:

public void setValueShadowThickness(int th)

Parameters List:

th: Shadow thickness for value area surround frame (default = 2).

3.10.12.6.44 Get shadow thickness - getValueShadowThickness

This method returns the value shadow thickness resource.

Method Definition:: public int getValueShadowThickness()
Parameters List:: none
Method Return:: Returns the value shadow thickness.

3.10.12.6.45 Set value type - setValueType

This method sets the value type resource.

Method Definition:

public void setValueType(int type)

Parameters List:

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.10.12.6.46 Get value type - getValueType

This method returns the value type resource.

Method Definition:: public int getValueType()
Parameters List:: none
Method Return:: Returns the value type flag.

3.10.12.6.47 Set variable label - setVariableLabelSize

This method sets the variable label size resource.

Method Definition:

public void setVariableLabelSize(boolean var)

Parameters List:

var: Allow or disallow a variable label size using actual label text to get the size for the label field rather than using a pre-calculated size input by the user (see setFixedLabelTextSize) (default = false).

3.10.12.6.48 Get variable label - getVariableLabelSize

This method returns the variable label size resource.

Method Definition:: public boolean getVariableLabelSize()
Parameters List:: none
Method Return:: Returns the value of the variable label size flag.

3.10.12.7 Standard Positioning and Sizing

3.10.12.7.1 Introduction

This section contains the standard methods for positioning and sizing the object.

Methods:

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

3.10.12.7.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.10.12.7.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.10.12.7.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.10.12.7.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.10.12.8 Add/Remove Action Listener

3.10.12.8.1 Introduction

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

Methods:

Add action listener - addActionListener
Remove action listener - removeActionListener

3.10.12.8.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.10.12.8.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.10.12.9 Overriden Superclass Methods

3.10.12.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 method is also over-ridden but is 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