3.2.2 - View Manager - JdlViewManager

John W. Campbell

3.2.2.1 Introduction

This class provides the means of managing a set of JdlView objects for a view object based program. The manager also provides methods for the central handling of event driven input from the view objects. There are special options for handling keyboard input at the same time as handling the JdlView objects and for handling a timer. A set of methods for calculating and setting a layout of JdlView objects is included.

When using the JdlView management, a single JdlViewManager object must be created before any individual JdlView objects are defined.

The JdlViewManagement object also defines standard sets of fonts, colours and style parameters for JdlView objects. These are used as default values for JdlView objects even if they are not used within the context of the JdlView object manager.

Default values for fonts and colours may be overridden by creating a file named ".java.jdl_vm.txt" in the home directory. Entries in the file may have the following forms:
standard_font  name siz 
standard_bold_font  name siz
standard_italic_font  name siz
fixed_font  name siz
fixed_bold_font  name siz
fixed_italic_font  name siz
fixed_font_small  name siz
bg r g b
bg_darker r g b
bg_brighter r g b
fg r g b
act_highlight r g b
focus_off_color r g b
The entries 'name' and 'siz' are replaced by the required font name string and integer font size. 'r', 'g', 'b' are floating point numbers (from 0.0 to 1.0) for the colour components. The colours may be followed by an additional field with either a - sign to darken the given colour or a + sign to brighten it. Not all entries need be given but the sizes of the standard/bold/italic fonts should be reasonably well matched. If the font name contains spaces, it must be specified in quotes.
e.g. (Not recommended but shows effect!)
bg 0.7 0.5 0.95
bg_darker 0.7 0.5 0.95 -
bg_brighter 0.7 0.5 0.95 +
fg 0.7 0.05 0.2
standard_font "URW Chancery L" 14
standard_bold_font "URW Chancery L" 14
standard_italic_font "URW Chancery L" 14

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Class Method
Operational Methods
Special Methods
Calculate Layout

3.2.2.2 Class Details

Package:
Jdl.JdlView;
Class name:
JdlViewManager
Class definition:
public class JdlViewManager
Extends:
Object
Implements:
ActionListener
WindowListener
Runnable
Actions:
none

3.2.2.3 Accessible Fields

The following accessible fields have been defined:

public static Font standard_font
Standard font.
public static Font standard_bold_font
Standard bold font.
public static Font standard_italic_font
Standard italic font.
public static Font fixed_font
Fixed width font.
public static Font fixed_bold_font
Fixed width bold font.
public static Font fixed_italic_font
Fixed width italic font.
public static Font fixed_font_small
Fixed width small font.
public static Color bg
Background colour.
public static Color bg_brighter
Background colour - brighter.
public static Color bg_darker
Background colour - darker.
public static Color fg
Foreground colour.
public static Color act_highlight
Active strip object 'active' button colour.
public static Color focus_off_color
Active strip 'keyboard focus off' message colour.
public static int view_border_style
JdlView object border style.
public static int view_border_width
JdlView object border width.
public static int menu_button_border_width
Menu button border width.
public static int view_frame_border
View frame border type.
public static int view_frame_border_width
View frame border width.
public static final JdlViewObject STANDARD_INPUT
Dummy object for standard input.
public static final JdlViewObject TIMEOUT_RETURN
Dummy object for timeout.
public static final JdlViewObject CLOSE_RETURN
Dummy object for window close.
public static final int VERTICAL_PAIR
Vertical pair.
public static final int HORIZONTAL_PAIR
Horizontal pair.
public static final int EXPAND_BOTH
Expand both children.
public static final int FIX_LEFT
Fix left hand child, expand right child.
public static final int FIX_TOP
Fix top child, expand bottom child.
public static final int FIX_RIGHT
Fix right hand child, expand left child.
public static final int FIX_BOTTOM
Fix bottom child, expand top child.
public static final int FIX_LEFT_LEFT
Left/left justify.
public static final int FIX_TOP_TOP
Top/top justify.
public static final int FIX_LEFT_RIGHT
Left/right justify.
public static final int FIX_TOP_BOTTOM
Top/bottom justify.
public static final int FIX_RIGHT_RIGHT
Right/right justify.
public static final int FIX_BOTTOM_BOTTOM
Bottom/bottom justify.
public static final int IGNORE_CLOSE
Frame closure option: Ignore close.
public static final int PROGRAM_CLOSE
Frame closure option: Handle in program.
public static final int WARN_IGNORE
Frame closure option: Warn but ignore.
public static final int WARN_EXIT
Frame closure option: Warn wit exit option.
public static final int EXIT
Frame closure option: Unconditional exit.

3.2.2.4 Constructor

3.2.2.4.1 Introduction

A single constructor is available.

Constructor:

Default constructor

3.2.2.4.2 Default constructor

Constructs a JdlView management object for a program. Only one such object should be constructed for a program and it must be made prior to making any of the JdlView objects.

Constructor Definition:
public JdlViewManager()
Parameters List:
none

3.2.2.5 Class Method

3.2.2.5.1 Introduction

This method tests to see whether or not a JdlViewManager object has been created.

Method:

View management - isView

3.2.2.5.2 View management - isView

This method is used when JdlView objects are created to determine whether or not they are being run under the control of JdlView management.

Method Definition:
public static boolean isView()
Parameters List:
none
Method Return:
Returns true if under JdlView management (i.e. a JdlViewManager object has been constructed) or false if not.

3.2.2.6 Operational Methods

3.2.2.6.1 Introduction

This section contains the main methods used when handling JdlView objects. Methods are available for adding or deleting view objects, for handling JdlView action events.

Methods:

Add JdlView object - addViewObject
Raise view object - raiseViewObject
Lower view object - lowerViewObject
Remove JdlView Object - removeViewObject
Delete JdlView Object - deleteViewObject
JdlView event handling - waitForViewActions
Return view handle - returnActionViewHandle

3.2.2.6.2 Add JdlView object - addViewObject

This method adds a JdlView object to the managed list.

Method Definition:
public int addViewObject (String name, JdlViewObject vob, JdlViewObjectFrame parent, int vh, int x, int y, int close)
Parameters List:
name
A name to be used to identify a JdlView object.
vob
The JdlView object.
parent
The parent frame - if null a new parent base frame will be constructed for this JdlView object.
vh
A unique integer number (handle) by which this JdlView object is to be identified (used in particular with event handling).
x
'x' coordinate for the view-object relative to the parent if given. If no parent is specified then it will be used as the preferred 'x' position on the screen for the new parent base frame which will be created for the object.
y
'y' coordinate for the view-object relative to the parent if given. If no parent is specified then it will be used as the preferred 'y' position on the screen for the new parent base frame which will be created for the object.
close
Frame closure option if the object added is a base frame or if a new frame is generated internally:
= 0, Ignore closure
= 1, Handle close in program via waitForViewActions(..)
= 2, Warn user but ignore closure
= 3, Exit program if chosen after warning
= 4, Exit program unconditionally
may use IGNORE_CLOSE, PROGRAM_CLOSE, WARN_IGNORE, WARN_EXIT, EXIT.

3.2.2.6.3 Raise view object - raiseViewObject

This method raises (brings to the front) a managed view object's parent base frame.

Method Definition:
public void raiseViewObject(JdlViewObject vobj)
Parameters List:
none

3.2.2.6.4 Lower view object - lowerViewObject

This method lowers (puts to the back) a managed view object's parent base frame.

Method Definition:
public void lowerViewObject(JdlViewObject vobj)
Parameters List:
none

3.2.2.6.5 Remove JdlView Object - removeViewObject

This method removes a JdlView object and any of its children from the JdlView manager list (and hides their windows) and deletes any internally generated parent base frame.

Method Definition:
public void removeViewObject (JdlViewObject vobj)
Parameters List:
vobj
The JdlView object to be removed.

3.2.2.6.6 Delete JdlView Object - deleteViewObject

This method deletes a JdlView object and any of its children and any internally generated parent base frame.

Method Definition:
public void deleteViewObject (JdlViewObject vobj)
Parameters List:
vobj
The JdlView object to be deleted.

3.2.2.6.7 JdlView event handling - waitForViewActions

An important part of the JdlView management is the event handling mechanism. This is done through a call from the application program to the waitForViewActions(..) method. When this method is called, the user specifies a list of the JdlView objects from which the program is ready to receive input ('active' JdlView objects). The method does not return until input is received from one of these active objects. When this occurs the method returns the Jdlview object from which the input was received so that it can be processed by the program. Each JdlView object has methods enabling details of the type of input to be determined.

There are additional options to allow for non-blocking keyboard input (from the standard input stream) in addition to any currently active JdlView object input and to allow for a timeout return after a specified period if no input has been made. A JdlViewTimer object may also be used to initiate a return from the method after a given time interval.

Note that there is also a mechanism by which an interrupt may be generated to trigger a return from the method.

Method Definition:
synchronized public JdlViewObject waitForViewActions ( JdlViewObject[] view_arr, int num_obj, boolean rd_term, boolean accept_close, JdlViewObject raise_obj, long timeout)
Parameters List:
view_arr
Array of JdlView objects which are to be made active and from which input may currently be received.
num_obj
The number of JdlView objects in the list.
rd_term
If true, allow for non-blocking reads from the standard input stream in addition to any active JdlView object input; if false do not.
accept_close
If true, return if close requested on any window which was set with the 'PROGRAM_CLOSE' option. If false, ignore all such close window requests.
raise_obj
A view-object to be raised to the front when the method is called. May be null if not required. The view object need not necessarily be one of those in the current 'view_arr' array. If specified, a request will also be made to set the keyboard focus to this object. If null, a raise and keyboard focus request will be made for the last object in the 'view_arr' list.
timeout
Specifies the number of milliseconds after which the method will return if no input was received. If 0, then there will be no timeout.
Method Return:
The view-object from which the input was received. For the special case of terminal input the JdlView object returned will be the JdlViewDummy dummy object accessible as the public variable STANDARD_INPUT. Similarly for a timeout return the JdlView object returned will be the JdlViewDummy dummy object accessible as the public variable TIMEOUT_RETURN. If there was an interrupt a null will be returned.

3.2.2.6.8 Return view handle - returnActionViewHandle

This method returns the view handle associated with the action giving rise to the latest return from the waitForViewActions(..) method. Usually this will be the view handle for the view object returned. If the return was for one of the special cases then the view handle will be as follows:
JdlDummy view object STANDARD_INPUT, Returned view handle will be 0
JdlDummy view object TIMEOUT_RETURN, Returned view handle will be 0
JdlDummy view object CLOSE_RETURN, Returned view handle will either be that of the base frame if this was added as a view object or the view handle of the object for which the base frame was generated internally (null parent case for addViewObject(..))

Method Definition:
public int returnActionViewHandle()
Parameters List:
none

3.2.2.7 Special Methods

3.2.2.7.1 Introduction

This section includes some methods which may be required in some circumstances.

Methods:

Get JdlView object handle - getViewObjectFromHandle
Get base frame - getParentBaseFrame
Enable interrupt - allowInterrupt
Interrupt wait - interrupt

3.2.2.7.2 Get JdlView object handle - getViewObjectFromHandle

This method returns the View Object from its handle.

Method Definition:
public JdlViewObject getViewObjectFromHandle (int vh)
Parameters List:
vh
The JdlView object handle.
Method Return:
The JdlView object, null if handle not found.

3.2.2.7.3 Get base frame - getParentBaseFrame

This method returns the associated base frame for a registered JdlView object.

Method Definition:
public JdlViewObjectFrame getParentBaseFrame (JdlViewObject vobj)
Parameters List:
vobj
The Jdlview object.
Method Return:
The associated base frame (null if 'vobj' not found).

3.2.2.7.4 Enable interrupt - allowInterrupt

This method sets the flag to allow/disallow interrupts using the interrupt(..) method.

Method Definition:
public void allowInterrupt(boolean flag)
Parameters List:
flag
If true, allow interrupts via call to interrupt(..) method, if false do not.

3.2.2.7.5 Interrupt wait - interrupt

If called, this method interrupts the waitForViewActions(..) method - only has an effect if the allowInterrupt(..) method has been called with a flag of true. If active, the waitForViewActions(..) method will return with a null.

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

3.2.2.8 Calculate Layout

3.2.2.8.1 Introduction

This section has methods for calculating a layout and setting sizes and positions for a set of JdlView objects where several objects are to be fitted together to give a tidy looking layout. The basic look of the layout may be preserved and new positions and sizes automatically calculated if the size requirements of any of the individual objects are changed. The basic procedure requires that the layout is defined in terms of pairs of objects and/or previously defined pairs. Each newly defined pair may be in a horizontal or vertical direction. Minimum size requirements are given for the individual objects and recursive procedures are used to calculate the overall size requirement for the layout and to reset the sizes and positions of the individual objects. In contrast to the standalone set of methods in the JdlViewLayout object, the methods here access JdlView objects which have been registered with the JdlView manager using the addViewObject(..) method; also the layout is also set as well as being calculated.

Methods:

Initialise layout - layoutInitialize
Set horizontal pair - layoutSetHorizontalPair
Set vertical pair - layoutSetVerticalPair
Set layout - layout
Get object size - getSingleLayoutSize
Get object position - getSingleLayoutPosition

3.2.2.8.2 Initialise layout - layoutInitialize

This method is used to initialise the layout methods prior to defining and calculating a JdlView object based layout.

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

3.2.2.8.3 Set horizontal pair - layoutSetHorizontalPair

This method is used to give details of a horizontal pair of JdlView objects and/or other pairs required in the layout.

Method Definition:
public boolean layoutSetHorizontalPair(String name, String child1, String child2, int hjust, double pcnt)
Parameters List:
name
A name which will be used to identify this pair.
child1
The name of the first (left hand) child.
child2
The name of the second (right hand) child.
hjust
Horizontal justification required:
= 1 Expand both children EXPAND_BOTH
= 2 Fix left, expand right FIX_LEFT
= 3 Expand left, fix right FIX_RIGHT
= 4 Left/left justify FIX_LEFT_LEFT
= 5 Left/right justify FIX_LEFT_RIGHT
= 6 Right/right justify FIX_RIGHT_RIGHT
pcnt
An approximate percentage of the total width of the pair to be occupied if both children are expanded.

3.2.2.8.4 Set vertical pair - layoutSetVerticalPair

This method is used to give details of a vertical pair of JdlView objects and/or other pairs required in the layout.

Method Definition:
public boolean layoutSetVerticalPair(String name, String child1, String child2, int vjust, double pcnt)
Parameters List:
name
A name which will be used to identify this pair.
child1
The name of the first (top) child.
child2
The name of the second (bottom) child.
vjust
Vertical justification required:
= 1 Expand both children EXPAND_BOTH
= 2 Fix top, expand bottom FIX_TOP
= 3 Expand top, fix bottom FIX_BOTTOM
= 4 Top/top justify FIX_TOP_TOP
= 5 Top/Bottom justify FIX_TOP_BOTTOM
= 6 Bottom/bottom justify FIX_BOTTOM_BOTTOM
pcnt
An approximate percentage of the total height of the pair to be occupied by the top child if both children are expanded.

3.2.2.8.5 Set layout - layout

This method calculates and sets the layout given the name of the top level pair defined for the layout.

Method Definition:
public Dimension layout (String name, JdlViewObjectFrame base_fr)
Parameters List:
name
Name of the top level pair of objects/pairs.
base_fr
The base frame for the layout.

3.2.2.8.6 Get object size - getSingleLayoutSize

This method returns the required size for a JdlView object after the layout has been calculated.

Method Definition:
public Dimension getSingleLayoutSize (JdlViewObject vobj)
Parameters List:
vobj
The JdlView object whose required size is to be found.

3.2.2.8.7 Get object position - getSingleLayoutPosition

This method returns the required position for a JdlView object after the layout has been calculated.

Method Definition:
public Point getSingleLayoutPosition (JdlViewObject vobj)
Parameters List:
vobj
The JdlView object whose required position is to be found.

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