Package org.eclipse.gef.rulers

# Class RulerProvider

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

public abstract class RulerProvider extends 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
Modifier and Type
Field
Description
`protected List<RulerChangeListener>`
`listeners`
A list of `RulerChangeListener`s that have to be notified of changes in ruler/guide properties.
`static final String`
`PROPERTY_HORIZONTAL_RULER`
The following property should be set on the graphical viewer.
`static final String`
`PROPERTY_RULER_VISIBILITY`
The following property should be set on the graphical viewer.
`static final String`
`PROPERTY_VERTICAL_RULER`
The following property should be set on the graphical viewer.
`static final int`
`UNIT_CENTIMETERS`
Constant indicating that the ruler should display centimeters.
`static final int`
`UNIT_CUSTOM`
Constant indicating that the ruler should display a custom unit per pixel count.
`static final int`
`UNIT_INCHES`
Constant indicating that the ruler should display inches.
`static final int`
`UNIT_PIXELS`
Constant indicating that the ruler should display pixel count.

## Constructor Summary

Constructors
Constructor
Description
`RulerProvider()`

## Method Summary

Modifier and Type
Method
Description
`void`
`addRulerChangeListener(RulerChangeListener listener)`
The given listener will be notified of changes in ruler properties.
`void`
`getAccGuideDescription(AccessibleEvent e, Object guide)`
Return the description of the control or specified child in the `result` field of the event object.
`void`
`getAccGuideName(AccessibleEvent e, Object guide)`
Return the given guide's name/label in the `result` field of the given event.
`void`
`getAccGuideValue(AccessibleControlEvent e, Object guide)`
Return the guide's position in the `result` field of the given event.
`List<? extends EditPart>`
`getAttachedEditParts(Object guide, GraphicalViewer viewer)`
Returns a List of EditParts that are attached to the given guide.
`List<? extends Object>`
`getAttachedModelObjects(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.
`int`
`getCustomRulerDPU()`
When the unit to be used for the ruler is `UNIT_CUSTOM` clients need to override this method to return the pixel dots per unit to be used for this ruler.
`Command`
`getDeleteGuideCommand(Object guide)`
Clients should override this method to return a Command to delete the given guide.
`Object`
`getGuideAt(int position)`
In most cases, there should be no need for clients to override this method.
`int`
`getGuidePosition(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.
`List<? extends Object>`
`getGuides()`
Clients should override this method to return a list of all the guides set on this ruler.
`Command`
`getMoveGuideCommand(Object guide, int positionDelta)`
Clients should override this method to return a Command to move the given guide by the given amount.
`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 Details

### PROPERTY_HORIZONTAL_RULER

public static final 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 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 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

### UNIT_CUSTOM

public static final int UNIT_CUSTOM
Constant indicating that the ruler should display a custom unit per pixel count. The unit per pixel count shall be provided via `getCustomRulerDPU()`.

Since:
  3.20
See Also:
  - Constant Field Values

### listeners

protected List<RulerChangeListener> listeners
A list of `RulerChangeListener`s that have to be notified of changes in ruler/guide properties.

## Constructor Details

### RulerProvider

public RulerProvider()

## Method Details

### 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, 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, 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, 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 List<? extends Object> getAttachedModelObjects(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 List<? extends EditPart> getAttachedEditParts(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

### getCustomRulerDPU

public int getCustomRulerDPU()
When the unit to be used for the ruler is `UNIT_CUSTOM` clients need to override this method to return the pixel dots per unit to be used for this ruler. Clients should override this method to return

Returns:
  the dots per unit for the ruler, default is 1 which is equal to use `UNIT_PIXELS`.
Since:
  3.20

### getDeleteGuideCommand

public Command getDeleteGuideCommand(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 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(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 List<? extends Object> 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(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 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`