net.sf.zig_project.gpl.common.gfx
Class WindowHandler

java.lang.Object
  net.sf.zig_project.gpl.common.gfx.WindowHandler

All Implemented Interfaces:

EventListener, WindowListener

public class WindowHandler

extends Object

implements WindowListener

WindowHandler is a highly convienent and versatile widget to manage shutting down a VM in a windowed session. Once every window has closed, and all WindowHandlers are marked safe for shut-down, a final call is made to System.exit(0). The requirement is that each window to be monitored must have a WindowHandler added as a WindowListener to it.

Implementation: Each WindowHandler is implemented as a counter of the number of open windows on the workspace, based on the number of windowOpened and windowClosed events dispatched. Internally, another reference counter is maintained counting the number of active WindowHandlers. On construction, a WindowHandler is initially active, and is not deactivated until it has counted all windows as closed, and the handler is marked as safetoexit (true by default); and is reactivated as soon as another window is opened.

This is well suited for single window test cases:

 public class Sample1 {
	public static void main(String[] args) {
		Frame f=new Frame("Example");
		Label l=new Label("Hi");
		f.add(l);
		new WindowHandler().APCS(f);}
 }

Another example would be for multi-window environments.

 public class Sample2 {
	private static final WindowHandler handler=new WindowHandler();
	public static void main(String[] args) {
		String[] labels={"Hi", "Hi there", "This is just one more example"};
		for (int i=labels.length-1; i>=0; i--) {
			Frame f=new Frame("Example "+(i+1));
			Label l=new Label(labels[i]);
			f.add(l);
			handler.APCS(f);}}
 }

Lastly, since these examples delegate exit calls to WindowHandler, we can trust WindowHandler to behave expectably when launching a subprocess within the same VM, for example:

 public class Sample3 {
	public static void main(String[] args) {
		Sample1.main(args);
		Sample2.main(args);}
 }

Another feature of WindowHandler are window centering methods. Java 1.4 introduces Window.setLocationRelativeTo(Component). However, these methods are considered to be more versatile in that they will make a best attempt for compatability in VMs as early as 1.1, but will utilize features in newer VMs to be as aware as possible of insets in the screen, as well as multi-monitor systems. Lastly, once a window is centered, it is checked to ensure that it fits on screen, and is shrunken if necessary.

These examples provide very simplistic windows. Often times however, it is necessary to perform some operation before actually allowing the VM to exit, or even allowing the Window to close. While it is possible to add a custom window listener to each window, in addition to a WindowHandler, the java specification does not document nor require an order in which window listeners are notified of events. For this reason, WindowHandler provides a constructor accepting a WindowListener. All events recieved by a WindowHandler are first delegated to the registered listener, allowing that listener to call the handler's setExitOnClose method if necessary. By default, the handler uses a BasicWindowListener to automatically close any window that posts a windowClosing event.

Version:

September 14, 2004

Author:

Frank Ziglar

Constructor Summary

WindowHandler()
Creates a default WindowHandler, which uses a BasicWindowListener

WindowHandler(WindowListener wl)
Creates a WindowHandler which will delegate all window events to the registered listener before continuing processing.

Method Summary

void	APCS(Window w) Add (this as a listener), Pack, Center, and Show
static void	centerWindow(Window w) General purpose: centers the window.
static void	centerWindowOnScreen(Window w) Centers the window within a screen.
static void	centerWindowOver(Window w, Component c) Centers the window ontop of the provided component.
static void	centerWindowOver(Window w, Rectangle r) Centers the window over a rectangular section of device space.
protected void	finalize() If this handler were active at the time of finalization, we might have a serious logic error, so it is best for now to deactivate it.
int	getOpenFrameCount() Returns the current number of frames counted by this handler as open.
void	setExitOnClose(boolean b) Instructs the WindowHandler whether or not it is safe to terminate the VM once all windows have been closed.
boolean	willExitOnClose() Returns the current state of the handler's safetoexit flag.
void	windowActivated(WindowEvent evt) Only passed to the registered listener.
void	windowClosed(WindowEvent evt) Decrements the number of open frames, if the source of the event is a frame, and possibly deactivates the handler.
void	windowClosing(WindowEvent evt) Only passed to the registered listener.
void	windowDeactivated(WindowEvent evt) Only passed to the registered listener.
void	windowDeiconified(WindowEvent evt) Only passed to the registered listener.
void	windowIconified(WindowEvent evt) Only passed to the registered listener.
void	windowOpened(WindowEvent evt) Activates the handler and increments the number of open frames, if the source of the event was a Frame.
boolean	wouldExitOnNextClose() Determines whether or not this handler would deactivate on the next windowClosed event.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WindowHandler

public WindowHandler(WindowListener wl)

Creates a WindowHandler which will delegate all window events to the registered listener before continuing processing.

WindowHandler

public WindowHandler()

Creates a default WindowHandler, which uses a BasicWindowListener

Method Detail

centerWindow

public static void centerWindow(Window w)

General purpose: centers the window. If the window has a parent, it is centered over that parent, otherwise it is centered on it's screen.

centerWindowOnScreen

public static void centerWindowOnScreen(Window w)

Centers the window within a screen. If the window already has a screen on which it resides, it is recentered in the same screen. Otherwise, it is centered in the default screen.

centerWindowOver

public static void centerWindowOver(Window w,
                                    Component c)

Centers the window ontop of the provided component. This method uses the registered location and screen of the component, and may be unpredictable if the component is not fully validated.

centerWindowOver

public static void centerWindowOver(Window w,
                                    Rectangle r)

Centers the window over a rectangular section of device space.

APCS

public final void APCS(Window w)

Add (this as a listener), Pack, Center, and Show

setExitOnClose

public void setExitOnClose(boolean b)

Instructs the WindowHandler whether or not it is safe to terminate the VM once all windows have been closed. If all windows have been terminated, and a call had previously been made setting this value to false, a further call to set this value to true will shut down the VM. However, it is safe to call this method immediately after the Handler has been initialized (before any windows have been opened).

See Also:

willExitOnClose()

finalize

protected void finalize()
                 throws Throwable

If this handler were active at the time of finalization, we might have a serious logic error, so it is best for now to deactivate it.

Throws:

Throwable

willExitOnClose

public boolean willExitOnClose()

Returns the current state of the handler's safetoexit flag.

See Also:

setExitOnClose(boolean)

getOpenFrameCount

public int getOpenFrameCount()

Returns the current number of frames counted by this handler as open.

wouldExitOnNextClose

public boolean wouldExitOnNextClose()

Determines whether or not this handler would deactivate on the next windowClosed event.

windowActivated

public void windowActivated(WindowEvent evt)

Only passed to the registered listener.

Specified by:

windowActivated in interface WindowListener

windowDeactivated

public void windowDeactivated(WindowEvent evt)

Only passed to the registered listener.

Specified by:

windowDeactivated in interface WindowListener

windowDeiconified

public void windowDeiconified(WindowEvent evt)

Only passed to the registered listener.

Specified by:

windowDeiconified in interface WindowListener

windowIconified

public void windowIconified(WindowEvent evt)

Only passed to the registered listener.

Specified by:

windowIconified in interface WindowListener

windowOpened

public void windowOpened(WindowEvent evt)

Activates the handler and increments the number of open frames, if the source of the event was a Frame.

Specified by:

windowOpened in interface WindowListener

windowClosing

public void windowClosing(WindowEvent evt)

Only passed to the registered listener.

Specified by:

windowClosing in interface WindowListener

windowClosed

public void windowClosed(WindowEvent evt)

Decrements the number of open frames, if the source of the event is a frame, and possibly deactivates the handler.

Specified by:

windowClosed in interface WindowListener