org.fife.ui.rtextarea
Class Gutter

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by org.fife.ui.rtextarea.Gutter
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable

public class Gutter
extends JComponent

The gutter is the component on the left-hand side of the text area that displays optional information such as line numbers and icons (for bookmarks, debugging breakpoints, error markers, 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).

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

Nested Class Summary
 
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 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
Gutter(RTextArea textArea)
          Constructor.
 
Method Summary
 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 addOffsetTrackingIcon(int offs, Icon icon)
          Adds an icon that tracks an offset in the document, and is displayed adjacent to the line numbers.
 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 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.
 Object[] getTrackingIcons(Point p)
          Returns the tracking icons at the specified view position.
 boolean isBookmarkingEnabled()
          Returns whether bookmarking 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 setBookmarkIcon(Icon icon)
          Sets the icon to use for bookmarks.
 void setBookmarkingEnabled(boolean enabled)
          Sets whether bookmarking is enabled.
 void setBorderColor(Color color)
          Sets the color for the "border" line.
 void setComponentOrientation(ComponentOrientation o)
          
 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.
 boolean toggleBookmark(int line)
          Programatically toggles whether there is a bookmark for the specified line.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, 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, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, 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, updateUI
 
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
 

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:
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:
addLineTrackingIcon(int, Icon), removeTrackingIcon(GutterIconInfo)

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)

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.

getTrackingIcons

public Object[] 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.

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)

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

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()

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.