org.eclipse.jface.text.source

## Class AbstractRulerColumn

- java.lang.Object
- - org.eclipse.jface.text.source.AbstractRulerColumn

All Implemented Interfaces:
  IVerticalRulerColumn, IVerticalRulerInfo, IVerticalRulerInfoExtension

    public abstract class AbstractRulerColumn
    extends Object
    implements IVerticalRulerColumn, IVerticalRulerInfo, IVerticalRulerInfoExtension

Abstract implementation of a `IVerticalRulerColumn` that uses a `Canvas` to draw the ruler contents and which handles scrolling and mouse selection.

### Painting

Subclasses can hook into the paint loop at three levels:

- Override `paint(GC, ILineRange)` to control the entire painting of the ruler.
- Override `paintLine(GC, int, int, int, int)` to control the painting of a line.
- Leave the painting to the default implementation, but override `computeBackground(int)`, `computeForeground(int)` and `computeText(int)` to specify the ruler appearance for a line.

### Invalidation

Subclasses may call `redraw()` to mark the entire ruler as needing to be redrawn. Alternatively, use `redraw(ILineRange)` to only invalidate a certain line range, for example due to changes to the display model.

### Configuration

Subclasses can set the following properties. Setting them may trigger redrawing.

- The `font` used to draw text in `paintLine(GC, int, int, int, int)`.
- The horizontal `text inset` for text drawn.
- The `default background color` of the ruler.
- The `width` of the ruler.

Since:
  3.3

### Constructor Summary

Constructors
`protected` `AbstractRulerColumn()` Creates a new ruler.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addVerticalRulerListener(IVerticalRulerListener listener)` Registers a vertical ruler listener to be informed if an annotation gets selected on the vertical ruler.
`protected Color` `computeBackground(int line)` Returns the background color drawn for a certain line by `paintLine(GC, int, int, int, int)`.
`protected Color` `computeForeground(int line)` Returns the foreground color drawn for a certain line by `paintLine(GC, int, int, int, int)`.
`protected String` `computeText(int line)` Returns the text to be drawn for a certain line by `paintLine(GC, int, int, int, int)`, `null` for no text.
`Control` `createControl(CompositeRuler parentRuler, Composite parentControl)` Creates the column's SWT control.
`void` `dispose()` Disposes this ruler column.
`protected int` `getCanvasStyle()` Returns the SWT style bits used when creating the ruler canvas.
`Control` `getControl()` Returns the column's SWT control.
`protected Color` `getDefaultBackground()` Returns the background color.
`protected Font` `getFont()` Returns the current font.
`IAnnotationHover` `getHover()` Returns the hover for this vertical ruler (column).
`int` `getLineOfLastMouseButtonActivity()` Returns the line number of the last mouse button activity.
`IAnnotationModel` `getModel()` Returns the model currently used by the receiver.
`protected CompositeRuler` `getParentRuler()` Returns the parent ruler, `null` before `createControl(CompositeRuler, Composite)` has been called.
`protected int` `getTextInset()` Returns the text inset for text drawn by `paintLine(GC, int, int, int, int)`.
`int` `getWidth()` Returns the width of this column's control.
`protected void` `paint(GC gc, ILineRange lines)` Paints the ruler.
`protected void` `paintLine(GC gc, int modelLine, int widgetLine, int linePixel, int lineHeight)` Paints the ruler representation of a single line.
`void` `redraw()` Redraws this column.
`protected void` `redraw(ILineRange lines)` Marks the region covered by `lines` as needing to be redrawn.
`void` `removeVerticalRulerListener(IVerticalRulerListener listener)` Removes a previously registered listener.
`protected void` `setDefaultBackground(Color background)` Sets the default background color for this column.
`void` `setFont(Font font)` Sets the font of this ruler column.
`protected void` `setHover(IAnnotationHover hover)` Sets the annotation hover.
`void` `setModel(IAnnotationModel model)` Associates an annotation model with this ruler column.
`protected void` `setTextInset(int textInset)` Sets the text inset (padding) used to draw text in `paintLine(GC, int, int, int, int)`.
`protected void` `setWidth(int width)` The new width in pixels.
`int` `toDocumentLineNumber(int y_coordinate)` Translates a y-coordinate of the ruler's SWT control into the according line number of the document of the connected text viewer.

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

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

### Constructor Detail

#### AbstractRulerColumn

    protected AbstractRulerColumn()

Creates a new ruler.

### Method Detail

#### createControl

    public Control createControl(CompositeRuler parentRuler,
                                 Composite parentControl)

Description copied from interface: `IVerticalRulerColumn`
Creates the column's SWT control.

Specified by:
  `createControl` in interface `IVerticalRulerColumn`
Parameters:
  `parentRuler` - the parent ruler of this column
  `parentControl` - the control of the parent ruler
Returns:
  the column's SWT control

#### getCanvasStyle

    protected int getCanvasStyle()

Returns the SWT style bits used when creating the ruler canvas.

The default implementation returns `SWT.NO_BACKGROUND`.

Clients may reimplement this method to create a canvas with their desired style bits.

Returns:
  the SWT style bits, or `SWT.NONE` if none

#### getControl

    public final Control getControl()

Description copied from interface: `IVerticalRulerColumn`
Returns the column's SWT control.

Specified by:
  `getControl` in interface `IVerticalRulerColumn`
Specified by:
  `getControl` in interface `IVerticalRulerInfo`
Returns:
  the column's SWT control

#### setWidth

    protected final void setWidth(int width)

The new width in pixels. The `DEFAULT_WIDTH` constant specifies the default width.

Parameters:
  `width` - the new width

#### getWidth

    public final int getWidth()

Description copied from interface: `IVerticalRulerColumn`
Returns the width of this column's control.

Specified by:
  `getWidth` in interface `IVerticalRulerColumn`
Specified by:
  `getWidth` in interface `IVerticalRulerInfo`
Returns:
  the width of this column's control

#### getParentRuler

    protected final CompositeRuler getParentRuler()

Returns the parent ruler, `null` before `createControl(CompositeRuler, Composite)` has been called.

Returns:
  the parent ruler or `null`

#### setFont

    public final void setFont(Font font)

Sets the font of this ruler column.

Specified by:
  `setFont` in interface `IVerticalRulerColumn`
Parameters:
  `font` - the font or `null` to use the default font

#### getFont

    protected final Font getFont()

Returns the current font. If a font has not been explicitly set, the widget's font is returned.

Returns:
  the font used to render text on the ruler.

#### setTextInset

    protected final void setTextInset(int textInset)

Sets the text inset (padding) used to draw text in `paintLine(GC, int, int, int, int)`.

Parameters:
  `textInset` - the new text inset

#### getTextInset

    protected final int getTextInset()

Returns the text inset for text drawn by `paintLine(GC, int, int, int, int)`. The `DEFAULT_TEXT_INSET` constant specifies the default inset in pixels.

Returns:
  the text inset for text

#### setModel

    public void setModel(IAnnotationModel model)

Description copied from interface: `IVerticalRulerColumn`
Associates an annotation model with this ruler column. A value `null` is acceptable and clears the ruler.

Specified by:
  `setModel` in interface `IVerticalRulerColumn`
Parameters:
  `model` - the new annotation model, may be `null`

#### getModel

    public final IAnnotationModel getModel()

Description copied from interface: `IVerticalRulerInfoExtension`
Returns the model currently used by the receiver.

Specified by:
  `getModel` in interface `IVerticalRulerInfoExtension`
Returns:
  the model of the receiver, or `null` if no model is installed.

#### setDefaultBackground

    protected final void setDefaultBackground(Color background)

Sets the default background color for this column. The default background is used as default implementation of `computeBackground(int)` and also to paint the area of the ruler that does not correspond to any lines (when the viewport is not entirely filled with lines).

Parameters:
  `background` - the default background color, `null` to use the text widget's background

#### getDefaultBackground

    protected final Color getDefaultBackground()

Returns the background color. May return `null` if the system is shutting down.

Returns:
  the background color

#### setHover

    protected final void setHover(IAnnotationHover hover)

Sets the annotation hover.

Parameters:
  `hover` - the annotation hover, `null` for no hover

#### getHover

    public IAnnotationHover getHover()

Description copied from interface: `IVerticalRulerInfoExtension`
Returns the hover for this vertical ruler (column).

Specified by:
  `getHover` in interface `IVerticalRulerInfoExtension`
Returns:
  the hover for this column

#### dispose

    public void dispose()

Disposes this ruler column.

Subclasses may extend this method.

Clients who created this column are responsible to call this method once the column is no longer used.

#### redraw

    public final void redraw()

Description copied from interface: `IVerticalRulerColumn`
Redraws this column.

Specified by:
  `redraw` in interface `IVerticalRulerColumn`

#### redraw

    protected final void redraw(ILineRange lines)

Marks the region covered by `lines` as needing to be redrawn.

Parameters:
  `lines` - the lines to be redrawn in document coordinates

#### paint

    protected void paint(GC gc,
                         ILineRange lines)

Paints the ruler. Note that `lines` reference widget line indices, and that `lines` may not cover the entire viewport, but only the lines that need to be painted. The lines may not be entirely visible.

Subclasses may replace or extend. The default implementation calls `paintLine(GC, int, int, int, int)` for every visible line.

Parameters:
  `gc` - the graphics context to paint on
  `lines` - the lines to paint in widget coordinates

#### paintLine

    protected void paintLine(GC gc,
                             int modelLine,
                             int widgetLine,
                             int linePixel,
                             int lineHeight)

Paints the ruler representation of a single line.

Subclasses may replace or extend. The default implementation draws the text obtained by `computeText(int)` in the `foreground color` and fills the entire width using the `background color`. The text is drawn `getTextInset()` pixels to the right of the left border.

Parameters:
  `gc` - the graphics context to paint on
  `modelLine` - the model line (based on document coordinates)
  `widgetLine` - the line in the text widget corresponding to `modelLine`
  `linePixel` - the first y-pixel of the widget line
  `lineHeight` - the line height in pixels

#### computeText

    protected String computeText(int line)

Returns the text to be drawn for a certain line by `paintLine(GC, int, int, int, int)`, `null` for no text. The default implementation returns `null`.

Subclasses may replace or extend.

Parameters:
  `line` - the document line number
Returns:
  the text to be drawn for the given line, `null` for no text

#### computeBackground

    protected Color computeBackground(int line)

Returns the background color drawn for a certain line by `paintLine(GC, int, int, int, int)`. The default implementation returns `getDefaultBackground()`.

Subclasses may replace or extend.

Parameters:
  `line` - the document line number
Returns:
  the background color for drawn for the given line

#### computeForeground

    protected Color computeForeground(int line)

Returns the foreground color drawn for a certain line by `paintLine(GC, int, int, int, int)`. The default implementation returns a `SWT.COLOR_DARK_GRAY` color.

Subclasses may replace or extend.

Parameters:
  `line` - the document line number
Returns:
  the foreground color for drawn for the given line

#### getLineOfLastMouseButtonActivity

    public final int getLineOfLastMouseButtonActivity()

Description copied from interface: `IVerticalRulerInfo`
Returns the line number of the last mouse button activity. Based on the input document of the connected text viewer.

Specified by:
  `getLineOfLastMouseButtonActivity` in interface `IVerticalRulerInfo`
Returns:
  the line number of the last mouse button activity or `-1` if the last mouse activity does not correspond to a valid document line

#### toDocumentLineNumber

    public final int toDocumentLineNumber(int y_coordinate)

Description copied from interface: `IVerticalRulerInfo`
Translates a y-coordinate of the ruler's SWT control into the according line number of the document of the connected text viewer.

Specified by:
  `toDocumentLineNumber` in interface `IVerticalRulerInfo`
Parameters:
  `y_coordinate` - a y-coordinate of the ruler's SWT control
Returns:
  the line number of that coordinate or `-1` if that coordinate does not correspond to a valid document line

#### addVerticalRulerListener

    public void addVerticalRulerListener(IVerticalRulerListener listener)

Description copied from interface: `IVerticalRulerInfoExtension`
Registers a vertical ruler listener to be informed if an annotation gets selected on the vertical ruler.

Specified by:
  `addVerticalRulerListener` in interface `IVerticalRulerInfoExtension`
Parameters:
  `listener` - the listener to be informed

#### removeVerticalRulerListener

    public void removeVerticalRulerListener(IVerticalRulerListener listener)

Description copied from interface: `IVerticalRulerInfoExtension`
Removes a previously registered listener. If `listener` is not registered with the receiver, calling this method has no effect.

Specified by:
  `removeVerticalRulerListener` in interface `IVerticalRulerInfoExtension`
Parameters:
  `listener` - the listener to be removed