Package ghidra.app.decompiler.component

# Class ClangHighlightController

java.lang.Object
ghidra.app.decompiler.component.ClangHighlightController

Direct Known Subclasses:
  `LocationClangHighlightController`, `NullClangHighlightController`

public abstract class ClangHighlightController extends Object
Class to handle highlights for a decompiled function.

This class does not paint directly. Rather, this class tracks the currently highlighted tokens and then sets the highlight color on the token when it is highlighted and clears the highlight color when the highlight is removed.

This class maintains the following types of highlights:

- Primary Highlights - triggered by user clicking and some user actions; considered transient and get cleared whenever the location changes. These highlights show state such as the current field, impact of a variable (via a slicing action), or related syntax (such as matching braces)
- Secondary Highlights - triggered by the user to show all occurrences of a particular variable; they will stay until they are manually cleared by a user action. The user can apply multiple secondary highlights at the same time, with different colors for each highlight. These highlights apply to the function in use when the highlight is created. Thus, each function has a unique set of highlights that is maintained between decompilation.
- Global Highlights - triggered by clients of the `DecompilerHighlightService`; they will stay until the client of the service clears the highlight. These highlights apply to every function that is decompiler.

When multiple highlights overlap, their colors will be blended.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static Color`
  `DEFAULT_HIGHLIGHT_COLOR`
  `protected Color`
  `defaultHighlightColor`
  `protected Color`
  `defaultParenColor`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ClangHighlightController()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addBraceHighlight(ClangSyntaxToken token, Color highlightColor)`
  `void`
  `addHighlighter(ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter)`
  `void`
  `addHighlighterHighlights(ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter, Supplier<? extends Collection<ClangToken>> tokens, ColorProvider colorProvider)`
  `void`
  `addListener(ClangHighlightListener listener)`
  `protected void`
  `addPrimaryHighlight(ClangToken token, Color highlightColor)`
  `void`
  `addPrimaryHighlights(ClangNode parentNode, ColorProvider colorProvider)`
  `void`
  `addPrimaryHighlights(ClangNode parentNode, Set<PcodeOp> ops, Color hlColor)`
  `protected List<ClangToken>`
  `addPrimaryHighlightToTokensForParenthesis(ClangSyntaxToken tok, Color highlightColor)`
  If input token is a parenthesis, highlight all tokens between it and its match
  `void`
  `addSecondaryHighlighter(Function function, ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter)`
  Adds the given secondary highlighter, but does not create any highlights.
  `Color`
  `blend(List<Color> colors)`
  `void`
  `clearPrimaryHighlights()`
  `void`
  `dispose()`
  `static ClangHighlightController`
  `dummyIfNull(ClangHighlightController c)`
  `abstract void`
  `fieldLocationChanged(FieldLocation location, Field field, EventTrigger trigger)`
  `Color`
  `getCombinedColor(ClangToken t)`
  Returns the current highlight color for the given token, based upon all known highlights, primary, secondary and highlighters
  `Set<ghidra.app.decompiler.component.ClangDecompilerHighlighter>`
  `getGlobalHighlighters()`
  Returns all global highlighters installed in this controller.
  `ClangToken`
  `getHighlightedToken()`
  Return the current highlighted token (if exists and unique)
  `TokenHighlights`
  `getHighlighterHighlights(DecompilerHighlighter highlighter)`
  Gets all highlights for the given highlighter.
  `String`
  `getPrimaryHighlightedText()`
  Returns the token that has the primary highlight applied, if any.
  `TokenHighlights`
  `getPrimaryHighlights()`
  `ColorProvider`
  `getRandomColorProvider()`
  Returns the color provider used by this class to generate colors.
  `Color`
  `getSecondaryHighlight(ClangToken token)`
  `TokenHighlightColors`
  `getSecondaryHighlightColors()`
  `Set<ghidra.app.decompiler.component.ClangDecompilerHighlighter>`
  `getSecondaryHighlighters(Function function)`
  Returns all secondary highlighters for the given function.
  `long`
  `getUpdateId()`
  An value that is updated every time a new highlight is added.
  `boolean`
  `hasPrimaryHighlight(ClangToken token)`
  `boolean`
  `hasSecondaryHighlight(ClangToken token)`
  `boolean`
  `hasSecondaryHighlights(Function function)`
  `protected void`
  `notifyListeners()`
  `void`
  `removeHighlighter(DecompilerHighlighter highlighter)`
  `void`
  `removeHighlighterHighlights(DecompilerHighlighter highlighter)`
  Removes all highlights for this highlighter across all functions
  `void`
  `removeListener(ClangHighlightListener listener)`
  `void`
  `removeSecondaryHighlights(ClangToken token)`
  Removes all secondary highlights for the given token
  `void`
  `removeSecondaryHighlights(Function f)`
  Removes all secondary highlights for the given function
  `void`
  `togglePrimaryHighlights(Color hlColor, Supplier<List<ClangToken>> tokens)`
  Toggles the primary highlight state of the given set of tokens.

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

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

- ## Field Details

  - ### DEFAULT_HIGHLIGHT_COLOR

    public static Color DEFAULT_HIGHLIGHT_COLOR

  - ### defaultHighlightColor

    protected Color defaultHighlightColor

  - ### defaultParenColor

    protected Color defaultParenColor

- ## Constructor Details

  - ### ClangHighlightController

    public ClangHighlightController()

- ## Method Details

  - ### dummyIfNull

    public static ClangHighlightController dummyIfNull(ClangHighlightController c)

  - ### fieldLocationChanged

    public abstract void fieldLocationChanged(FieldLocation location, Field field, EventTrigger trigger)

  - ### getRandomColorProvider

    public ColorProvider getRandomColorProvider()
    Returns the color provider used by this class to generate colors. The initial color selection is random. Repeated calls to get a color for the same token will return the same color.
    Returns:
      the color provider

  - ### getPrimaryHighlightedText

    public String getPrimaryHighlightedText()
    Returns the token that has the primary highlight applied, if any. If multiple tokens are highlighted, then the return value is arbitrary.
    Returns:
      the highlighted text

  - ### getUpdateId

    public long getUpdateId()
    An value that is updated every time a new highlight is added. This allows clients to determine if a buffered update request is still valid.
    Returns:
      the value

  - ### hasPrimaryHighlight

    public boolean hasPrimaryHighlight(ClangToken token)

  - ### hasSecondaryHighlight

    public boolean hasSecondaryHighlight(ClangToken token)

  - ### hasSecondaryHighlights

    public boolean hasSecondaryHighlights(Function function)

  - ### getSecondaryHighlight

    public Color getSecondaryHighlight(ClangToken token)

  - ### getSecondaryHighlightColors

    public TokenHighlightColors getSecondaryHighlightColors()

  - ### getPrimaryHighlights

    public TokenHighlights getPrimaryHighlights()

  - ### getSecondaryHighlighters

    public Set<ghidra.app.decompiler.component.ClangDecompilerHighlighter> getSecondaryHighlighters(Function function)
    Returns all secondary highlighters for the given function. This allows clients to update the secondary highlight state of a given function without affecting highlights applied to other functions.
    Parameters:
      `function` - the function
    Returns:
      the highlighters

  - ### getGlobalHighlighters

    public Set<ghidra.app.decompiler.component.ClangDecompilerHighlighter> getGlobalHighlighters()
    Returns all global highlighters installed in this controller. The global highlighters apply to all functions. This is in contrast to secondary highlighters, which are function-specific.
    Returns:
      the highlighters

  - ### getHighlighterHighlights

    public TokenHighlights getHighlighterHighlights(DecompilerHighlighter highlighter)
    Gets all highlights for the given highlighter.
    Parameters:
      `highlighter` - the highlighter
    Returns:
      the highlights
    See Also:
      - `getPrimaryHighlights()`

  - ### getHighlightedToken

    public ClangToken getHighlightedToken()
    Return the current highlighted token (if exists and unique)
    Returns:
      token or null

  - ### clearPrimaryHighlights

    public void clearPrimaryHighlights()

  - ### togglePrimaryHighlights

    public void togglePrimaryHighlights(Color hlColor, Supplier<List<ClangToken>> tokens)
    Toggles the primary highlight state of the given set of tokens. If the given tokens do not all have the same highlight state (highlights on or off), then the highlights will be cleared. If all tokens are not highlighted, then they will all become highlighted.
    Parameters:
      `hlColor` - the highlight color
      `tokens` - the tokens

  - ### removeSecondaryHighlights

    public void removeSecondaryHighlights(Function f)
    Removes all secondary highlights for the given function
    Parameters:
      `f` - the function

  - ### removeSecondaryHighlights

    public void removeSecondaryHighlights(ClangToken token)
    Removes all secondary highlights for the given token
    Parameters:
      `token` - the token
    See Also:
      - `removeSecondaryHighlights(Function)`

  - ### removeHighlighter

    public void removeHighlighter(DecompilerHighlighter highlighter)

  - ### removeHighlighterHighlights

    public void removeHighlighterHighlights(DecompilerHighlighter highlighter)
    Removes all highlights for this highlighter across all functions
    Parameters:
      `highlighter` - the highlighter

  - ### addSecondaryHighlighter

    public void addSecondaryHighlighter(Function function, ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter)
    Adds the given secondary highlighter, but does not create any highlights. All secondary highlighters pertain to a given function.
    Parameters:
      `function` - the function
      `highlighter` - the highlighter

  - ### addHighlighter

    public void addHighlighter(ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter)

  - ### addHighlighterHighlights

    public void addHighlighterHighlights(ghidra.app.decompiler.component.ClangDecompilerHighlighter highlighter, Supplier<? extends Collection<ClangToken>> tokens, ColorProvider colorProvider)

  - ### addPrimaryHighlights

    public void addPrimaryHighlights(ClangNode parentNode, Set<PcodeOp> ops, Color hlColor)

  - ### addPrimaryHighlights

    public void addPrimaryHighlights(ClangNode parentNode, ColorProvider colorProvider)

  - ### addPrimaryHighlight

    protected void addPrimaryHighlight(ClangToken token, Color highlightColor)

  - ### getCombinedColor

    public Color getCombinedColor(ClangToken t)
    Returns the current highlight color for the given token, based upon all known highlights, primary, secondary and highlighters
    Parameters:
      `t` - the token
    Returns:
      the color

  - ### blend

    public Color blend(List<Color> colors)

  - ### addPrimaryHighlightToTokensForParenthesis

    protected List<ClangToken> addPrimaryHighlightToTokensForParenthesis(ClangSyntaxToken tok, Color highlightColor)
    If input token is a parenthesis, highlight all tokens between it and its match
    Parameters:
      `tok` - potential parenthesis token
      `highlightColor` - the highlight color
    Returns:
      a list of all tokens that were highlighted.

  - ### addBraceHighlight

    public void addBraceHighlight(ClangSyntaxToken token, Color highlightColor)

  - ### addListener

    public void addListener(ClangHighlightListener listener)

  - ### removeListener

    public void removeListener(ClangHighlightListener listener)

  - ### notifyListeners

    protected void notifyListeners()

  - ### dispose

    public void dispose()