Package ghidra.debug.api.action

# Interface LocationTrackingSpec

public interface LocationTrackingSpec
A specification for automatic navigation of the dynamic listing

TODO: Some of these should be configurable and permit multiple instances so that common configurations can be saved. The most obvious use case would be a Sleigh expression. A user may want 3 different common expressions readily available in the drop-down list. It might make sense to generate a tracking specification from each Watch.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `LocationTrackingSpec.TrackingSpecConfigFieldCodec`
  Codec for saving/restoring the tracking specification

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `changeIsCurrent(AddressSpace space, TraceAddressSnapRange range, DebuggerCoordinates current)`
  Check if the given trace-space and range refer to memory or the current frame
  `String`
  `computeTitle(DebuggerCoordinates coordinates)`
  Compute a title prefix to indicate this tracking specification
  `String`
  `getConfigName()`
  Get the configuration name
  `String`
  `getLocationLabel()`
  Get the name used in the location tracking label
  `Icon`
  `getMenuIcon()`
  Get the icon for this specification
  `String`
  `getMenuName()`
  A human-readable name for this specification
  `LocationTracker`
  `getTracker()`
  Get (or create) the actual location tracking logic

- ## Method Details

  - ### changeIsCurrent

    static boolean changeIsCurrent(AddressSpace space, TraceAddressSnapRange range, DebuggerCoordinates current)
    Check if the given trace-space and range refer to memory or the current frame

    If the space models memory, the thread and frame are not considered, in case, e.g., the tracked register is memory-mapped. If the space models registers, the thread and frame are considered and must match those given in the coordinates. Whatever the case, the span must include the snap of the coordinates. Otherwise, the change is not considered current.

    Parameters:
      `space` - the trace-space, giving thread, frame, and address space
      `range` - the address range and time span of the change
      `current` - the current coordinates
    Returns:
      true if the change affects the tracked address for the given coordinates

  - ### getConfigName

    String getConfigName()
    Get the configuration name

    This is the value stored in configuration files to identify this specification

    Returns:
      the configuration name

  - ### getMenuName

    String getMenuName()
    A human-readable name for this specification

    This is the text displayed in menus

    Returns:
      the menu name

  - ### getMenuIcon

    Icon getMenuIcon()
    Get the icon for this specification
    Returns:
      the icon

  - ### computeTitle

    String computeTitle(DebuggerCoordinates coordinates)
    Compute a title prefix to indicate this tracking specification
    Parameters:
      `coordinates` - the current coordinates
    Returns:
      a prefix, or `null` to use a default

  - ### getLocationLabel

    String getLocationLabel()
    Get the name used in the location tracking label
    Returns:
      the label

  - ### getTracker

    LocationTracker getTracker()
    Get (or create) the actual location tracking logic

    Having a separate object from the spec gives implementations the option of keeping state on a per-window basis.

    Returns:
      the tracker