SyntaxView
Date: 2017-02-11

org.fife.ui.rsyntaxtextarea

## Class SyntaxView

- java.lang.Object
- - javax.swing.text.View
  - - org.fife.ui.rsyntaxtextarea.SyntaxView

- All Implemented Interfaces:
    javax.swing.SwingConstants, javax.swing.text.TabExpander, TokenOrientedView

      public class SyntaxView
      extends javax.swing.text.View
      implements javax.swing.text.TabExpander, TokenOrientedView

  The `javax.swing.text.View` object used by `RSyntaxTextArea` when word wrap is disabled. It implements syntax highlighting for programming languages using the colors and font styles specified by the `RSyntaxTextArea`.

  You don't really have to do anything to use this class, as `RSyntaxTextAreaUI` automatically sets the text area's view to be an instance of this class if word wrap is disabled.

  The tokens that specify how to paint the syntax-highlighted text are gleaned from the text area's `RSyntaxDocument`.

- - ### Field Summary

    - ### Fields inherited from class javax.swing.text.View

      `BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS`

    - ### Fields inherited from interface javax.swing.SwingConstants

      `BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SyntaxView(javax.swing.text.Element elem)` Constructs a new `SyntaxView` wrapped around an element.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `changedUpdate(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)` Gives notification from the document that attributes were changed in a location that this view is responsible for.
    `protected void` | `damageLineRange(int line0, int line1, java.awt.Shape a, java.awt.Component host)` Repaint the given line range.
    `int` | `getNextVisualPositionFrom(int pos, javax.swing.text.Position.Bias b, java.awt.Shape a, int direction, javax.swing.text.Position.Bias[] biasRet)` Provides a way to determine the next visually represented model location that one might place a caret.
    `float` | `getPreferredSpan(int axis)` Determines the preferred span for this view along an axis.
    `Token` | `getTokenListForPhysicalLineAbove(int offset)` Returns a token list for the physical line above the physical line containing the specified offset into the document.
    `Token` | `getTokenListForPhysicalLineBelow(int offset)` Returns a token list for the physical line below the physical line containing the specified offset into the document.
    `void` | `insertUpdate(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)` Gives notification that something was inserted into the document in a location that this view is responsible for.
    `protected java.awt.Rectangle` | `lineToRect(java.awt.Shape a, int line)` Determine the rectangle that represents the given line.
    `java.awt.Shape` | `modelToView(int p0, javax.swing.text.Position.Bias b0, int p1, javax.swing.text.Position.Bias b1, java.awt.Shape a)` Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space.
    `java.awt.Shape` | `modelToView(int pos, java.awt.Shape a, javax.swing.text.Position.Bias b)` Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
    `float` | `nextTabStop(float x, int tabOffset)` Returns the next tab stop position after a given reference position.
    `void` | `paint(java.awt.Graphics g, java.awt.Shape a)` Actually paints the text area.
    `void` | `removeUpdate(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)` Gives notification that something was removed from the document in a location that this view is responsible for.
    `void` | `setSize(float width, float height)`
    `protected void` | `updateDamage(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)` Repaint the region of change covered by the given document event.
    `int` | `viewToModel(float fx, float fy, java.awt.Shape a, javax.swing.text.Position.Bias[] bias)` Provides a mapping from the view coordinate space to the logical coordinate space of the model.
    `int` | `yForLine(java.awt.Rectangle alloc, int line)` Returns the y-coordinate of the specified line.
    `int` | `yForLineContaining(java.awt.Rectangle alloc, int offs)` Returns the y-coordinate of the line containing a specified offset.

    - ### Methods inherited from class javax.swing.text.View

      `append, breakView, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, preferenceChanged, remove, removeAll, replace, setParent, updateChildren, updateLayout, viewToModel`

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

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

- - ### Constructor Detail

    - #### SyntaxView

          public SyntaxView(javax.swing.text.Element elem)

      Constructs a new `SyntaxView` wrapped around an element.
      Parameters:
        `elem` - The element representing the text to display.

  - ### Method Detail

    - #### changedUpdate

          public void changedUpdate(javax.swing.event.DocumentEvent changes,
                           java.awt.Shape a,
                           javax.swing.text.ViewFactory f)

      Gives notification from the document that attributes were changed in a location that this view is responsible for.
      Overrides:
        `changedUpdate` in class `javax.swing.text.View`
      Parameters:
        `changes` - the change information from the associated document
        `a` - the current allocation of the view
        `f` - the factory to use to rebuild if the view has children
      See Also:
        `View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)`

    - #### damageLineRange

          protected void damageLineRange(int line0,
                             int line1,
                             java.awt.Shape a,
                             java.awt.Component host)

      Repaint the given line range.
      Parameters:
        `line0` - The starting line number to repaint. This must be a valid line number in the model.
        `line1` - The ending line number to repaint. This must be a valid line number in the model.
        `a` - The region allocated for the view to render into.
        `host` - The component hosting the view (used to call repaint).

    - #### getNextVisualPositionFrom

          public int getNextVisualPositionFrom(int pos,
                                      javax.swing.text.Position.Bias b,
                                      java.awt.Shape a,
                                      int direction,
                                      javax.swing.text.Position.Bias[] biasRet)
                                        throws javax.swing.text.BadLocationException

      Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.
      Overrides:
        `getNextVisualPositionFrom` in class `javax.swing.text.View`
      Parameters:
        `pos` - the position to convert >= 0
        `a` - the allocated region to render into
        `direction` - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH.
      Returns:
        the location within the model that best represents the next location visual position.
      Throws:
        `javax.swing.text.BadLocationException`
        `java.lang.IllegalArgumentException` - for an invalid direction

    - #### getPreferredSpan

          public float getPreferredSpan(int axis)

      Determines the preferred span for this view along an axis.
      Specified by:
        `getPreferredSpan` in class `javax.swing.text.View`
      Parameters:
        `axis` - may be either View.X_AXIS or View.Y_AXIS
      Returns:
        the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
      Throws:
        `java.lang.IllegalArgumentException` - for an invalid axis

    - #### getTokenListForPhysicalLineAbove

          public Token getTokenListForPhysicalLineAbove(int offset)

      Returns a token list for the physical line above the physical line containing the specified offset into the document. Note that for this plain (non-wrapped) view, this is simply the token list for the logical line above the line containing `offset`, since lines are not wrapped.
      Specified by:
        `getTokenListForPhysicalLineAbove` in interface `TokenOrientedView`
      Parameters:
        `offset` - The offset in question.
      Returns:
        A token list for the physical (and in this view, logical) line before this one. If `offset` is in the first line in the document, `null` is returned.

    - #### getTokenListForPhysicalLineBelow

          public Token getTokenListForPhysicalLineBelow(int offset)

      Returns a token list for the physical line below the physical line containing the specified offset into the document. Note that for this plain (non-wrapped) view, this is simply the token list for the logical line below the line containing `offset`, since lines are not wrapped.
      Specified by:
        `getTokenListForPhysicalLineBelow` in interface `TokenOrientedView`
      Parameters:
        `offset` - The offset in question.
      Returns:
        A token list for the physical (and in this view, logical) line after this one. If `offset` is in the last physical line in the document, `null` is returned.

    - #### insertUpdate

          public void insertUpdate(javax.swing.event.DocumentEvent changes,
                          java.awt.Shape a,
                          javax.swing.text.ViewFactory f)

      Gives notification that something was inserted into the document in a location that this view is responsible for.
      Overrides:
        `insertUpdate` in class `javax.swing.text.View`
      Parameters:
        `changes` - The change information from the associated document.
        `a` - The current allocation of the view.
        `f` - The factory to use to rebuild if the view has children.

    - #### lineToRect

          protected java.awt.Rectangle lineToRect(java.awt.Shape a,
                                      int line)

      Determine the rectangle that represents the given line.
      Parameters:
        `a` - The region allocated for the view to render into
        `line` - The line number to find the region of. This must be a valid line number in the model.

    - #### modelToView

          public java.awt.Shape modelToView(int pos,
                                   java.awt.Shape a,
                                   javax.swing.text.Position.Bias b)
                                     throws javax.swing.text.BadLocationException

      Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
      Specified by:
        `modelToView` in class `javax.swing.text.View`
      Parameters:
        `pos` - the position to convert >= 0
        `a` - the allocated region to render into
      Returns:
        the bounding box of the given position
      Throws:
        `javax.swing.text.BadLocationException` - if the given position does not represent a valid location in the associated document
      See Also:
        `View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)`

    - #### modelToView

          public java.awt.Shape modelToView(int p0,
                                   javax.swing.text.Position.Bias b0,
                                   int p1,
                                   javax.swing.text.Position.Bias b1,
                                   java.awt.Shape a)
                                     throws javax.swing.text.BadLocationException

      Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space. The specified region is created as a union of the first and last character positions.

      This is implemented to subtract the width of the second character, as this view's `modelToView` actually returns the width of the character instead of "1" or "0" like the View implementations in `javax.swing.text`. Thus, if we don't override this method, the `View` implementation will return one character's width too much for its consumers (implementations of `javax.swing.text.Highlighter`).

      Overrides:
        `modelToView` in class `javax.swing.text.View`
      Parameters:
        `p0` - the position of the first character (>=0)
        `b0` - The bias of the first character position, toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; `b0` will have one of these values:
        - `Position.Bias.Forward`
        - `Position.Bias.Backward`
        `p1` - the position of the last character (>=0)
        `b1` - the bias for the second character position, defined one of the legal values shown above
        `a` - the area of the view, which encompasses the requested region
      Returns:
        the bounding box which is a union of the region specified by the first and last character positions
      Throws:
        `javax.swing.text.BadLocationException` - if the given position does not represent a valid location in the associated document
        `java.lang.IllegalArgumentException` - if `b0` or `b1` are not one of the legal `Position.Bias` values listed above
      See Also:
        `View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])`

    - #### nextTabStop

          public float nextTabStop(float x,
                          int tabOffset)

      Returns the next tab stop position after a given reference position. This implementation does not support things like centering so it ignores the tabOffset argument.
      Specified by:
        `nextTabStop` in interface `javax.swing.text.TabExpander`
      Parameters:
        `x` - the current position >= 0
        `tabOffset` - the position within the text stream that the tab occurred at >= 0.
      Returns:
        the tab stop, measured in points >= 0

    - #### paint

          public void paint(java.awt.Graphics g,
                   java.awt.Shape a)

      Actually paints the text area. Only lines that have been damaged are repainted.
      Specified by:
        `paint` in class `javax.swing.text.View`
      Parameters:
        `g` - The graphics context with which to paint.
        `a` - The allocated region in which to render.

    - #### removeUpdate

          public void removeUpdate(javax.swing.event.DocumentEvent changes,
                          java.awt.Shape a,
                          javax.swing.text.ViewFactory f)

      Gives notification that something was removed from the document in a location that this view is responsible for.
      Overrides:
        `removeUpdate` in class `javax.swing.text.View`
      Parameters:
        `changes` - the change information from the associated document
        `a` - the current allocation of the view
        `f` - the factory to use to rebuild if the view has children

    - #### setSize

          public void setSize(float width,
                     float height)

      Overrides:
        `setSize` in class `javax.swing.text.View`

    - #### updateDamage

          protected void updateDamage(javax.swing.event.DocumentEvent changes,
                          java.awt.Shape a,
                          javax.swing.text.ViewFactory f)

      Repaint the region of change covered by the given document event. Damages the line that begins the range to cover the case when the insert/remove is only on one line. If lines are added or removed, damages the whole view. The longest line is checked to see if it has changed.

    - #### viewToModel

          public int viewToModel(float fx,
                        float fy,
                        java.awt.Shape a,
                        javax.swing.text.Position.Bias[] bias)

      Provides a mapping from the view coordinate space to the logical coordinate space of the model.
      Specified by:
        `viewToModel` in class `javax.swing.text.View`
      Parameters:
        `fx` - the X coordinate >= 0
        `fy` - the Y coordinate >= 0
        `a` - the allocated region to render into
      Returns:
        the location within the model that best represents the given point in the view >= 0

    - #### yForLine

          public int yForLine(java.awt.Rectangle alloc,
                     int line)
                       throws javax.swing.text.BadLocationException

      Returns the y-coordinate of the specified line.

      This method is quicker than using traditional `modelToView(int)` calls, as the entire bounding box isn't computed.

      Parameters:
        `alloc` - The area the text area can render into.
        `line` - The line number.
      Returns:
        The y-coordinate of the top of the line, or `-1` if this text area doesn't yet have a positive size or the line is hidden (i.e. from folding).
      Throws:
        `javax.swing.text.BadLocationException` - If `line` isn't a valid line number for this document.

    - #### yForLineContaining

          public int yForLineContaining(java.awt.Rectangle alloc,
                               int offs)
                                 throws javax.swing.text.BadLocationException

      Returns the y-coordinate of the line containing a specified offset.

      This method is quicker than using traditional `modelToView(int)` calls, as the entire bounding box isn't computed.

      Parameters:
        `alloc` - The area the text area can render into.
        `offs` - The offset info the document.
      Returns:
        The y-coordinate of the top of the offset, or `-1` if this text area doesn't yet have a positive size or the line is hidden (i.e. from folding).
      Throws:
        `javax.swing.text.BadLocationException` - If `offs` isn't a valid offset into the document.