jewl
Class Window

java.lang.Object
  jewl.Window

Direct Known Subclasses:

Container, Control

public abstract class Window

extends java.lang.Object

The abstract base class for all other JEWL window classes. Apart from top-level windows (frames and dialogs), every window is contained inside another window. The origin of the top-left corner of a window enclosed in another window (the parent window) is expressed by an (x,y) coordinate (two integers giving the distance in pixels across, and then down, from the top-left corner of the parent window). Negative values for the coordinates allow these offsets to be measured from the bottom or right edges of the parent window rather than the top and left; for example, an origin of (-20,5) means an origin located 20 pixels in from the right-hand edge of the parent window and 5 pixels down from the top edge.

Heights and widths can also be specified relative to the size of the parent window. Positive values are used for absolute heights and widths, whereas zero or negative values are taken to be relative to the height or width of the parent window. Zero means the same height or width as the parent window, and a negative value -n means n pixels less than the corresponding dimension of the parent window.

Coordinates which are relative to the parent window are adjusted if the size of the parent window changes. For example, a window with an origin of (5,-50) and a width of -10 will be adjusted so that if the size of the parent window is changed, the enclosed window will be adjusted so that its top-left corner is still positioned 5 pixels from the left of the parent window's left edge, 50 pixels up from the parent window's bottom edge, and the width will be 10 pixels less than the width of the parent window.

Methods inherited from Window allow you to show or hide a window, test whether it is visible on the screen, get or set its size or position, and get or set the font it uses.

Method Summary

void	addEventListener(EventListener listener) Add an event listener associated with this window.
static boolean	commandAvailable() Test if a new command code is available.
static char	getCommand() Get the most recently generated command code.
Font	getFont() Get the current font used in this window.
int	getHeight() Get the current height of this window.
int	getID() Get the ID number for this window.
int	getLeft() Get the coordinate of the left edge of this window relative to the left of its parent window.
static int	getScreenHeight() Get the height of the entire screen.
static int	getScreenWidth() Get the width of the entire screen.
static Window	getSource() Get a reference to the window which generated the most recent command.
int	getTop() Get the coordinate of the top edge of this window relative to the top of its parent window.
int	getWidth() Get the current width of this window.
void	hide() Hide this window.
static void	init() Register the calling thread as a user interface thread.
boolean	isVisible() Test if this window is visible.
static char	nextCommand() Wait for a command code to be generated by any window.
Container	parent() Get the parent window enclosing this one.
Container	root() Get the top-level window enclosing this one.
void	setFont(java.awt.Font font) Set the font to be used for any text in this window.
void	setID(int id) Set the ID number for this window.
void	setLocation(int left, int top) Set the location of this window within the parent window.
void	setSize(int width, int height) Set the size of this window.
void	show() Show this window.
void	show(boolean visible) Show or hide this window.

Methods inherited from class java.lang.Object

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

Method Detail

init

public static void init()

Register the calling thread as a user interface thread. A program using this package will be terminated automatically when the last thread dies which has created a window. Calling this method allows threads which do not create any windows to keep the program alive as long as they are alive.

addEventListener

public void addEventListener(EventListener listener)

Add an event listener associated with this window. This allows a window's change of state to be dealt with directly, rather than relying entirely on windows generating command codes.

Parameters:

listener - an event listener.which implements the EventListener interface.

setID

public void setID(int id)

Set the ID number for this window. The ID number is provided so that other non-visual implementations of JEWL can identify specific windows. For example, an automated assessment system could use this to identify and interact with particular controls, regardless of the visual layout of the user interface. It can only be set once; calling this method after the ID has been set to a non-zero value will have no effect.

Parameters:

id - the desired ID number.

getID

public int getID()

Get the ID number for this window. The ID number is zero by default, but it can be used to provide a way for other implementations of JEWL to identify specific windows.

Returns:

The ID number for this window.

See Also:

setID(int)

show

public void show(boolean visible)

Show or hide this window.

Parameters:

visible - true if this window should be made visible, false if it should be hidden.

show

public void show()

Show this window. This is the same as show(true).

See Also:

show(boolean)

hide

public void hide()

Hide this window. This is the same as show(false).

See Also:

show(boolean)

isVisible

public boolean isVisible()

Test if this window is visible.

Returns:

True if this window is visible, false otherwise.

setSize

public void setSize(int width,
                    int height)

Set the size of this window. A non-positive width or height will be taken as being relative to the width or height of the parent window. For example, a width of 0 will set the width of this window to be the same as the width of its parent window; a width of -5 will set the width of this window to be 5 pixels less than the width of its parent window. If the parent window is resized, this window will also be resized as necessary.

Parameters:

width - the desired width in pixels.

height - the desired height in pixels.

setLocation

public void setLocation(int left,
                        int top)

Set the location of this window within the parent window. A negative coordinate will be taken relative to the opposite edge of the parent window. For example, specifying the top of the window as -50 will set the top edge of this window to 50 pixels above the bottom of its parent window. If the parent window is resized, this window will also be resized as necessary.

Parameters:

left - the desired position of the left edge of this window relative to the left edge of the parent window, or to the right edge if the value given is negative, measured in pixels.

top - the desired position of the top edge of this window relative to the top edge of the parent window, or to the bottom edge if the value given is negative, measured in pixels.

getTop

public int getTop()

Get the coordinate of the top edge of this window relative to the top of its parent window.

Returns:

The coordinate of the top edge of this window in pixels.

getLeft

public int getLeft()

Get the coordinate of the left edge of this window relative to the left of its parent window.

Returns:

The coordinate of the left edge of this window in pixels.

getWidth

public int getWidth()

Get the current width of this window. This will be the actual (positive) width in pixels at the time this method is called.

Returns:

The current width of this window in pixels.

getHeight

public int getHeight()

Get the current height of this window. This will be the actual (positive) height in pixels at the time this method is called.

Returns:

The current height of this window in pixels.

getScreenWidth

public static int getScreenWidth()

Get the width of the entire screen. This is a static method which allows specific screen-based positions to be calculated for top-level windows.

Returns:

The width of the screen in pixels.

getScreenHeight

public static int getScreenHeight()

Get the height of the entire screen. This is a static method which allows specific screen-based positions to be calculated for top-level windows.

Returns:

The height of the screen in pixels.

setFont

public void setFont(java.awt.Font font)

Set the font to be used for any text in this window.

Parameters:

font - the desired font to be applied. If this is null, the parent window's font will be used. Although this is specified as a java.awt.Font, you can use jewl.Font instead.

See Also:

Font

getFont

public Font getFont()

Get the current font used in this window.

Returns:

The current font used in this window.

parent

public Container parent()

Get the parent window enclosing this one. If this window is a top-level window, this method returns null.

Returns:

The parent window to which this window is attached.

root

public Container root()

Get the top-level window enclosing this one. If this window is a top-level window, this method returns a reference to this window.

Returns:

The top-level container window to which this window is attached.

nextCommand

public static char nextCommand()

Wait for a command code to be generated by any window. This is the character specified in the constructor for windows which generate commands (top-level windows, buttons, menu items and canvases). If at least one frame has been created but no frames have been made visible yet, the first frame that was created will be shown. Otherwise, an exception will be generated if no windows are visible, since no events can be generated without a visible window.

Returns:

The command code that was generated.

Throws:

java.lang.IllegalStateException - if no windows are visible when the method is called

getSource

public static Window getSource()

Get a reference to the window which generated the most recent command. If multiple copies of the same window have been used, this can be used to identify the particular instance of the window that generated the command. For example, if there are several copies of a frame, each of which contains an identical button, the buttons will generate identical command codes. You can identify the frame containing the button which was pressed using Window.getSource().root()

    if (Window.getSource().root() == myFrame) {
        ...
      }
  

Returns:

A reference to the window which generated the most recent command.

See Also:

root()

getCommand

public static char getCommand()

Get the most recently generated command code.

Returns:

The command code.

commandAvailable

public static boolean commandAvailable()

Test if a new command code is available. This tests if a command has been generated (by closing a window, pressing a button or selecting a menu item) since the last time that nextCommand() was called.

Returns:

True if a command code is available, false otherwise. The command code can be retrieved using nextCommand().

See Also:

nextCommand()