org.fife.ui.rtextarea

## Class Gutter

- java.lang.Object
- - java.awt.Component
  - - java.awt.Container
    - - javax.swing.JComponent
      - - javax.swing.JPanel
        - - org.fife.ui.rtextarea.Gutter

All Implemented Interfaces:
  ImageObserver, MenuContainer, Serializable, Accessible

    public class Gutter
    extends JPanel

The gutter is the component on the left-hand side of the text area that displays optional information such as line numbers, fold regions, and icons (for bookmarks, debugging breakpoints, error markers, etc.).

Icons can be added on a per-line basis to visually mark syntax errors, lines with breakpoints set on them, etc. To add icons to the gutter, you must first call `RTextScrollPane.setIconRowHeaderEnabled(boolean)` on the parent scroll pane, to make the icon area visible. Then, you can add icons that track either lines in the document, or offsets, via `addLineTrackingIcon(int, Icon)` and `addOffsetTrackingIcon(int, Icon)`, respectively. To remove an icon you've added, use `removeTrackingIcon(GutterIconInfo)`.

In addition to support for arbitrary per-line icons, this component also has built-in support for displaying icons representing "bookmarks;" that is, lines a user can cycle through via F2 and Shift+F2. Bookmarked lines are toggled via Ctrl+F2. In order to enable bookmarking, you must first assign an icon to represent a bookmarked line, then actually enable the feature:

     Gutter gutter = scrollPane.getGutter();
     gutter.setBookmarkIcon(new ImageIcon("bookmark.png"));
     gutter.setBookmarkingEnabled(true);

Version:
  1.0
Author:
  Robert Futrell
See Also:
  `GutterIconInfo`, Serialized Form

### Nested Class Summary

### Nested classes/interfaces inherited from class javax.swing.JPanel

`JPanel.AccessibleJPanel`

### Nested classes/interfaces inherited from class javax.swing.JComponent

`JComponent.AccessibleJComponent`

### Nested classes/interfaces inherited from class java.awt.Container

`Container.AccessibleAWTContainer`

### Nested classes/interfaces inherited from class java.awt.Component

`Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy`

### Field Summary

Fields
`static Color` `DEFAULT_ACTIVE_LINE_RANGE_COLOR` The color used to highlight active line ranges if none is specified.

### Fields inherited from class javax.swing.JComponent

`accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW`

### Fields inherited from class java.awt.Component

`BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

### Fields inherited from interface java.awt.image.ImageObserver

`ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

### Constructor Summary

Constructors
Constructor and Description
`Gutter(RTextArea textArea)` Constructor.

### Method Summary

Methods
`GutterIconInfo` `addLineTrackingIcon(int line, Icon icon)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
`GutterIconInfo` `addLineTrackingIcon(int line, Icon icon, String tip)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
`GutterIconInfo` `addOffsetTrackingIcon(int offs, Icon icon)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
`GutterIconInfo` `addOffsetTrackingIcon(int offs, Icon icon, String tip)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
`Color` `getActiveLineRangeColor()` Returns the color used to paint the active line range, if any.
`Icon` `getBookmarkIcon()` Returns the icon to use for bookmarks.
`GutterIconInfo[]` `getBookmarks()` Returns the bookmarks known to this gutter.
`Color` `getBorderColor()` Returns the color of the "border" line.
`Color` `getFoldBackground()` Returns the background color used by the (default) fold icons.
`Color` `getFoldIndicatorForeground()` Returns the foreground color of the fold indicator.
`Color` `getLineNumberColor()` Returns the color to use to paint line numbers.
`Font` `getLineNumberFont()` Returns the font used for line numbers.
`int` `getLineNumberingStartIndex()` Returns the starting line's line number.
`boolean` `getLineNumbersEnabled()` Returns `true` if the line numbers are enabled and visible.
`boolean` `getShowCollapsedRegionToolTips()` Returns whether tool tips are displayed showing the contents of collapsed fold regions when the mouse hovers over a +/- icon.
`GutterIconInfo[]` `getTrackingIcons(Point p)` Returns the tracking icons at the specified view position.
`boolean` `isBookmarkingEnabled()` Returns whether bookmarking is enabled.
`boolean` `isFoldIndicatorEnabled()` Returns whether the fold indicator is enabled.
`boolean` `isIconRowHeaderEnabled()` Returns whether the icon row header is enabled.
`void` `removeAllTrackingIcons()` Removes all tracking icons.
`void` `removeTrackingIcon(GutterIconInfo tag)` Removes the specified tracking icon.
`void` `setActiveLineRangeColor(Color color)` Sets the color to use to render active line ranges.
`void` `setBookmarkIcon(Icon icon)` Sets the icon to use for bookmarks.
`void` `setBookmarkingEnabled(boolean enabled)` Sets whether bookmarking is enabled.
`void` `setBorder(Border border)`
`void` `setBorderColor(Color color)` Sets the color for the "border" line.
`void` `setComponentOrientation(ComponentOrientation o)`
`void` `setFoldBackground(Color bg)` Sets the background color used by the (default) fold icons.
`void` `setFoldIcons(Icon collapsedIcon, Icon expandedIcon)` Sets the icons to use to represent collapsed and expanded folds.
`void` `setFoldIndicatorEnabled(boolean enabled)` Toggles whether the fold indicator is enabled.
`void` `setFoldIndicatorForeground(Color fg)` Sets the foreground color used by the fold indicator.
`void` `setLineNumberColor(Color color)` Sets the color to use to paint line numbers.
`void` `setLineNumberFont(Font font)` Sets the font used for line numbers.
`void` `setLineNumberingStartIndex(int index)` Sets the starting line's line number.
`void` `setShowCollapsedRegionToolTips(boolean show)` Toggles whether tool tips should be displayed showing the contents of collapsed fold regions when the mouse hovers over a +/- icon.
`boolean` `toggleBookmark(int line)` Programatically toggles whether there is a bookmark for the specified line.

### Methods inherited from class javax.swing.JPanel

`getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI`

### Methods inherited from class javax.swing.JComponent

`addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update`

### Methods inherited from class java.awt.Container

`add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree`

### Methods inherited from class java.awt.Component

`action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle`

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

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

### Field Detail

#### DEFAULT_ACTIVE_LINE_RANGE_COLOR

    public static final Color DEFAULT_ACTIVE_LINE_RANGE_COLOR

The color used to highlight active line ranges if none is specified.

### Constructor Detail

#### Gutter

    public Gutter(RTextArea textArea)

Constructor.

Parameters:
  `textArea` - The parent text area.

### Method Detail

#### addLineTrackingIcon

    public GutterIconInfo addLineTrackingIcon(int line,
                                     Icon icon)
                                       throws BadLocationException

Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers. This is useful for marking things such as source code errors.

Parameters:
  `line` - The line to track (zero-based).
  `icon` - The icon to display. This should be small (say 16x16).
Returns:
  A tag for this icon. This can later be used in a call to `removeTrackingIcon(GutterIconInfo)` to remove this icon.
Throws:
  `BadLocationException` - If `offs` is an invalid offset into the text area.
See Also:
  `addLineTrackingIcon(int, Icon, String)`, `addOffsetTrackingIcon(int, Icon)`, `removeTrackingIcon(GutterIconInfo)`

#### addLineTrackingIcon

    public GutterIconInfo addLineTrackingIcon(int line,
                                     Icon icon,
                                     String tip)
                                       throws BadLocationException

Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers. This is useful for marking things such as source code errors.

Parameters:
  `line` - The line to track (zero-based).
  `icon` - The icon to display. This should be small (say 16x16).
  `tip` - An optional tool tip for the icon.
Returns:
  A tag for this icon. This can later be used in a call to `removeTrackingIcon(GutterIconInfo)` to remove this icon.
Throws:
  `BadLocationException` - If `offs` is an invalid offset into the text area.
See Also:
  `addLineTrackingIcon(int, Icon)`, `addOffsetTrackingIcon(int, Icon)`, `removeTrackingIcon(GutterIconInfo)`

#### addOffsetTrackingIcon

    public GutterIconInfo addOffsetTrackingIcon(int offs,
                                       Icon icon)
                                         throws BadLocationException

Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers. This is useful for marking things such as source code errors.

Parameters:
  `offs` - The offset to track.
  `icon` - The icon to display. This should be small (say 16x16).
Returns:
  A tag for this icon.
Throws:
  `BadLocationException` - If `offs` is an invalid offset into the text area.
See Also:
  `addOffsetTrackingIcon(int, Icon, String)`, `addLineTrackingIcon(int, Icon)`, `removeTrackingIcon(GutterIconInfo)`

#### addOffsetTrackingIcon

    public GutterIconInfo addOffsetTrackingIcon(int offs,
                                       Icon icon,
                                       String tip)
                                         throws BadLocationException

Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers. This is useful for marking things such as source code errors.

Parameters:
  `offs` - The offset to track.
  `icon` - The icon to display. This should be small (say 16x16).
  `tip` - An optional tool tip for the icon.
Returns:
  A tag for this icon.
Throws:
  `BadLocationException` - If `offs` is an invalid offset into the text area.
See Also:
  `addOffsetTrackingIcon(int, Icon)`, `addLineTrackingIcon(int, Icon)`, `removeTrackingIcon(GutterIconInfo)`

#### getActiveLineRangeColor

    public Color getActiveLineRangeColor()

Returns the color used to paint the active line range, if any.

Returns:
  The color.
See Also:
  `setActiveLineRangeColor(Color)`

#### getBookmarkIcon

    public Icon getBookmarkIcon()

Returns the icon to use for bookmarks.

Returns:
  The icon to use for bookmarks. If this is `null`, bookmarking is effectively disabled.
See Also:
  `setBookmarkIcon(Icon)`, `isBookmarkingEnabled()`

#### getBookmarks

    public GutterIconInfo[] getBookmarks()

Returns the bookmarks known to this gutter.

Returns:
  The bookmarks. If there are no bookmarks, an empty array is returned.

#### getBorderColor

    public Color getBorderColor()

Returns the color of the "border" line.

Returns:
  The color.
See Also:
  `setBorderColor(Color)`

#### getFoldBackground

    public Color getFoldBackground()

Returns the background color used by the (default) fold icons.

Returns:
  The background color.
See Also:
  `setFoldBackground(Color)`

#### getFoldIndicatorForeground

    public Color getFoldIndicatorForeground()

Returns the foreground color of the fold indicator.

Returns:
  The foreground color of the fold indicator.
See Also:
  `setFoldIndicatorForeground(Color)`

#### getLineNumberColor

    public Color getLineNumberColor()

Returns the color to use to paint line numbers.

Returns:
  The color used when painting line numbers.
See Also:
  `setLineNumberColor(Color)`

#### getLineNumberFont

    public Font getLineNumberFont()

Returns the font used for line numbers.

Returns:
  The font used for line numbers.
See Also:
  `setLineNumberFont(Font)`

#### getLineNumberingStartIndex

    public int getLineNumberingStartIndex()

Returns the starting line's line number. The default value is `1`.

Returns:
  The index
See Also:
  `setLineNumberingStartIndex(int)`

#### getLineNumbersEnabled

    public boolean getLineNumbersEnabled()

Returns `true` if the line numbers are enabled and visible.

Returns:
  Whether or not line numbers are visible.

#### getShowCollapsedRegionToolTips

    public boolean getShowCollapsedRegionToolTips()

Returns whether tool tips are displayed showing the contents of collapsed fold regions when the mouse hovers over a +/- icon.

Returns:
  Whether these tool tips are displayed.
See Also:
  `setShowCollapsedRegionToolTips(boolean)`

#### getTrackingIcons

    public GutterIconInfo[] getTrackingIcons(Point p)
                                      throws BadLocationException

Returns the tracking icons at the specified view position.

Parameters:
  `p` - The view position.
Returns:
  The tracking icons at that position. If there are no tracking icons there, this will be an empty array.
Throws:
  `BadLocationException` - If `p` is invalid.

#### isFoldIndicatorEnabled

    public boolean isFoldIndicatorEnabled()

Returns whether the fold indicator is enabled.

Returns:
  Whether the fold indicator is enabled.
See Also:
  `setFoldIndicatorEnabled(boolean)`

#### isBookmarkingEnabled

    public boolean isBookmarkingEnabled()

Returns whether bookmarking is enabled.

Returns:
  Whether bookmarking is enabled.
See Also:
  `setBookmarkingEnabled(boolean)`

#### isIconRowHeaderEnabled

    public boolean isIconRowHeaderEnabled()

Returns whether the icon row header is enabled.

Returns:
  Whether the icon row header is enabled.

#### removeTrackingIcon

    public void removeTrackingIcon(GutterIconInfo tag)

Removes the specified tracking icon.

Parameters:
  `tag` - A tag for an icon in the gutter, as returned from either `addLineTrackingIcon(int, Icon)` or `addOffsetTrackingIcon(int, Icon)`.
See Also:
  `removeAllTrackingIcons()`, `addLineTrackingIcon(int, Icon)`, `addOffsetTrackingIcon(int, Icon)`

#### removeAllTrackingIcons

    public void removeAllTrackingIcons()

Removes all tracking icons.

See Also:
  `removeTrackingIcon(GutterIconInfo)`, `addOffsetTrackingIcon(int, Icon)`

#### setActiveLineRangeColor

    public void setActiveLineRangeColor(Color color)

Sets the color to use to render active line ranges.

Parameters:
  `color` - The color to use. If this is null, then the default color is used.
See Also:
  `getActiveLineRangeColor()`, `DEFAULT_ACTIVE_LINE_RANGE_COLOR`

#### setBookmarkIcon

    public void setBookmarkIcon(Icon icon)

Sets the icon to use for bookmarks.

Parameters:
  `icon` - The new bookmark icon. If this is `null`, bookmarking is effectively disabled.
See Also:
  `getBookmarkIcon()`, `isBookmarkingEnabled()`

#### setBookmarkingEnabled

    public void setBookmarkingEnabled(boolean enabled)

Sets whether bookmarking is enabled. Note that a bookmarking icon must be set via `setBookmarkIcon(Icon)` before bookmarks are truly enabled.

Parameters:
  `enabled` - Whether bookmarking is enabled.
See Also:
  `isBookmarkingEnabled()`, `setBookmarkIcon(Icon)`

#### setBorderColor

    public void setBorderColor(Color color)

Sets the color for the "border" line.

Parameters:
  `color` - The new color.
See Also:
  `getBorderColor()`

#### setComponentOrientation

    public void setComponentOrientation(ComponentOrientation o)

Overrides:
  `setComponentOrientation` in class `Component`

#### setFoldIcons

    public void setFoldIcons(Icon collapsedIcon,
                    Icon expandedIcon)

Sets the icons to use to represent collapsed and expanded folds.

Parameters:
  `collapsedIcon` - The collapsed fold icon. This cannot be `null`.
  `expandedIcon` - The expanded fold icon. This cannot be `null`.

#### setFoldIndicatorEnabled

    public void setFoldIndicatorEnabled(boolean enabled)

Toggles whether the fold indicator is enabled.

Parameters:
  `enabled` - Whether the fold indicator should be enabled.
See Also:
  `isFoldIndicatorEnabled()`

#### setFoldBackground

    public void setFoldBackground(Color bg)

Sets the background color used by the (default) fold icons.

Parameters:
  `bg` - The new background color.
See Also:
  `getFoldBackground()`

#### setFoldIndicatorForeground

    public void setFoldIndicatorForeground(Color fg)

Sets the foreground color used by the fold indicator.

Parameters:
  `fg` - The new fold indicator foreground.
See Also:
  `getFoldIndicatorForeground()`

#### setLineNumberColor

    public void setLineNumberColor(Color color)

Sets the color to use to paint line numbers.

Parameters:
  `color` - The color to use when painting line numbers.
See Also:
  `getLineNumberColor()`

#### setLineNumberFont

    public void setLineNumberFont(Font font)

Sets the font used for line numbers.

Parameters:
  `font` - The font to use. This cannot be `null`.
See Also:
  `getLineNumberFont()`

#### setLineNumberingStartIndex

    public void setLineNumberingStartIndex(int index)

Sets the starting line's line number. The default value is `1`. Applications can call this method to change this value if they are displaying a subset of lines in a file, for example.

Parameters:
  `index` - The new index.
See Also:
  `getLineNumberingStartIndex()`

#### setShowCollapsedRegionToolTips

    public void setShowCollapsedRegionToolTips(boolean show)

Toggles whether tool tips should be displayed showing the contents of collapsed fold regions when the mouse hovers over a +/- icon.

Parameters:
  `show` - Whether to show these tool tips.
See Also:
  `getShowCollapsedRegionToolTips()`

#### toggleBookmark

    public boolean toggleBookmark(int line)
                           throws BadLocationException

Programatically toggles whether there is a bookmark for the specified line. If bookmarking is not enabled, this method does nothing.

Parameters:
  `line` - The line.
Returns:
  Whether a bookmark is now at the specified line.
Throws:
  `BadLocationException` - If `line` is an invalid line number in the text area.

#### setBorder

    public void setBorder(Border border)

Overrides:
  `setBorder` in class `JComponent`