oracle.javatools.editor.gutter
Interface Gutter

All Known Subinterfaces:

CodeEditorGutter

All Known Implementing Classes:

LineGutterPlugin

public interface Gutter

The Gutter interface describes a visual component that is displayed vertically to the left of a BasicEditorPane. The Gutter tracks the BasicEditorPane such that they have the same height and same number of lines. The Gutter is used to display Icons associated with specific lines in the editor pane.

The interface provides facilities for adding multiple columns of icons, tracking line changes, and responding to mouse clicks in the Gutter component. Note that all line-numbers are 1-based, unlike the underlying LineMap of the document - this is because this is a visual component for users, who naturally expect line numbers to start with 1.

Note that when creating columns, a advisory pixel width is specified. This may be used by the underlying implementation to lay out, and center the columns properly. For clients that know the widths of the icons to be placed in the columns, these values should be used. If not sure what width to set, use the DEFAULT_WIDTH constant provided.

See Also:

GutterMark, GutterClickListener, GutterTrackingListener

Field Summary

static int	DEFAULT_WIDTH Public constant for some reasonable default width for a column.
static int	MAXIMUM_WIDTH Public constant for the maximum width that a column can be constrained to be.
static int	MINIMUM_WIDTH Public constant for the minimum width that a column can be constrained to be.

Method Summary

boolean	addColumn(java.lang.String columnName, int pixelWidth, boolean firstColumn) Creates a new column that can contain GutterMarks for displaying icons in the Gutter.
boolean	addColumn(java.lang.String columnName, int pixelWidth, java.lang.String existingColumn, boolean insertBefore) Creates a new column that can contain GutterMarks for displaying icons in the Gutter.
void	addGutterClickListener(GutterClickListener listener) Registers a GutterClickListener to receive notifications of mouse clicks in this Gutter component.
GutterMark	addGutterMark(java.lang.String columnName, int line, javax.swing.Icon icon, HighlightStyle highlightStyle, GutterTrackingListener listener) Adds a new GutterMark to the specified column for the specified line.
void	removeAllColumns() Removes all existing columns from the Gutter.
boolean	removeColumn(java.lang.String columnName) Removes an existing column from the Gutter and all its marks and icons.
void	removeGutterClickListener(GutterClickListener listener) Deregisters a previously-registered GutterClickListener so that it no longer receives notifications of mouse clicks in this Gutter component.
void	removeGutterMark(GutterMark mark) Removes the mark from the Gutter.

Field Detail

MINIMUM_WIDTH

public static final int MINIMUM_WIDTH

Public constant for the minimum width that a column can be constrained to be. Column widths smaller than 5 will be set to 5.

See Also:

Constant Field Values

DEFAULT_WIDTH

public static final int DEFAULT_WIDTH

Public constant for some reasonable default width for a column.

See Also:

Constant Field Values

MAXIMUM_WIDTH

public static final int MAXIMUM_WIDTH

Public constant for the maximum width that a column can be constrained to be. Column widths larger than 15 will be set to 15.

See Also:

Constant Field Values

Method Detail

addColumn

public boolean addColumn(java.lang.String columnName,
                         int pixelWidth,
                         boolean firstColumn)

Creates a new column that can contain GutterMarks for displaying icons in the Gutter. Returns true if the column was created successfully, or false if there is already an existing column with the same name.

Parameters:

columnName - columnName the name of the column to create

pixelWidth - the requested width of the column in pixels

firstColumn - true to create the column as the left-most (first) column, false to create the column as the right-most (last) column

Returns:

true if the column was created successfully, false if another column already exists with the same name

addColumn

public boolean addColumn(java.lang.String columnName,
                         int pixelWidth,
                         java.lang.String existingColumn,
                         boolean insertBefore)

Creates a new column that can contain GutterMarks for displaying icons in the Gutter. This will attempt to position the column before or after an existing column. Returns true if the column was created successfully, or false if the specified existing column does not exist.

Parameters:

columnName - columnName the name of the column to create

pixelWidth - the requested width of the column in pixels

existingColumn - the name of an existing column to place the new column next to

insertBefore - whether to insert the column before (true) the existing column, or after (false)

Returns:

true if the column was created successfully, false if the specified existing column doesn't exist

removeColumn

public boolean removeColumn(java.lang.String columnName)

Removes an existing column from the Gutter and all its marks and icons. The registered GutterTrackingListener for any tracking marks will automatically be unregistered.

removeAllColumns

public void removeAllColumns()

Removes all existing columns from the Gutter.

addGutterMark

public GutterMark addGutterMark(java.lang.String columnName,
                                int line,
                                javax.swing.Icon icon,
                                HighlightStyle highlightStyle,
                                GutterTrackingListener listener)

Adds a new GutterMark to the specified column for the specified line. The provided icon will be displayed visually in this Gutter column, and the highlight used to highlight the entire line. If a tracking listener is provided, this mark will track user edits in the associated editor document. If no tracking listener is provided, this mark will be non-tracking and will be fixed to the specified line. Returns the newly created GutterMark, or null if the specified line does not exist.

Parameters:

line - the line on which to create the GutterMark

icon - the icon to display visually for this line in the Gutter

highlightStyle - the highlight style to use for highlighting the line, null for no highlight

listener - the tracking listener to associate with this mark for move or remove notifications (for tracking marks only)

Returns:

the newly created GutterMark, or null if the line is invalid

removeGutterMark

public void removeGutterMark(GutterMark mark)

Removes the mark from the Gutter. This will also remove the icon from the Gutter display as well as cancel any line tracking (if any) established for this mark.

Parameters:

mark - the GutterMark to remove

addGutterClickListener

public void addGutterClickListener(GutterClickListener listener)

Registers a GutterClickListener to receive notifications of mouse clicks in this Gutter component.

Parameters:

listener - the listener to register

removeGutterClickListener

public void removeGutterClickListener(GutterClickListener listener)

Deregisters a previously-registered GutterClickListener so that it no longer receives notifications of mouse clicks in this Gutter component.

Parameters:

listener - the listener to register