org.eclipse.gef.rulers

## Class RulerProvider

- java.lang.Object
- - org.eclipse.gef.rulers.RulerProvider

    public abstract class RulerProvider
    extends java.lang.Object

This class provides an interface to interact with the ruler/guide feature provided in GEF. A `RulerProvider` represents a ruler (and the guides contained within), and provides the necessary information about them.

Clients wishing to utilize this GEF feature should do the following:

- Extend this class and override the necessary methods. Also provide a notification mechanism to notify registered `RulerChangeListener`s of changes in ruler properties.
- Set instances of that class as properties on the diagram's graphical viewer (PROPERTY_HORIZONTAL_RULER and/or PROPERTY_VERTICAL_RULER)
- Set PROPERTY_RULER_VISIBILITY to be `true` on the graphical viewer.

Since:
  3.0

### Field Summary

Fields
`protected java.util.List` `listeners` A list of `RulerChangeListener`s that have to be notified of changes in ruler/guide properties.
`static java.lang.String` `PROPERTY_HORIZONTAL_RULER` The following property should be set on the graphical viewer.
`static java.lang.String` `PROPERTY_RULER_VISIBILITY` The following property should be set on the graphical viewer.
`static java.lang.String` `PROPERTY_VERTICAL_RULER` The following property should be set on the graphical viewer.
`static int` `UNIT_CENTIMETERS` Constant indicating that the ruler should display centimeters.
`static int` `UNIT_INCHES` Constant indicating that the ruler should display inches.
`static int` `UNIT_PIXELS` Constant indicating that the ruler should display pixel count.

### Constructor Summary

Constructors
Constructor and Description
`RulerProvider()`

### Method Summary

Methods
`void` `addRulerChangeListener(RulerChangeListener listener)` The given listener will be notified of changes in ruler properties.
`void` `getAccGuideDescription(AccessibleEvent e, java.lang.Object guide)` Return the description of the control or specified child in the `result` field of the event object.
`void` `getAccGuideName(AccessibleEvent e, java.lang.Object guide)` Return the given guide's name/label in the `result` field of the given event.
`void` `getAccGuideValue(AccessibleControlEvent e, java.lang.Object guide)` Return the guide's position in the `result` field of the given event.
`java.util.List` `getAttachedEditParts(java.lang.Object guide, GraphicalViewer viewer)` Returns a List of EditParts that are attached to the given guide.
`java.util.List` `getAttachedModelObjects(java.lang.Object guide)` Returns a List of model objects that are attached to the given guide.
`Command` `getCreateGuideCommand(int position)` Clients should override this method to return a Command to create a new guide at the given position.
`Command` `getDeleteGuideCommand(java.lang.Object guide)` Clients should override this method to return a Command to delete the given guide.
`java.lang.Object` `getGuideAt(int position)` In most cases, there should be no need for clients to override this method.
`int` `getGuidePosition(java.lang.Object guide)` Clients should override this method to return the position (in pixels) of the given guide.
`int[]` `getGuidePositions()` Clients should override this method to return an array of all the positions of all the guides on this ruler.
`java.util.List` `getGuides()` Clients should override this method to return a list of all the guides set on this ruler.
`Command` `getMoveGuideCommand(java.lang.Object guide, int positionDelta)` Clients should override this method to return a Command to move the given guide by the given amount.
`java.lang.Object` `getRuler()` Clients should override this method to return a model representation of the ruler.
`int` `getUnit()` Clients should override this method to return the units that the ruler should display: one of UNIT_INCHES, UNIT_CENTIMETERS, UNIT_PIXELS.
`void` `removeRulerChangeListener(RulerChangeListener listener)` The given listener will not be notified of changes in the ruler anymore.
`void` `setUnit(int newUnit)` This method will be invoked when the user requests that the ruler display a different measurement.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### PROPERTY_HORIZONTAL_RULER

    public static final java.lang.String PROPERTY_HORIZONTAL_RULER

The following property should be set on the graphical viewer. PROPERTY_HORIZONTAL_RULER should have a RulerProvider as its value.

See Also:
  Constant Field Values

#### PROPERTY_RULER_VISIBILITY

    public static final java.lang.String PROPERTY_RULER_VISIBILITY

The following property should be set on the graphical viewer. PROPERTY_RULER_VISIBILITY should have a Boolean value.

See Also:
  Constant Field Values

#### PROPERTY_VERTICAL_RULER

    public static final java.lang.String PROPERTY_VERTICAL_RULER

The following property should be set on the graphical viewer. PROPERTY_VERTICAL_RULER should have a RulerProvider as its value.

See Also:
  Constant Field Values

#### UNIT_CENTIMETERS

    public static final int UNIT_CENTIMETERS

Constant indicating that the ruler should display centimeters. Note that this setting does not affect how a guide's position is interpreted (it is always taken as pixels).

See Also:
  Constant Field Values

#### UNIT_INCHES

    public static final int UNIT_INCHES

Constant indicating that the ruler should display inches. Note that this setting does not affect how a guide's position is interpreted (it is always taken as pixels).

See Also:
  Constant Field Values

#### UNIT_PIXELS

    public static final int UNIT_PIXELS

Constant indicating that the ruler should display pixel count.

See Also:
  Constant Field Values

#### listeners

    protected java.util.List listeners

A list of `RulerChangeListener`s that have to be notified of changes in ruler/guide properties.

### Constructor Detail

#### RulerProvider

    public RulerProvider()

### Method Detail

#### addRulerChangeListener

    public void addRulerChangeListener(RulerChangeListener listener)

The given listener will be notified of changes in ruler properties.

Parameters:
  `listener` - the listener that is to be notified of changes in ruler properties

#### getAccGuideDescription

    public void getAccGuideDescription(AccessibleEvent e,
                              java.lang.Object guide)

Return the description of the control or specified child in the `result` field of the event object. Returning an empty string tells the client that the control or child does not have a description, and returning null tells the client to use the platform description.

Parameters:
  `e` - AccessibleEvent
  `guide` - The guide whose accessibility information is requested
See Also:
  `AccessibleAdapter.getDescription(AccessibleEvent)`

#### getAccGuideName

    public void getAccGuideName(AccessibleEvent e,
                       java.lang.Object guide)

Return the given guide's name/label in the `result` field of the given event.

Parameters:
  `e` - AccessibleEvent
  `guide` - The guide whose accessibility information is requested
See Also:
  `AccessibleAdapter.getName(AccessibleEvent)`

#### getAccGuideValue

    public void getAccGuideValue(AccessibleControlEvent e,
                        java.lang.Object guide)

Return the guide's position in the `result` field of the given event.

Parameters:
  `e` - AccessibleEvent
  `guide` - The guide whose accessibility information is requested
See Also:
  `AccessibleControlAdapter.getValue(AccessibleControlEvent)`

#### getAttachedModelObjects

    public java.util.List getAttachedModelObjects(java.lang.Object guide)

Returns a List of model objects that are attached to the given guide.

Parameters:
  `guide` - the guide to which the model parts are attached.
Returns:
  list of attached model objects

#### getAttachedEditParts

    public java.util.List getAttachedEditParts(java.lang.Object guide,
                                      GraphicalViewer viewer)

Returns a List of EditParts that are attached to the given guide.

Parameters:
  `guide` - the guide to which the EditParts are attached.
  `viewer` - the GraphicalViewer in which these EditParts are shown.
Returns:
  list of attached edit parts

#### getCreateGuideCommand

    public Command getCreateGuideCommand(int position)

Clients should override this method to return a Command to create a new guide at the given position.

Parameters:
  `position` - The pixel position where the new guide is to be created
Returns:
  UnexecutableCommand

#### getDeleteGuideCommand

    public Command getDeleteGuideCommand(java.lang.Object guide)

Clients should override this method to return a Command to delete the given guide.

Parameters:
  `guide` - The guide that is to be deleted
Returns:
  UnexecutableCommand

#### getGuideAt

    public java.lang.Object getGuideAt(int position)

In most cases, there should be no need for clients to override this method.

Parameters:
  `position` - The position of the guide that is to be found
Returns:
  The guide object at the given position; `null` if no guide exists at the given position

#### getMoveGuideCommand

    public Command getMoveGuideCommand(java.lang.Object guide,
                              int positionDelta)

Clients should override this method to return a Command to move the given guide by the given amount.

Parameters:
  `guide` - The guide that is to be moved
  `positionDelta` - The amount by which the guide is to be moved
Returns:
  UnexecutableCommand

#### getGuides

    public java.util.List getGuides()

Clients should override this method to return a list of all the guides set on this ruler.

Returns:
  an empty list

#### getGuidePositions

    public int[] getGuidePositions()

Clients should override this method to return an array of all the positions of all the guides on this ruler.

Returns:
  an empty array

#### getGuidePosition

    public int getGuidePosition(java.lang.Object guide)

Clients should override this method to return the position (in pixels) of the given guide.

Parameters:
  `guide` - The guide whose position is to be determined
Returns:
  `Integer.MIN_VALUE`

#### getRuler

    public java.lang.Object getRuler()

Clients should override this method to return a model representation of the ruler.

Returns:
  `null`

#### getUnit

    public int getUnit()

Clients should override this method to return the units that the ruler should display: one of UNIT_INCHES, UNIT_CENTIMETERS, UNIT_PIXELS.

Returns:
  UNIT_INCHES

#### removeRulerChangeListener

    public void removeRulerChangeListener(RulerChangeListener listener)

The given listener will not be notified of changes in the ruler anymore.

Parameters:
  `listener` - the listener that is to be removed

#### setUnit

    public void setUnit(int newUnit)

This method will be invoked when the user requests that the ruler display a different measurement. The default implementation ignores the user's request.

Parameters:
  `newUnit` - the new unit of measurement; will be one of `UNIT_CENTIMETERS`, `UNIT_INCHES`, or `UNIT_PIXELS`