John W. Campbell
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
- Package:
- Jdl.JdlView;
- Class name:
- JdlViewManager
- Class definition:
- public class JdlViewManager
- Extends:
- Object
- Implements:
- ActionListener
WindowListener
Runnable
- Actions:
- none
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.
A single constructor is available.
Constructor:
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
This method tests to see whether or not a JdlViewManager object has been
created.
Method:
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.
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
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.
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
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
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.
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.
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.
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
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
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.
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).
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.
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
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
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
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.
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.
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.
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.
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