com.programix.gui
Class AnchorPoint

java.lang.Object
  com.programix.gui.AnchorPoint

All Implemented Interfaces:

Serializable, Comparable<AnchorPoint>

public final class AnchorPoint
extends Object
implements Serializable, Comparable<AnchorPoint>

Used to specify where some item should be anchored relative to its container if extra width or height is available in the container. Some anchors also specify whether or not an item's width (or height) should be flexed (stretched or shrunk) to match the available width (or height). See each of the sixteen anchors defined for specifics: CENTER, NORTH, NORTHEAST, EAST, SOUTHEAST, SOUTH, SOUTHWEST, WEST, NORTHWEST, TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, and CENTER_FLEX_BOTH.

Author:

Paul Hyde

See Also:

Serialized Form

Field Summary

static AnchorPoint	BOTTOM_FLEX_WIDTH Anchor in the bottom (southern) region, but match the width to the available width of the container.
static AnchorPoint	CENTER Anchor in the CENTER region.
static AnchorPoint	CENTER_FLEX_BOTH Anchor in the CENTER (middle) region, but match the width to the available width of the container and match the height to the available height of the container.
static AnchorPoint	CENTER_FLEX_HEIGHT Anchor in the CENTER (middle) region, but match the height to the available height of the container.
static AnchorPoint	CENTER_FLEX_WIDTH Anchor in the CENTER (middle) region, but match the width to the available width of the container.
static AnchorPoint	EAST Anchor in the EAST (middle right) region.
static AnchorPoint	LEFT_FLEX_HEIGHT Anchor in the left (western) region, but match the height to the available height of the container.
static AnchorPoint	NORTH Anchor in the NORTH (centered, top) region.
static AnchorPoint	NORTHEAST Anchor in the NORTHEAST (top right) region.
static AnchorPoint	NORTHWEST Anchor in the NORTHWEST (top, left) region.
static AnchorPoint	RIGHT_FLEX_HEIGHT Anchor in the right (eastern) region, but match the height to the available height of the container.
static AnchorPoint	SOUTH Anchor in the SOUTH (centered, bottom) region.
static AnchorPoint	SOUTHEAST Anchor in the SOUTHEAST (bottom, right) region.
static AnchorPoint	SOUTHWEST Anchor in the SOUTHWEST (bottom, left) region.
static AnchorPoint	TOP_FLEX_WIDTH Anchor in the top (northern) region, but match the width to the available width of the container.
static List<AnchorPoint>	VALUE_LIST Unmodifiable List of all the instances of AnchorPoint.
static AnchorPoint	WEST Anchor in the WEST (middle, left) region.
static AnchorPoint[]	ZERO_LEN_ARRAY An array with exactly zero slots and a component type of AnchorPoint.

Method Summary

Rectangle	calcBounds(int width, int height, int availableWidth, int availableHeight) Calculates the x and y offsets, width, and height based on the anchor settings always creating a new Rectangle.
Rectangle	calcBounds(int width, int height, int availableWidth, int availableHeight, Rectangle dest) Calculates the x and y offsets, width, and height based on the anchor settings.
Point	calcOffset(int width, int height, int availableWidth, int availableHeight) Calculates the offsets, always creating a new Point.
Point	calcOffset(int width, int height, int availableWidth, int availableHeight, Point dest) Calculates the x and y offsets based on the anchor settings.
int	compareTo(AnchorPoint other)
boolean	equals(Object obj)
String	getName() Returns the name of this anchor.
static AnchorPoint[]	getValues() Returns an array of all the legal values.
int	hashCode()
boolean	isBottom() Returns true if the anchoring results in the bottom side of the item being placed as far down as possible in the container when the container has extra height available.
boolean	isFlexHeight() Returns true if the alignment is any of: LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, or CENTER_FLEX_BOTH.
boolean	isFlexWidth() Returns true if the alignment is any of: TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, or CENTER_FLEX_BOTH.
boolean	isHorizontalMiddle() Returns true if the anchoring results in the extra width being split between the left side and right side of the item when the container has extra width available.
boolean	isLeft() Returns true if the anchoring results in the left side of the item being placed as far left as possible in the container when the container has extra width available.
boolean	isRight() Returns true if the anchoring results in the right side of the item being placed as far right as possible in the container when the container has extra width available.
boolean	isTop() Returns true if the anchoring results in the top side of the item being placed as far up as possible in the container when the container has extra height available.
boolean	isVerticalMiddle() Returns true if the anchoring results in the extra height being split above and below the item when the container has extra height available.
String	toString()
static AnchorPoint	valueOf(String name) Returns the instance whose getName() method returns a String that matches the name passed in.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

CENTER

public static final AnchorPoint CENTER

Anchor in the CENTER region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is split evenly above and below the item. If extra horizontal space (width) is available in the container, this space is split evenly to the left and to the right of the item.

CENTER:

NORTH

public static final AnchorPoint NORTH

Anchor in the NORTH (centered, top) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed below the item. If extra horizontal space (width) is available in the container, this space is split evenly to the left and to the right of the item.

NORTH:

NORTHEAST

public static final AnchorPoint NORTHEAST

Anchor in the NORTHEAST (top right) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed below the item. If extra horizontal space (width) is available in the container, this space is placed to the left of the item.

NORTHEAST:

EAST

public static final AnchorPoint EAST

Anchor in the EAST (middle right) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is split evenly above and below the item. If extra horizontal space (width) is available in the container, this space is placed to the left of the item.

EAST:

SOUTHEAST

public static final AnchorPoint SOUTHEAST

Anchor in the SOUTHEAST (bottom, right) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed above the item. If extra horizontal space (width) is available in the container, this space is placed to the left of the item.

SOUTHEAST:

SOUTH

public static final AnchorPoint SOUTH

Anchor in the SOUTH (centered, bottom) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed above the item. If extra horizontal space (width) is available in the container, this space is split evenly on the left and on the right of the item.

SOUTH:

SOUTHWEST

public static final AnchorPoint SOUTHWEST

Anchor in the SOUTHWEST (bottom, left) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed above the item. If extra horizontal space (width) is available in the container, this space is placed on the right of the item.

SOUTHWEST:

WEST

public static final AnchorPoint WEST

Anchor in the WEST (middle, left) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is split evenly above and below the item. If extra horizontal space (width) is available in the container, this space is placed on the right of the item.

WEST:

NORTHWEST

public static final AnchorPoint NORTHWEST

Anchor in the NORTHWEST (top, left) region. The width and height of the item being anchored within the container are kept at their preferred values. If extra vertical space (height) is available in the container, this space is placed below the item. If extra horizontal space (width) is available in the container, this space is placed on the right of the item.

NORTHWEST:

TOP_FLEX_WIDTH

public static final AnchorPoint TOP_FLEX_WIDTH

Anchor in the top (northern) region, but match the width to the available width of the container. The item's height is set to the item's preferred height. If extra vertical space (height) is available in the container, this space is placed below the item. If extra horizontal space (width) is available in the container, the item is stretched to take up this space.

TOP_FLEX_WIDTH:

CENTER_FLEX_WIDTH

public static final AnchorPoint CENTER_FLEX_WIDTH

Anchor in the CENTER (middle) region, but match the width to the available width of the container. The item's height is set to the item's preferred height. If extra vertical space (height) is available in the container, this space is split evenly above and below the item. If extra horizontal space (width) is available in the container, the item is stretched to take up this space.

CENTER_FLEX_WIDTH:

BOTTOM_FLEX_WIDTH

public static final AnchorPoint BOTTOM_FLEX_WIDTH

Anchor in the bottom (southern) region, but match the width to the available width of the container. The item's height is set to the item's preferred height. If extra vertical space (height) is available in the container, this space is placed above the item. If extra horizontal space (width) is available in the container, the item is stretched to take up this space.

BOTTOM_FLEX_WIDTH:

LEFT_FLEX_HEIGHT

public static final AnchorPoint LEFT_FLEX_HEIGHT

Anchor in the left (western) region, but match the height to the available height of the container. The item's width is set to the item's preferred width. If extra vertical space (height) is available in the container, the item is stretched to take up this space. If extra horizontal space (width) is available in the container, the space is placed to the right of the item.

LEFT_FLEX_HEIGHT:

CENTER_FLEX_HEIGHT

public static final AnchorPoint CENTER_FLEX_HEIGHT

Anchor in the CENTER (middle) region, but match the height to the available height of the container. The item's width is set to the item's preferred width. If extra vertical space (height) is available in the container, the item is stretched to take up this space. If extra horizontal space (width) is available in the container, the space is split evenly to the left and the right of the item.

CENTER_FLEX_HEIGHT:

RIGHT_FLEX_HEIGHT

public static final AnchorPoint RIGHT_FLEX_HEIGHT

Anchor in the right (eastern) region, but match the height to the available height of the container. The item's width is set to the item's preferred width. If extra vertical space (height) is available in the container, the item is stretched to take up this space. If extra horizontal space (width) is available in the container, the space is placed to the left of the item.

RIGHT_FLEX_HEIGHT:

CENTER_FLEX_BOTH

public static final AnchorPoint CENTER_FLEX_BOTH

Anchor in the CENTER (middle) region, but match the width to the available width of the container and match the height to the available height of the container. If extra vertical space (height) is available in the container, the item is stretched to take up this space. If extra horizontal space (width) is available in the container, the item is stretched to take up this space. With this fully filling option, the term anchor is a bit of a misnomer as all of the excess space is consumed by stretching in both directions (similarly, using center as part of the name is an arbitrary choice).

CENTER_FLEX_BOTH:

ZERO_LEN_ARRAY

public static final AnchorPoint[] ZERO_LEN_ARRAY

An array with exactly zero slots and a component type of AnchorPoint. This object can be safely shared (including simultaneously shared) by all as it is completely immutable.

VALUE_LIST

public static final List<AnchorPoint> VALUE_LIST

Unmodifiable List of all the instances of AnchorPoint.

Method Detail

getValues

public static AnchorPoint[] getValues()

Returns an array of all the legal values. A cloned copy is returned, so no caution is required.

valueOf

public static AnchorPoint valueOf(String name)
                           throws IllegalArgumentException

Returns the instance whose getName() method returns a String that matches the name passed in. The matching is done ignoring any case differences and after trimming any leading or trailing whitespace on the string passed in.

Parameters:

name - the name to search for.

Returns:

the matching instance

Throws:

IllegalArgumentException - if no match is found.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

compareTo

public int compareTo(AnchorPoint other)

Specified by:

compareTo in interface Comparable<AnchorPoint>

getName

public String getName()

Returns the name of this anchor. For example: "NORTH", "CENTER", etc.

isLeft

public boolean isLeft()

Returns true if the anchoring results in the left side of the item being placed as far left as possible in the container when the container has extra width available. Specifically, true is returned if the alignment is any of: WEST, NORTHWEST, SOUTHWEST, LEFT_FLEX_HEIGHT, TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, or CENTER_FLEX_BOTH.

isRight

public boolean isRight()

Returns true if the anchoring results in the right side of the item being placed as far right as possible in the container when the container has extra width available. Specifically, true is returned if the alignment is any of: EAST, NORTHEAST, SOUTHEAST, RIGHT_FLEX_HEIGHT, TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, or CENTER_FLEX_BOTH.

isHorizontalMiddle

public boolean isHorizontalMiddle()

Returns true if the anchoring results in the extra width being split between the left side and right side of the item when the container has extra width available. Specifically, true is returned if the alignment is any of: CENTER, NORTH, SOUTH, CENTER_FLEX_HEIGHT, TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, or CENTER_FLEX_BOTH.

isTop

public boolean isTop()

Returns true if the anchoring results in the top side of the item being placed as far up as possible in the container when the container has extra height available. Specifically, true is returned if the alignment is any of: NORTH, NORTHEAST, NORTHWEST, TOP_FLEX_WIDTH, LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, CENTER_FLEX_BOTH.

isBottom

public boolean isBottom()

Returns true if the anchoring results in the bottom side of the item being placed as far down as possible in the container when the container has extra height available. Specifically, true is returned if the alignment is any of: SOUTH, SOUTHEAST, SOUTHWEST, BOTTOM_FLEX_WIDTH, LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, CENTER_FLEX_BOTH.

isVerticalMiddle

public boolean isVerticalMiddle()

Returns true if the anchoring results in the extra height being split above and below the item when the container has extra height available. Specifically, true is returned if the alignment is any of: CENTER, EAST, WEST, CENTER_FLEX_WIDTH, LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, CENTER_FLEX_BOTH.

isFlexWidth

public boolean isFlexWidth()

Returns true if the alignment is any of: TOP_FLEX_WIDTH, CENTER_FLEX_WIDTH, BOTTOM_FLEX_WIDTH, or CENTER_FLEX_BOTH.

isFlexHeight

public boolean isFlexHeight()

Returns true if the alignment is any of: LEFT_FLEX_HEIGHT, CENTER_FLEX_HEIGHT, RIGHT_FLEX_HEIGHT, or CENTER_FLEX_BOTH.

calcBounds

public Rectangle calcBounds(int width,
                            int height,
                            int availableWidth,
                            int availableHeight,
                            Rectangle dest)

Calculates the x and y offsets, width, and height based on the anchor settings.

Parameters:

width - of the item to anchor.

height - of the item to anchor.

availableWidth - of the space to be anchored within.

availableHeight - of the space to be anchored within.

dest - Rectangle to load with offsets. If null is passed, a new Rectangle is allocated.

Returns:

passed dest, or a new Rectangle if dest is null.

calcBounds

public Rectangle calcBounds(int width,
                            int height,
                            int availableWidth,
                            int availableHeight)

Calculates the x and y offsets, width, and height based on the anchor settings always creating a new Rectangle. Equivalent to:

 return calcOffset(width, height, availableWidth, availableHeight, null);
 

calcOffset

public Point calcOffset(int width,
                        int height,
                        int availableWidth,
                        int availableHeight,
                        Point dest)

Calculates the x and y offsets based on the anchor settings.

Parameters:

width - of the item to anchor.

height - of the item to anchor.

availableWidth - of the space to be anchored within.

availableHeight - of the space to be anchored within.

dest - Point to load with offsets. If null is passed, a new Point is allocated.

Returns:

passed dest, or a new Point if dest is null.

calcOffset

public Point calcOffset(int width,
                        int height,
                        int availableWidth,
                        int availableHeight)

Calculates the offsets, always creating a new Point. Equivalent to:

 return calcOffset(width, height, availableWidth, availableHeight, null);