Class 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);
     
    See Also:
    GutterIconInfo, Serialized Form
    • 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

      • 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.
        See Also:
        toggleBookmark(int)
      • 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)
      • getIconRowHeaderInheritsGutterBackground

        public boolean getIconRowHeaderInheritsGutterBackground()
        Returns whether the icon area inherits the gutter background (as opposed to painting with its own, default "panel" color, which is the default).
        Returns:
        Whether the gutter background is used in the icon row header.
        See Also:
        setIconRowHeaderInheritsGutterBackground(boolean)
      • 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.
      • 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()
      • 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()
      • setIconRowHeaderInheritsGutterBackground

        public void setIconRowHeaderInheritsGutterBackground​(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.
        See Also:
        getIconRowHeaderInheritsGutterBackground()
      • 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.
        See Also:
        getBookmarks()