Runtime

## org.eclipse.gmf.runtime.diagram.ui.figures
Class BorderItemLocator

    java.lang.Object
      org.eclipse.gmf.runtime.diagram.ui.figures.BorderItemLocator

All Implemented Interfaces:
  IBorderItemLocator, Locator

public class BorderItemLocator
extends java.lang.Object
implements IBorderItemLocator

BorderItemLocator works closely with border items in determining position. BorderItemLocators use a figure as the bounds around which the borderItemFigure can be placed. This figure may not necessarily be the main figure.

BorderItemLocator allows intial placement ( N/W/S/E ) and is used in conjunction with BorderItemSelectionEditPolicy for feedback.

Collision detection is provided so that border items cannot overlap and therefore be hidden.

Border item movement is restricted along border of bordered shape.

Constructor Summary
`BorderItemLocator(IFigure parentFigure)` The preferred side determines placement of figure.
`BorderItemLocator(IFigure borderItem, IFigure parentFigure, Rectangle constraint)` The preferred location overrides the preferred side.
`BorderItemLocator(IFigure parentFigure, int preferredSide)` The preferred side determines placement of figure.

Method Summary
`static int` `findClosestSideOfParent(Rectangle proposedLocation, Rectangle parentBorder)` Find the closest side when x,y is inside parent.
`protected Point` `getAbsoluteToBorder(Point ptRelativeOffset)` Convert the relative coords in the model to ones that are Relative to the container (absolute in respect to the main figure)
`Dimension` `getBorderItemOffset()`
`protected Rectangle` `getConstraint()` Accessor to return the constraint location of the border item.
`int` `getCurrentSideOfParent()` Returns the side of the parent figure on which the border item is currently on.
`protected Rectangle` `getParentBorder()` Utility to calculate the parent bounds with consideration for the handle bounds inset.
`IFigure` `getParentFigure()` getter for the parent figure
`protected Point` `getPreferredLocation(IFigure borderItem)` Get the preferred location.
`protected Point` `getPreferredLocation(int side, IFigure borderItem)` Get an initial location based on the side. ( choose middle of the side )
`int` `getPreferredSideOfParent()` Returns the preferred side of the parent figure on which to place this border item.
`Rectangle` `getValidLocation(Rectangle proposedLocation, IFigure borderItem)` Returns a suitable location for the border item given a proposed location.
`void` `relocate(IFigure borderItem)`
`void` `setBorderItemOffset(Dimension borderItemOffset)`
`void` `setConstraint(Rectangle theConstraint)` Sets the constraint for the location of this border item.
`void` `setCurrentSideOfParent(int side)` Sets the side of the parent figure on which the border item should appear.
`void` `setPreferredSideOfParent(int preferredSide)` Sets the preferred side of the parent figure on which to place this border item.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### BorderItemLocator

    public BorderItemLocator(IFigure parentFigure)

  The preferred side determines placement of figure.

Parameters:
  `parentFigure` -

### BorderItemLocator

    public BorderItemLocator(IFigure parentFigure,
                             int preferredSide)

  The preferred side determines placement of figure.

Parameters:
  `parentFigure` -
  `preferredSide` - the preferred side of the parent figure on which to place this border item as defined in `PositionConstants`

### BorderItemLocator

    public BorderItemLocator(IFigure borderItem,
                             IFigure parentFigure,
                             Rectangle constraint)

  The preferred location overrides the preferred side.

Parameters:
  `parentFigure` -
  `constraint` -

Method Detail

### getConstraint

    protected Rectangle getConstraint()

  Accessor to return the constraint location of the border item.

  Returns:
    the constraint

### setConstraint

    public void setConstraint(Rectangle theConstraint)

  Description copied from interface: `IBorderItemLocator`
  Sets the constraint for the location of this border item.

  Specified by:
    `setConstraint` in interface `IBorderItemLocator`
  Parameters:
    `theConstraint` - the position and optionally size

### getPreferredLocation

    protected Point getPreferredLocation(IFigure borderItem)

  Get the preferred location. If none has been previously set, use the preferred side to take an initial guess.

  Returns:
    point

### getParentBorder

    protected Rectangle getParentBorder()

  Utility to calculate the parent bounds with consideration for the handle bounds inset.

  Returns:
    `Rectangle` that is the bounds of the parent.

### getPreferredLocation

    protected Point getPreferredLocation(int side,
                                         IFigure borderItem)

  Get an initial location based on the side. ( choose middle of the side )

  Parameters:
    `side` - the preferred side of the parent figure on which to place this border item as defined in `PositionConstants`
  Returns:
    point

### getAbsoluteToBorder

    protected Point getAbsoluteToBorder(Point ptRelativeOffset)

  Convert the relative coords in the model to ones that are Relative to the container (absolute in respect to the main figure)

  Parameters:
    `ptRelativeOffset` -
  Returns:
    point

### getValidLocation

    public Rectangle getValidLocation(Rectangle proposedLocation,
                                      IFigure borderItem)

  Description copied from interface: `IBorderItemLocator`
  Returns a suitable location for the border item given a proposed location. By implementing this method, the feedback shown when the user moves a border item can reflect where the locator will actually place the border item.

  For example, if the border item is restricted to being on the border of its parent shape, when the user attempts to move the border item outside the border of the parent shape (the proposed location), the feedback will always show the border item on the border. In this case, this method would return a location on the border close to the proposed location.

  Specified by:
    `getValidLocation` in interface `IBorderItemLocator`
  Parameters:
    `proposedLocation` - a proposed location and optionally size
    `borderItem` - the border item in question
  Returns:
    a rectangle containing the valid location

### findClosestSideOfParent

    public static int findClosestSideOfParent(Rectangle proposedLocation,
                                              Rectangle parentBorder)

  Find the closest side when x,y is inside parent.

  Parameters:
    `proposedLocation` -
    `parentBorder` -
  Returns:
    draw constant

### relocate

    public void relocate(IFigure borderItem)

  Specified by:
    `relocate` in interface `Locator`

### getParentFigure

    public IFigure getParentFigure()

  getter for the parent figure

  Returns:
    `IFigure`

### getBorderItemOffset

    public Dimension getBorderItemOffset()

  Returns:
    Returns the borderItemOffset.

### setBorderItemOffset

    public void setBorderItemOffset(Dimension borderItemOffset)

  Parameters:
    `borderItemOffset` - The borderItemOffset to set.

### getPreferredSideOfParent

    public int getPreferredSideOfParent()

  Returns the preferred side of the parent figure on which to place this border item.

  Returns:
    the preferred side of the parent figure on which to place this border item as defined in `PositionConstants`

### setPreferredSideOfParent

    public void setPreferredSideOfParent(int preferredSide)

  Sets the preferred side of the parent figure on which to place this border item.

  Parameters:
    `preferredSide` - the preferred side of the parent figure on which to place this border item as defined in `PositionConstants`

### getCurrentSideOfParent

    public int getCurrentSideOfParent()

  Description copied from interface: `IBorderItemLocator`
  Returns the side of the parent figure on which the border item is currently on.

  Specified by:
    `getCurrentSideOfParent` in interface `IBorderItemLocator`
  Returns:
    the side on which this border item appears as defined in `PositionConstants`

### setCurrentSideOfParent

    public void setCurrentSideOfParent(int side)

  Sets the side of the parent figure on which the border item should appear.

  Parameters:
    `side` - the side on which this border item appears as defined in `PositionConstants`

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.