Package ghidra.app.services

# Interface MarkerService

public interface MarkerService

Service to manage navigation markers displayed around a scrollable window like the Listing. The navigation bar displays the general location of markers for the entire view. The marker bar displays a marker at each marked address visible within the view.

The interface defines priorities for display of markers in Marker Margin and colored bars in Navigation Margin. The higher the priority, the more likely the marker/bar will be displayed on the top. Areas will always be lower than marker priorities.

Recommended Usage
The service used to work independently of `Program`s. In order to work effectively this service has been changed to associate created markers with individual programs. Thus, it is up to the clients of this class perform lifecycle management of markers created by this service. For example, a client that creates a marker from `createAreaMarker(String, String, Program, int, boolean, boolean, boolean, Color)` should call `removeMarker(MarkerSet, Program)` when the markers are no longer used, such as when a program has become deactivated. In this example usage markers are added and removed as the user tabs through open programs.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BOOKMARK_PRIORITY`
  Display priority for bookmark locations.
  `static final int`
  `BREAKPOINT_PRIORITY`
  Display priority for marking locations of breakpoints.
  `static final int`
  `CHANGE_PRIORITY`
  Display priority for marking a change set.
  `static final int`
  `CURSOR_PRIORITY`
  Display priority for marking the cursor location.
  `static final int`
  `DIFF_PRIORITY`
  Display priority for marking locations where a program diff difference exists.
  `static final int`
  `FUNCTION_COMPARE_CURSOR_PRIORITY`
  Display priority for marking the cursor location.
  `static final int`
  `GROUP_PRIORITY`
  Display priority for marking a change set for members in a group.
  `static final String`
  `HIGHLIGHT_GROUP`
  A group name for highlights.
  `static final int`
  `HIGHLIGHT_PRIORITY`
  Display priority for marking the highlight.
  `static final int`
  `PROPERTY_PRIORITY`
  Display priority for marking locations where a property exists.
  `static final int`
  `REFERENCE_PRIORITY`
  Display priority for marking references.
  `static final int`
  `SEARCH_PRIORITY`
  Display priority for marking locations of search hits.
  `static final int`
  `SELECTION_PRIORITY`
  Display priority for marking the selection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addChangeListener(ChangeListener listener)`
  Adds a change listener to be notified when markers are added/removed or the addresses in any current markerSets are changed
  `MarkerSet`
  `createAreaMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color)`
  Create a Marker display which shows area type markers.
  `MarkerSet`
  `createAreaMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, boolean isPreferred)`
  Create a Marker display which shows area type markers.
  `ghidra.app.plugin.core.marker.MarkerMarginProvider`
  `createMarginProvider()`
  Create a new marker margin provider.
  `ghidra.app.plugin.core.marker.MarkerOverviewProvider`
  `createOverviewProvider()`
  Create a new marker overview provider.
  `MarkerSet`
  `createPointMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, Icon icon)`
  Create a Marker display which shows point type markers.
  `MarkerSet`
  `createPointMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, Icon icon, boolean isPreferred)`
  Create a Marker display which shows point type markers.
  `Color`
  `getBackgroundColor(Program program, Address address)`
  Returns the background color associated with the given program and address.
  `MarkerSet`
  `getMarkerSet(String name, Program program)`
  Return the marker set with the given name;
  `boolean`
  `isActiveMarkerForGroup(String groupName, MarkerSet markerSet, Program program)`
  Returns true if the given marker set is the current marker set for the given group.
  `void`
  `removeChangeListener(ChangeListener listener)`
  Removes the given change listener from the list of listeners to be notified of changes
  `void`
  `removeMarker(MarkerSet markerSet, Program program)`
  Remove the marker set
  `void`
  `removeMarkerForGroup(String groupName, MarkerSet markerSet, Program program)`
  Removes a marker set for a given group name.
  `void`
  `setMarkerClickedListener(MarkerClickedListener listener)`
  Sets the listener to be notified when the user double-clicks in the Marker Margin area.
  `void`
  `setMarkerForGroup(String groupName, MarkerSet markerSet, Program program)`
  Sets a marker set for a given group name.

- ## Field Details

  - ### SELECTION_PRIORITY

    static final int SELECTION_PRIORITY
    Display priority for marking the selection.
    See Also:
      - Constant Field Values

  - ### HIGHLIGHT_PRIORITY

    static final int HIGHLIGHT_PRIORITY
    Display priority for marking the highlight.
    See Also:
      - Constant Field Values

  - ### CHANGE_PRIORITY

    static final int CHANGE_PRIORITY
    Display priority for marking a change set.
    See Also:
      - Constant Field Values

  - ### GROUP_PRIORITY

    static final int GROUP_PRIORITY
    Display priority for marking a change set for members in a group.
    See Also:
      - Constant Field Values

  - ### CURSOR_PRIORITY

    static final int CURSOR_PRIORITY
    Display priority for marking the cursor location.
    See Also:
      - Constant Field Values

  - ### FUNCTION_COMPARE_CURSOR_PRIORITY

    static final int FUNCTION_COMPARE_CURSOR_PRIORITY
    Display priority for marking the cursor location.
    See Also:
      - Constant Field Values

  - ### SEARCH_PRIORITY

    static final int SEARCH_PRIORITY
    Display priority for marking locations of search hits.
    See Also:
      - Constant Field Values

  - ### BREAKPOINT_PRIORITY

    static final int BREAKPOINT_PRIORITY
    Display priority for marking locations of breakpoints.
    See Also:
      - Constant Field Values

  - ### BOOKMARK_PRIORITY

    static final int BOOKMARK_PRIORITY
    Display priority for bookmark locations.
    See Also:
      - Constant Field Values

  - ### PROPERTY_PRIORITY

    static final int PROPERTY_PRIORITY
    Display priority for marking locations where a property exists.
    See Also:
      - Constant Field Values

  - ### DIFF_PRIORITY

    static final int DIFF_PRIORITY
    Display priority for marking locations where a program diff difference exists.
    See Also:
      - Constant Field Values

  - ### REFERENCE_PRIORITY

    static final int REFERENCE_PRIORITY
    Display priority for marking references.
    See Also:
      - Constant Field Values

  - ### HIGHLIGHT_GROUP

    static final String HIGHLIGHT_GROUP
    A group name for highlights. This is intended to be used with `setMarkerForGroup(String, MarkerSet, Program)` and `removeMarkerForGroup(String, MarkerSet, Program)`
    See Also:
      - Constant Field Values

- ## Method Details

  - ### createAreaMarker

    MarkerSet createAreaMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color)
    Create a Marker display which shows area type markers.
    Parameters:
      `name` - name of the navigation markers
      `markerDescription` - description of the navigation markers
      `program` - The program with which the created markers will be associated.
      `priority` - to sort out what displays on top, higher is more likely to be on top
      `showMarkers` - true indicates to show area markers (on the left side of the browser.)
      `showNavigation` - true indicates to show area navigation markers (on the right side of the browser.)
      `colorBackground` - if true, then the browser's background color will reflect the marker.
      `color` - the color of marked areas.
    Returns:
      set of navigation markers

  - ### createAreaMarker

    MarkerSet createAreaMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, boolean isPreferred)
    Create a Marker display which shows area type markers.
    Parameters:
      `name` - name of the navigation markers
      `markerDescription` - description of the navigation markers
      `program` - The program with which the created markers will be associated.
      `priority` - to sort out what displays on top, higher is more likely to be on top
      `showMarkers` - true indicates to show area markers (on the left side of the browser.)
      `showNavigation` - true indicates to show area navigation markers (on the right side of the browser.)
      `colorBackground` - if true, then the browser's background color will reflect the marker.
      `color` - the color of marked areas.
      `isPreferred` - true indicates higher priority than all non-preferred MarkerSets
    Returns:
      set of navigation markers

  - ### createPointMarker

    MarkerSet createPointMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, Icon icon)
    Create a Marker display which shows point type markers.
    Parameters:
      `name` - name of the navigation markers
      `markerDescription` - description of the navigation markers
      `program` - The program with which the created markers will be associated.
      `priority` - to sort out what displays on top, higher is more likely to be on top
      `showMarkers` - true indicates to show area markers (on the left side of the browser.)
      `showNavigation` - true indicates to show area navigation markers (on the right side of the browser.)
      `colorBackground` - if true, then the browser's background color will reflect the marker.
      `color` - the color of marked areas in navigation bar
      `icon` - icon to display in marker bar
    Returns:
      set of navigation markers

  - ### createPointMarker

    MarkerSet createPointMarker(String name, String markerDescription, Program program, int priority, boolean showMarkers, boolean showNavigation, boolean colorBackground, Color color, Icon icon, boolean isPreferred)
    Create a Marker display which shows point type markers.
    Parameters:
      `name` - name of the navigation markers
      `markerDescription` - description of the navigation markers
      `program` - The program with which the created markers will be associated.
      `priority` - to sort out what displays on top, higher is more likely to be on top
      `showMarkers` - true indicates to show area markers (on the left side of the browser.)
      `showNavigation` - true indicates to show area navigation markers (on the right side of the browser.)
      `colorBackground` - if true, then the browser's background color will reflect the marker.
      `color` - the color of marked areas in navigation bar
      `icon` - icon to display in marker bar
      `isPreferred` - is prioritized over non-preferred MarkersSets
    Returns:
      set of navigation markers

  - ### removeMarker

    void removeMarker(MarkerSet markerSet, Program program)
    Remove the marker set
    Parameters:
      `markerSet` - marker set to be removed from navigation bars.
      `program` - The program with which the markers are associated.

  - ### getMarkerSet

    MarkerSet getMarkerSet(String name, Program program)
    Return the marker set with the given name;
    Parameters:
      `name` - The name of the marker set for which to search
      `program` - The program with which the created markers will be associated.
    Returns:
      the markerset with the given name;

  - ### setMarkerForGroup

    void setMarkerForGroup(String groupName, MarkerSet markerSet, Program program)
    Sets a marker set for a given group name. Any previous marker set associated with the given group name will be removed from this marker service. This method is used to ensure that only one marker set is used at any time for a give group.
    Parameters:
      `groupName` - The name to associate the marker set with.
      `markerSet` - The marker set to add to this service
      `program` - The program with which the markers are associated.
    See Also:
      - `removeMarkerForGroup(String, MarkerSet, Program)`

  - ### isActiveMarkerForGroup

    boolean isActiveMarkerForGroup(String groupName, MarkerSet markerSet, Program program)
    Returns true if the given marker set is the current marker set for the given group.
    Parameters:
      `groupName` - The group name to check
      `markerSet` - The marker set to check
      `program` - The program with which the markers are associated.
    Returns:
      true if the given marker set is the current marker set for the given group
    See Also:
      - `setMarkerForGroup(String, MarkerSet, Program)`
      - `removeMarkerForGroup(String, MarkerSet, Program)`

  - ### removeMarkerForGroup

    void removeMarkerForGroup(String groupName, MarkerSet markerSet, Program program)
    Removes a marker set for a given group name. If the given marker set is not the marker set associated with the given group name, then no action will be taken.
    Parameters:
      `groupName` - The name associated the marker set with.
      `markerSet` - The marker set to add to this service
      `program` - The program with which the markers are associated
    See Also:
      - `setMarkerForGroup(String, MarkerSet, Program)`
      - `isActiveMarkerForGroup(String, MarkerSet, Program)`

  - ### getBackgroundColor

    Color getBackgroundColor(Program program, Address address)
    Returns the background color associated with the given program and address. Each markerSet that supports background coloring is blended to determine a background color for the given address.
    Parameters:
      `program` - the program to check for a background color.
      `address` - the address to check for a background color.
    Returns:
      the background color to use for that address or null if no markers contain that address.

  - ### addChangeListener

    void addChangeListener(ChangeListener listener)
    Adds a change listener to be notified when markers are added/removed or the addresses in any current markerSets are changed
    Parameters:
      `listener` - the listener

  - ### removeChangeListener

    void removeChangeListener(ChangeListener listener)
    Removes the given change listener from the list of listeners to be notified of changes
    Parameters:
      `listener` - the listener

  - ### setMarkerClickedListener

    void setMarkerClickedListener(MarkerClickedListener listener)
    Sets the listener to be notified when the user double-clicks in the Marker Margin area. Note that only one listener is allowed to be set at a time. If an attempt to set a second listener occurs, then an IllegalStateException is thrown.
    Parameters:
      `listener` - the listener to be notified or null to remove the current listener
    Throws:
      `IllegalStateException` - if a listener is already set.

  - ### createMarginProvider

    ghidra.app.plugin.core.marker.MarkerMarginProvider createMarginProvider()
    Create a new marker margin provider. The newly created provider is not added to the UI; clients must install the newly created provider themselves. Note that you must keep a strong reference to the provider, or it may not receive updates from the service.
    Returns:
      the new provider

  - ### createOverviewProvider

    ghidra.app.plugin.core.marker.MarkerOverviewProvider createOverviewProvider()
    Create a new marker overview provider. The newly created provider is not added to the UI; clients must install the newly created provider themselves. Note that you must keep a strong reference to the provider, or it may not receive updates from the service.
    Returns:
      the new provider