PIRL.Viewers
Class View_Locator

java.lang.Object
  PIRL.Viewers.View_Locator

public class View_Locator
extends Object

A View_Locator is used to manage the location of a Window view on the Display relative to a base location.

Version:

1.15

Author:

Bradford Castalia, UA/PIRL

Field Summary

static int	BOTTOM Specifies vertical positioning of a view relative to the bottom side of the base.
static int	CENTER Specifies centered positioning of a view relative to the base.
static Insets	Default_Frame_Margins The default top, left, bottom and right margins to be used with the base dimensions when calculating the relocation position of a view: 0, 0, 0, 0.
static String	DEFAULT_LAF The default Look-and-Feel for Select_LAF(String).
static Point	Default_Offsets The default horizontal and vertical offsets relative to a base to apply to a view when it is relocated: 20x, 20y.
static Point	Default_Orientation The default orientation: x: LEFT | INWARD, y: TOP | INWARD.
static Point	Default_Warp_Location The default location to position a view if it would otherwise overlap a side of the display: 175x, 75y.
static Point	Default_Warp_Offsets The default horizontal and/or vertical offsets to apply to the Warp_Location when it is moved along the corresponding axis.
static int	DIRECTION Selects the direction relative to the base orientation policy.
static int	INWARD Specifies positioning of a view relative to the inside side of the base.
static int	LEFT Specifies horizontal positioning of a view relative to the left side of the base.
static int	OUTWARD Specifies positioning of a view relative to the outside side of the base.
static int	RIGHT Specifies horizontal positioning of a view relative to the right side of the base.
static int	SIDE Selects the base side orientation policy.
static int	TOP Specifies vertical positioning of a view relative to the top side of the base.

Constructor Summary

View_Locator()
Constructs a View_Locator using default policies.

View_Locator(int horizontal_orientation, int vertical_orientation)
Constructs a View_Locator with the specified orientation policies.

View_Locator(View_Locator locator)
Constructs a View_Locator as a copy of another View_Locator.

View_Locator(Window view)
Constructs a View_Locator using default policies, and positions the view to the Warp_Location.

View_Locator(Window view, View_Locator locator)
Constructs a View_Locator using another View_Locator for Policies, and positions the view to the Warp_Location.

Method Summary

Rectangle	Display() Gets the Rectangle for the current display bounds.
View_Locator	Display(Rectangle rectangle) Sets the boundary to use when views are relocated.
Insets	Frame_Margins() Gets the margins to be use for a view frame.
View_Locator	Frame_Margins(Insets margins) Sets the margins around a view frame to be used when calculating a view relocation position.
View_Locator	Frame_Margins(int top, int left, int bottom, int right) Sets the margins around a view frame to be used when calculating a view relocation position.
int	Horizontal() Gets the horizontal orientation policies.
View_Locator	Horizontal(int policies) Sets the horizontal orientation policies.
Point	Offsets() Gets the horizontal and vertical offsets to be applied when a view is relocated.
View_Locator	Offsets(int x, int y) Sets the horizontal and vertical offsets to be applied when a view is relocated.
View_Locator	Offsets(Point offsets) Sets the horizontal and vertical offsets to be applied when a view is relocated.
Point	Orientation() Gets the orientation polices.
View_Locator	Orientation(int x, int y) Sets the orientation policies when relocating a view relative to a base.
View_Locator	Orientation(Point orientation) Sets the orientation policies when relocating a view relative to a base.
View_Locator	Policies(View_Locator policies) Sets the view relocation polices for this View_Locator from the policies of another View_Locator.
void	Relocate(Window view, Point location) Relocates a view relative to a base Point.
void	Relocate(Window view, Rectangle base_bounds) Relocates a view relative to base bounds.
void	Relocate(Window view, Window base) Relocates a view relative to a base view.
Rectangle	Screen() Gets the Rectangle for the current effective screen bounds.
View_Locator	Screen(Rectangle rectangle) Sets the screen boundary to use for all View_Locators.
static String	Select_LAF(String LAF_name) Select a GUI Look-and_Feel.
static String	Select_LAF(String LAF_name, boolean apply_to_window_frames) Select a GUI Look-and_Feel.
String	toString() Provides a description of the policies and parmeters of this View_Locator.
int	Vertical() Gets the vertical orientation policies.
View_Locator	Vertical(int policies) Sets the vertical orientation policies.
Point	Warp_Location() Gets the current location to which to "warp" a view if relocating it would cause it to overlap the display bounds.
View_Locator	Warp_Location(int x, int y) Sets the location on the screen to which to "warp" a view if relocating it would cause it to overlap the display bounds.
View_Locator	Warp_Location(Point location) Sets the location on the screen to which to "warp" a view if relocating it would cause it to overlap the display bounds.
Point	Warp_Offsets() Gets the horizontal and vertical offsets to be applied when the warp location is automatically moved.
View_Locator	Warp_Offsets(int x, int y) Sets the horizontal and vertical offsets to be applied when the warp location is automatically moved.
View_Locator	Warp_Offsets(Point offsets) Sets the horizontal and vertical offsets to be applied when the warp location is automatically moved.

Methods inherited from class java.lang.Object

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

Field Detail

LEFT

public static final int LEFT

Specifies horizontal positioning of a view relative to the left side of the base.

See Also:

Constant Field Values

RIGHT

public static final int RIGHT

Specifies horizontal positioning of a view relative to the right side of the base.

See Also:

Constant Field Values

SIDE

public static final int SIDE

Selects the base side orientation policy.

See Also:

Constant Field Values

TOP

public static final int TOP

Specifies vertical positioning of a view relative to the top side of the base.

See Also:

Constant Field Values

BOTTOM

public static final int BOTTOM

Specifies vertical positioning of a view relative to the bottom side of the base.

See Also:

Constant Field Values

CENTER

public static final int CENTER

Specifies centered positioning of a view relative to the base.

See Also:

Constant Field Values

OUTWARD

public static final int OUTWARD

Specifies positioning of a view relative to the outside side of the base.

See Also:

Constant Field Values

INWARD

public static final int INWARD

Specifies positioning of a view relative to the inside side of the base.

See Also:

Constant Field Values

DIRECTION

public static final int DIRECTION

Selects the direction relative to the base orientation policy.

See Also:

Constant Field Values

Default_Orientation

public static Point Default_Orientation

The default orientation: x: LEFT | INWARD, y: TOP | INWARD.

Default_Offsets

public static Point Default_Offsets

The default horizontal and vertical offsets relative to a base to apply to a view when it is relocated: 20x, 20y.

Default_Frame_Margins

public static Insets Default_Frame_Margins

The default top, left, bottom and right margins to be used with the base dimensions when calculating the relocation position of a view: 0, 0, 0, 0.

Default_Warp_Location

public static Point Default_Warp_Location

The default location to position a view if it would otherwise overlap a side of the display: 175x, 75y.

Default_Warp_Offsets

public static Point Default_Warp_Offsets

The default horizontal and/or vertical offsets to apply to the Warp_Location when it is moved along the corresponding axis.

DEFAULT_LAF

public static final String DEFAULT_LAF

The default Look-and-Feel for Select_LAF(String).

See Also:

Constant Field Values

Constructor Detail

View_Locator

public View_Locator(Window view,
                    View_Locator locator)

Constructs a View_Locator using another View_Locator for Policies, and positions the view to the Warp_Location.

Parameters:

view - A Window to position (may be null).

locator - A View_Locator used to set the Policies of the new View_Locator. If null then default values will be used.

View_Locator

public View_Locator(Window view)

Constructs a View_Locator using default policies, and positions the view to the Warp_Location.

Parameters:

view - The Window to be positioned.

View_Locator

public View_Locator(View_Locator locator)

Constructs a View_Locator as a copy of another View_Locator.

Parameters:

locator - The View_Locator to copy.

View_Locator

public View_Locator(int horizontal_orientation,
                    int vertical_orientation)

Constructs a View_Locator with the specified orientation policies.

Parameters:

horizontal_orientation - The horizontal Orientation policies.

vertical_orientation - The vertical Orientation policies.

View_Locator

public View_Locator()

Constructs a View_Locator using default policies.

Method Detail

Policies

public View_Locator Policies(View_Locator policies)

Sets the view relocation polices for this View_Locator from the policies of another View_Locator.

Parameters:

policies - The View_Locator from which to copy all relocation parameters. If null, defaults will be applied.

Returns:

This View_Locator.

Display

public View_Locator Display(Rectangle rectangle)

Sets the boundary to use when views are relocated.

The boundary does not need to be coincident with the real screen boundaries. For example, if it is desirable to allow a view to be relocated such that it would overlap the screen display, use a Rectangle that is positioned and/or sized beyond the screen bounds by the maximum amount of overlap to be allowed.

Parameters:

rectangle - The Rectangle specifying the bounds of the effective display. If null, then the display boundary will be reset to the boundary of the screen.

Returns:

This View_Locator.

Display

public Rectangle Display()

Gets the Rectangle for the current display bounds.

Returns:

A Rectangle describing the current display bounds. Note: This will be null if the display bounds have not yet been determined.

Screen

public View_Locator Screen(Rectangle rectangle)

Sets the screen boundary to use for all View_Locators.

Normally this is automatically found by using GraphicsConfiguration of the first view encountered.

The boundary does not need to be coincident with the real screen boundaries. For example, if it is desirable to allow a view to be relocated such that it would overlap the screen display, use a Rectangle that is positioned and/or sized beyond the screen bounds by the maximum amount of overlap to be allowed.

Parameters:

rectangle - The Rectangle specifying the bounds of the effective screen. If null, then the screen boundary will be reset using the GraphicsConfiguration of the next view encountered.

Returns:

This View_Locator.

Screen

public Rectangle Screen()

Gets the Rectangle for the current effective screen bounds.

Returns:

A Rectangle describing the current effective screen bounds. Note: This will be null if the screen bounds have not yet been determined.

Orientation

public View_Locator Orientation(Point orientation)

Sets the orientation policies when relocating a view relative to a base.

The values used may be a combination, by ORing, of:

• x (horizontal)

  LEFT, RIGHT or CENTER

  Locate the view relative to the left or right side or center of the base.

  OUTWARD or INWARD

  Locate the view towards the inside or ourside of the base.

• y (vertical)

  TOP, BOTTOM orCENTER

  Locate the view relative to the top, bottom or center of the base.

  OUTWARD or INWARD

  Locate the view towards the inside or ourside of the base.

Parameters:

orientation - The orientation policies value.

Returns:

This View_Locator.

Orientation

public View_Locator Orientation(int x,
                                int y)

Sets the orientation policies when relocating a view relative to a base.

Parameters:

x - The horizontal relocation policies.

y - The vertical relocation policies.

See Also:

Orientation(Point)

Orientation

public Point Orientation()

Gets the orientation polices.

The values may be examined by ANDing with the SIDE and comparing with the LEFT/RIGHT/CENTER or TOP/BOTTOM/CENTER constants, and/or ANDing with the DIRECTION and comparing with the OUTWARD/INWARD constants.

Returns:

The orientation policies as a Point of x and y values.

Horizontal

public View_Locator Horizontal(int policies)

Sets the horizontal orientation policies.

Parameters:

policies - A horizontal orientation value.

Returns:

This View_Locator.

See Also:

Orientation(Point)

Horizontal

public int Horizontal()

Gets the horizontal orientation policies.

Returns:

A horizontal orientation value.

See Also:

Orientation(Point)

Vertical

public View_Locator Vertical(int policies)

Sets the vertical orientation policies.

Parameters:

policies - Vertical orientation policies.

Returns:

This View_Locator.

See Also:

Orientation(Point)

Vertical

public int Vertical()

Gets the vertical orientation policies.

Returns:

Either TOP or BOTTOM or-ed with either INWARD or OUTWARD.

See Also:

Orientation(Point)

Warp_Location

public View_Locator Warp_Location(Point location)

Sets the location on the screen to which to "warp" a view if relocating it would cause it to overlap the display bounds.

Parameters:

location - The setLocation Point to use if a view is warped.

Returns:

This View_Locator.

Warp_Location

public View_Locator Warp_Location(int x,
                                  int y)

Sets the location on the screen to which to "warp" a view if relocating it would cause it to overlap the display bounds.

Parameters:

x - The horizontal setLocation Point to use if a view is warped.

y - The vertical setLocation Point to use if a view is warped.

Returns:

This View_Locator.

See Also:

Component.setLocation(Point)

Warp_Location

public Point Warp_Location()

Gets the current location to which to "warp" a view if relocating it would cause it to overlap the display bounds.

Returns:

The Point for the current warp location.

Offsets

public View_Locator Offsets(Point offsets)

Sets the horizontal and vertical offsets to be applied when a view is relocated.

Parameters:

offsets - The Point containing the horizontal (x) and vertical (y) offsets.

Returns:

This View_Locator.

See Also:

Offsets(int, int)

Offsets

public View_Locator Offsets(int x,
                            int y)

Sets the horizontal and vertical offsets to be applied when a view is relocated.

Parameters:

x - The horizontal offset amount.

y - The vertical offset amount.

Returns:

This View_Locator.

See Also:

Offsets(Point)

Offsets

public Point Offsets()

Gets the horizontal and vertical offsets to be applied when a view is relocated.

Returns:

The Point containing the horizontal (x) and vertical (y) offsets.

Warp_Offsets

public View_Locator Warp_Offsets(Point offsets)

Sets the horizontal and vertical offsets to be applied when the warp location is automatically moved.

Parameters:

offsets - The Point containing the horizontal (x) and vertical (y) offsets.

Returns:

This View_Locator.

Warp_Offsets

public View_Locator Warp_Offsets(int x,
                                 int y)

Sets the horizontal and vertical offsets to be applied when the warp location is automatically moved.

Parameters:

x - The horizontal offset amount.

y - The vertical offset amount.

Returns:

This View_Locator.

Warp_Offsets

public Point Warp_Offsets()

Gets the horizontal and vertical offsets to be applied when the warp location is automatically moved.

Returns:

The Point containing the horizontal (x) and vertical (y) offsets.

Frame_Margins

public View_Locator Frame_Margins(Insets margins)

Sets the margins around a view frame to be used when calculating a view relocation position.

Parameters:

margins - Insets providing the top, left, bottom, and right margins.

Returns:

This View_Locator.

Frame_Margins

public View_Locator Frame_Margins(int top,
                                  int left,
                                  int bottom,
                                  int right)

Sets the margins around a view frame to be used when calculating a view relocation position.

Parameters:

top - The margin for the top side of a frame.

left - The margin for the left side of a frame.

bottom - The margin for the bottom side of a frame.

right - The margin for the right side of a frame.

Returns:

This View_Locator.

Frame_Margins

public Insets Frame_Margins()

Gets the margins to be use for a view frame.

Returns:

Insets providing the top, left, bottom, and right margins.

toString

public String toString()

Provides a description of the policies and parmeters of this View_Locator.

Overrides:

toString in class Object

Returns:

A descriptive String (not new-line terminated).

Relocate

public void Relocate(Window view,
                     Window base)

Relocates a view relative to a base view.

Parameters:

view - The Window to be relocated on the screen.

base - The Window to use as the base bounds reference.

See Also:

Orientation(Point), Offsets(Point), Display(Rectangle), Warp_Location(Point), Warp_Offsets(Point), Frame_Margins(Insets), Component.setLocation(Point), Relocate(Window, Rectangle)

Relocate

public void Relocate(Window view,
                     Rectangle base_bounds)

Relocates a view relative to base bounds.

The view location coordinates are adjusted. The horizontal location is changed according to the LEFT, RIGHT or CENTER horizontal positioning policies and the vertical location is changed according to the TOP, BOTTOM or CENTER vertical positioning policies.

Centering policies set the view location such that the center of the view is aligned with the center of the base. N.B.: Centering polices ignore the direction of the orientation and do not use offset values.

Other policies offset the view location either INWARD or OUTWARD relative to the LEFT or RIGHT and/or TOP or BOTTOM sides of the base location coordinates. OUTWARD motion positions the view outside of the base adjacent to the specified side, plus that side's frame margin, aligned with the top (for horizonatal motion) or left (for vertical motion) side of the base before applying the offsets. INWARD motion positions the view towards the inside of the base adjacent to the specified sides before applying the offsets. Note that the offset values may be positive, negative or zero.

For example, to produce the effect of horizontal, top aligned window tiling for a View Window relative to a Base Window:

        View_Locator locator = new View_Locator ();
        locator
                .Offsets (0, 0)
                .Horizontal (View_Locator.RIGHT | View_Locator.OUTWARD)
                .Vertical   (View_Locator.TOP   | View_Locator.INWARD);
        locator.Relocate (View, Base);

After the view location coordinates have been offset the view boundary is checked for having been repositioned across a Display boundary. If it has, then it is "warped" to the current Warp_Location. This position is intended to keep the view from overlapping a boundary. However, if the view is larger than the display bounds then it is placed against the left and/or top display boundary according to which dimensions are too large to fit. Each time a view is warped the current Warp_Location is moved horizontally by the Warp_Offsets.y amount. If this new position crosses a display boundary it is wrapped around to the other boundary and then the vertical position is also offset. When the vertical position crosses a boundary it is wrapped around to the other boundary. The movement of the Warp_Location is done to help prevent warped views from being positioned directly on top of another warped view.

Once the view relocation position has been determined the view is moved to that location on the screen.

Parameters:

view - The Window to be relocated on the screen.

base_bounds - The Rectangle to use as a relative reference.

See Also:

Orientation(Point), Offsets(Point), Display(Rectangle), Warp_Location(Point), Warp_Offsets(Point), Frame_Margins(Insets), Component.setLocation(Point)

Relocate

public void Relocate(Window view,
                     Point location)

Relocates a view relative to a base Point.

Parameters:

view - The Window to be relocated on the screen.

location - The Point to use as a relative reference. This will be used as a Rectangle with no height or width.

See Also:

Relocate(Window, Rectangle)

Select_LAF

public static String Select_LAF(String LAF_name,
                                boolean apply_to_window_frames)

Select a GUI Look-and_Feel.

A set of well-known LAF styles may be selected by their short names: Java, which is also known as Metal, Basic or Cross-platform; Motif; GTK; Synth; Windows and Windows_Classic. A fully qualified classpath for a LookAndFeel may be specified and an attempt will be made to load it into the User Interface Manager. If the name Native is specified the LAF associated with the host system will be selected. If the selected LAF can not be used by the User Interface Manager the Native LAF will be used instead.

New windows (JFrame and JDialog) may be requested to use the selected LAF, if possible. However, this hint will only be effective if applied before the new windows are constructed.

Parameters:

LAF_name - The name of the selected LAF. This may be one of the well known short names or a fully qualified classpath for a LookAndFeel class. If null or the empty String the DEFAULT_LAF will be selected.

apply_to_window_frames - If true the JFrame and JDialog classes will have a hint applied that they should use the selected LAF when a new object is constructed.

Returns:

An error message String. This will be null if the selected LAF was accepted by the User Interface Manager. Otherwise it will describe the reason that the selected LAF could not be used.

Select_LAF

public static String Select_LAF(String LAF_name)

Select a GUI Look-and_Feel.

This is the same as using Select_LAF(String, boolean) with the apply_to_window_frames argument set to true.

Parameters:

LAF_name - The name of the selected LAF. This may be one of the well known short names or a fully qualified classpath for a LookAndFeel class. If null or the empty String the DEFAULT_LAF will be selected.

Returns:

An error message String. This will be null if the selected LAF was accepted by the User Interface Manager. Otherwise it will describe the reason that the selected LAF could not be used.