IconRowHeader
Date: 2017-02-11

org.fife.ui.rtextarea

## Class IconRowHeader

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

- All Implemented Interfaces:
    java.awt.event.MouseListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible
  Direct Known Subclasses:
    FoldingAwareIconRowHeader

      public class IconRowHeader
      extends javax.swing.JPanel
      implements java.awt.event.MouseListener

  Renders icons in the `Gutter`. This can be used to visually mark lines containing syntax errors, lines with breakpoints set on them, etc.

  This component 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, or by clicking in the icon area at the line to bookmark. In order to enable bookmarking, you must first assign an icon to represent a bookmarked line, then actually enable the feature. This is actually done on the parent `Gutter` component:

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

  See Also:
    `FoldingAwareIconRowHeader`, Serialized Form

- - ### Nested Class Summary

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

      `javax.swing.JPanel.AccessibleJPanel`

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

      `javax.swing.JComponent.AccessibleJComponent`

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

      `java.awt.Container.AccessibleAWTContainer`

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

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

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `activeLineRangeEnd` The end line in the active line range.
    `protected int` | `activeLineRangeStart` The first line in the active line range.
    `protected int` | `currentLineCount` The number of lines in the text area.
    `protected RTextArea` | `textArea` The text area whose lines we are marking with icons.
    `protected java.awt.Insets` | `textAreaInsets` Used in `paintComponent(Graphics)` to prevent reallocation on each paint.
    `protected java.util.List<org.fife.ui.rtextarea.IconRowHeader.GutterIconImpl>` | `trackingIcons` The icons to render.
    `protected java.awt.Rectangle` | `visibleRect` Used in `paintComponent(Graphics)` to prevent reallocation on each paint.
    `protected int` | `width` The width of this component.

    - ### 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
    `IconRowHeader(RTextArea textArea)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `GutterIconInfo` | `addOffsetTrackingIcon(int offs, javax.swing.Icon icon)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
    `GutterIconInfo` | `addOffsetTrackingIcon(int offs, javax.swing.Icon icon, java.lang.String tip)` Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
    `void` | `clearActiveLineRange()` Clears the active line range.
    `java.awt.Color` | `getActiveLineRangeColor()` Returns the color used to paint the active line range, if any.
    `javax.swing.Icon` | `getBookmarkIcon()` Returns the icon to use for bookmarks.
    `GutterIconInfo[]` | `getBookmarks()` Returns the bookmarks known to this gutter.
    `protected static java.awt.Rectangle` | `getChildViewBounds(javax.swing.text.View parent, int line, java.awt.Rectangle editorRect)` Returns the bounds of a child view as a rectangle, since `View`s tend to use `Shape`.
    `protected Gutter` | `getGutter()` Returns the parent `Gutter` component.
    `java.awt.Dimension` | `getPreferredSize()`
    `java.lang.String` | `getToolTipText(java.awt.event.MouseEvent e)` Overridden to display the tool tip of any icons on this line.
    `protected org.fife.ui.rtextarea.IconRowHeader.GutterIconImpl` | `getTrackingIcon(int index)`
    `GutterIconInfo[]` | `getTrackingIcons(int line)` Returns the tracking icons at the specified line.
    `protected void` | `init()` Called by the constructor before the text area is set.
    `boolean` | `isBookmarkingEnabled()` Returns whether bookmarking is enabled.
    `void` | `mouseClicked(java.awt.event.MouseEvent e)`
    `void` | `mouseEntered(java.awt.event.MouseEvent e)`
    `void` | `mouseExited(java.awt.event.MouseEvent e)`
    `void` | `mousePressed(java.awt.event.MouseEvent e)`
    `void` | `mouseReleased(java.awt.event.MouseEvent e)`
    `protected void` | `paintBackgroundImpl(java.awt.Graphics g, java.awt.Rectangle visibleRect)` Paints the background of this component.
    `protected void` | `paintComponent(java.awt.Graphics g)`
    `void` | `removeAllTrackingIcons()` Removes all tracking icons.
    `void` | `removeTrackingIcon(java.lang.Object tag)` Removes the specified tracking icon.
    `void` | `setActiveLineRange(int startLine, int endLine)` Highlights a range of lines in the icon area.
    `void` | `setActiveLineRangeColor(java.awt.Color color)` Sets the color to use to render active line ranges.
    `void` | `setBookmarkIcon(javax.swing.Icon icon)` Sets the icon to use for bookmarks.
    `void` | `setBookmarkingEnabled(boolean enabled)` Sets whether bookmarking is enabled.
    `void` | `setInheritsGutterBackground(boolean inherits)` Sets whether the icon area inherits the gutter background (as opposed to painting with its own, default "panel" color, which is the default).
    `void` | `setTextArea(RTextArea textArea)` Sets the text area being displayed.
    `boolean` | `toggleBookmark(int line)` Programatically toggles whether there is a bookmark for the specified line.
    `void` | `updateUI()`

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

      `getAccessibleContext, getUI, getUIClassID, paramString, setUI`

    - ### 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, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, 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, setBorder, 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, 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, setComponentOrientation, 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

    - #### trackingIcons

          protected java.util.List<org.fife.ui.rtextarea.IconRowHeader.GutterIconImpl> trackingIcons

      The icons to render.

    - #### width

          protected int width

      The width of this component.

    - #### visibleRect

          protected java.awt.Rectangle visibleRect

      Used in `paintComponent(Graphics)` to prevent reallocation on each paint.

    - #### textAreaInsets

          protected java.awt.Insets textAreaInsets

      Used in `paintComponent(Graphics)` to prevent reallocation on each paint.

    - #### activeLineRangeStart

          protected int activeLineRangeStart

      The first line in the active line range.

    - #### activeLineRangeEnd

          protected int activeLineRangeEnd

      The end line in the active line range.

    - #### textArea

          protected RTextArea textArea

      The text area whose lines we are marking with icons.

    - #### currentLineCount

          protected int currentLineCount

      The number of lines in the text area.

  - ### Constructor Detail

    - #### IconRowHeader

          public IconRowHeader(RTextArea textArea)

      Constructor.
      Parameters:
        `textArea` - The parent text area.

  - ### Method Detail

    - #### addOffsetTrackingIcon

          public GutterIconInfo addOffsetTrackingIcon(int offs,
                                             javax.swing.Icon icon)
                                               throws javax.swing.text.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:
        `javax.swing.text.BadLocationException` - If `offs` is an invalid offset into the text area.
      See Also:
        `removeTrackingIcon(Object)`

    - #### addOffsetTrackingIcon

          public GutterIconInfo addOffsetTrackingIcon(int offs,
                                             javax.swing.Icon icon,
                                             java.lang.String tip)
                                               throws javax.swing.text.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` - A tool tip for the icon.
      Returns:
        A tag for this icon.
      Throws:
        `javax.swing.text.BadLocationException` - If `offs` is an invalid offset into the text area.
      See Also:
        `removeTrackingIcon(Object)`

    - #### clearActiveLineRange

          public void clearActiveLineRange()

      Clears the active line range.
      See Also:
        `setActiveLineRange(int, int)`

    - #### getActiveLineRangeColor

          public java.awt.Color getActiveLineRangeColor()

      Returns the color used to paint the active line range, if any.
      Returns:
        The color.
      See Also:
        `setActiveLineRangeColor(Color)`

    - #### getBookmarkIcon

          public javax.swing.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.

    - #### getPreferredSize

          public java.awt.Dimension getPreferredSize()

      Overrides:
        `getPreferredSize` in class `javax.swing.JComponent`

    - #### getToolTipText

          public java.lang.String getToolTipText(java.awt.event.MouseEvent e)

      Overridden to display the tool tip of any icons on this line.
      Overrides:
        `getToolTipText` in class `javax.swing.JComponent`
      Parameters:
        `e` - The location the mouse is hovering over.

    - #### getTrackingIcon

          protected org.fife.ui.rtextarea.IconRowHeader.GutterIconImpl getTrackingIcon(int index)

    - #### getTrackingIcons

          public GutterIconInfo[] getTrackingIcons(int line)
                                            throws javax.swing.text.BadLocationException

      Returns the tracking icons at the specified line.
      Parameters:
        `line` - The line.
      Returns:
        The tracking icons at that line. If there are no tracking icons there, this will be an empty array.
      Throws:
        `javax.swing.text.BadLocationException` - If `line` is invalid.

    - #### init

          protected void init()

      Called by the constructor before the text area is set. This is a hook to allow subclasses to do any needed initialization. The default implementation does nothing.

    - #### isBookmarkingEnabled

          public boolean isBookmarkingEnabled()

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

    - #### mouseClicked

          public void mouseClicked(java.awt.event.MouseEvent e)

      Specified by:
        `mouseClicked` in interface `java.awt.event.MouseListener`

    - #### mouseEntered

          public void mouseEntered(java.awt.event.MouseEvent e)

      Specified by:
        `mouseEntered` in interface `java.awt.event.MouseListener`

    - #### mouseExited

          public void mouseExited(java.awt.event.MouseEvent e)

      Specified by:
        `mouseExited` in interface `java.awt.event.MouseListener`

    - #### mousePressed

          public void mousePressed(java.awt.event.MouseEvent e)

      Specified by:
        `mousePressed` in interface `java.awt.event.MouseListener`

    - #### mouseReleased

          public void mouseReleased(java.awt.event.MouseEvent e)

      Specified by:
        `mouseReleased` in interface `java.awt.event.MouseListener`

    - #### paintComponent

          protected void paintComponent(java.awt.Graphics g)

      Overrides:
        `paintComponent` in class `javax.swing.JComponent`

    - #### paintBackgroundImpl

          protected void paintBackgroundImpl(java.awt.Graphics g,
                                 java.awt.Rectangle visibleRect)

      Paints the background of this component.
      Parameters:
        `g` - The graphics context.
        `visibleRect` - The visible bounds of this component.

    - #### removeTrackingIcon

          public void removeTrackingIcon(java.lang.Object tag)

      Removes the specified tracking icon.
      Parameters:
        `tag` - A tag for a tracking icon.
      See Also:
        `removeAllTrackingIcons()`, `addOffsetTrackingIcon(int, Icon)`

    - #### removeAllTrackingIcons

          public void removeAllTrackingIcons()

      Removes all tracking icons.
      See Also:
        `removeTrackingIcon(Object)`, `addOffsetTrackingIcon(int, Icon)`

    - #### setActiveLineRange

          public void setActiveLineRange(int startLine,
                                int endLine)

      Highlights a range of lines in the icon area.
      Parameters:
        `startLine` - The start of the line range.
        `endLine` - The end of the line range.
      See Also:
        `clearActiveLineRange()`

    - #### setActiveLineRangeColor

          public void setActiveLineRangeColor(java.awt.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()`, `Gutter.DEFAULT_ACTIVE_LINE_RANGE_COLOR`

    - #### setBookmarkIcon

          public void setBookmarkIcon(javax.swing.Icon icon)

      Sets the icon to use for bookmarks. Any previous bookmark icons are removed.
      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. If this is `false`, any bookmark icons are removed.
      See Also:
        `isBookmarkingEnabled()`, `setBookmarkIcon(Icon)`

    - #### setInheritsGutterBackground

          public void setInheritsGutterBackground(boolean inherits)

      Sets whether the icon area inherits the gutter background (as opposed to painting with its own, default "panel" color, which is the default).
      Parameters:
        `inherits` - Whether the gutter background should be used in the icon row header. If this is `false`, a default, Look-and-feel-dependent color is used.

    - #### setTextArea

          public void setTextArea(RTextArea textArea)

      Sets the text area being displayed. This will clear any tracking icons currently displayed.
      Parameters:
        `textArea` - The text area.

    - #### toggleBookmark

          public boolean toggleBookmark(int line)
                                 throws javax.swing.text.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:
        `javax.swing.text.BadLocationException` - If `line` is an invalid line number in the text area.

    - #### updateUI

          public void updateUI()

      Overrides:
        `updateUI` in class `javax.swing.JPanel`

    - #### getChildViewBounds

          protected static final java.awt.Rectangle getChildViewBounds(javax.swing.text.View parent,
                                              int line,
                                              java.awt.Rectangle editorRect)

      Returns the bounds of a child view as a rectangle, since `View`s tend to use `Shape`.
      Parameters:
        `parent` - The parent view of the child whose bounds we're getting.
        `line` - The index of the child view.
        `editorRect` - Returned from the text area's `getVisibleEditorRect` method.
      Returns:
        The child view's bounds.

    - #### getGutter

          protected Gutter getGutter()

      Returns the parent `Gutter` component.
      Returns:
        The parent `Gutter`.