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.

### Field Summary

Fields
`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

Constructors
Constructor and Description
`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

Methods
`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` or`CENTER`
    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.