Package ghidra.program.model.listing

# Interface BookmarkManager

All Known Subinterfaces:
  `TraceProgramViewBookmarkManager`

All Known Implementing Classes:
  `BookmarkDBManager`, `DBTraceProgramViewBookmarkManager`

public interface BookmarkManager
Interface for managing bookmarks.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `OLD_BOOKMARK_PROPERTY_OBJECT_CLASS1`
  1st version of bookmark property object class (schema change and class moved)
  `static final String`
  `OLD_BOOKMARK_PROPERTY_OBJECT_CLASS2`
  2nd version of bookmark property object class (class moved, property map no longer used)

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BookmarkType`
  `defineType(String type, Icon icon, Color color, int priority)`
  Define a bookmark type with its marker icon and color.
  `Bookmark`
  `getBookmark(long id)`
  Returns the bookmark that has the given id or null if no such bookmark exists.
  `Bookmark`
  `getBookmark(Address addr, String type, String category)`
  Get a specific bookmark
  `AddressSetView`
  `getBookmarkAddresses(String type)`
  Get addresses for bookmarks of a specified type.
  `int`
  `getBookmarkCount()`
  Returns the total number of bookmarks in the program
  `int`
  `getBookmarkCount(String type)`
  Return the number of bookmarks of the given type
  `Bookmark[]`
  `getBookmarks(Address addr)`
  Get all bookmarks on a specific address
  `Bookmark[]`
  `getBookmarks(Address address, String type)`
  Get bookmarks of the indicated type on a specific address
  `Iterator<Bookmark>`
  `getBookmarksIterator()`
  Returns an iterator over all bookmarks
  `Iterator<Bookmark>`
  `getBookmarksIterator(Address startAddress, boolean forward)`
  Returns an iterator over all bookmark types, starting at the given address, with traversal in the given direction.
  `Iterator<Bookmark>`
  `getBookmarksIterator(String type)`
  Get iterator over all bookmarks of the specified type.
  `BookmarkType`
  `getBookmarkType(String type)`
  Get a bookmark type
  `BookmarkType[]`
  `getBookmarkTypes()`
  Returns list of known bookmark types
  `String[]`
  `getCategories(String type)`
  Get list of categories used for a specified type
  `Program`
  `getProgram()`
  Returns the program associated with this BookmarkManager.
  `boolean`
  `hasBookmarks(String type)`
  Returns true if program contains one or more bookmarks of the given type
  `boolean`
  `isDefinedType(String type)`
  Returns true if the given bookmark type has been defined via a call to `defineType(String, Icon, Color, int)`.
  `void`
  `removeBookmark(Bookmark bookmark)`
  Remove bookmark
  `void`
  `removeBookmarks(AddressSetView set, TaskMonitor monitor)`
  Removes all bookmarks over the given address set.
  `void`
  `removeBookmarks(AddressSetView set, String type, TaskMonitor monitor)`
  Removes all bookmarks of the given type over the given address set
  `void`
  `removeBookmarks(AddressSetView set, String type, String category, TaskMonitor monitor)`
  Removes all bookmarks of the given type and category over the given address set
  `void`
  `removeBookmarks(String type)`
  Removes all bookmarks of the given type.
  `void`
  `removeBookmarks(String type, String category, TaskMonitor monitor)`
  Removes all bookmarks with the given type and category.
  `Bookmark`
  `setBookmark(Address addr, String type, String category, String comment)`
  Set a bookmark.

- ## Field Details

  - ### OLD_BOOKMARK_PROPERTY_OBJECT_CLASS1

    static final String OLD_BOOKMARK_PROPERTY_OBJECT_CLASS1
    1st version of bookmark property object class (schema change and class moved)
    See Also:
      - Constant Field Values

  - ### OLD_BOOKMARK_PROPERTY_OBJECT_CLASS2

    static final String OLD_BOOKMARK_PROPERTY_OBJECT_CLASS2
    2nd version of bookmark property object class (class moved, property map no longer used)
    See Also:
      - Constant Field Values

- ## Method Details

  - ### defineType

    BookmarkType defineType(String type, Icon icon, Color color, int priority)
    Define a bookmark type with its marker icon and color. The icon and color values are not permanently stored. Therefor, this method must be re-invoked by a plugin each time a program is opened if a custom icon and color are desired.
    Parameters:
      `type` - bookmark type
      `icon` - marker icon which may get scaled
      `color` - marker color
      `priority` - the bookmark priority
    Returns:
      bookmark type object
    Throws:
      `IllegalArgumentException` - if any of the arguments are null or if the type is empty

  - ### isDefinedType

    boolean isDefinedType(String type)
    Returns true if the given bookmark type has been defined via a call to `defineType(String, Icon, Color, int)`. This allows clients to know whether the given type should be displayed.
    Parameters:
      `type` - the type to check
    Returns:
      true if defined

  - ### getBookmarkTypes

    BookmarkType[] getBookmarkTypes()
    Returns list of known bookmark types
    Returns:
      list of known bookmark types

  - ### getBookmarkType

    BookmarkType getBookmarkType(String type)
    Get a bookmark type
    Parameters:
      `type` - bookmark type name
    Returns:
      bookmark type or null if type is unknown

  - ### getCategories

    String[] getCategories(String type)
    Get list of categories used for a specified type
    Parameters:
      `type` - bookmark type
    Returns:
      array of category strings

  - ### setBookmark

    Bookmark setBookmark(Address addr, String type, String category, String comment)
    Set a bookmark.
    Parameters:
      `addr` - the address at which to set a bookmark
      `type` - the name of the bookmark type.
      `category` - the category for the bookmark.
      `comment` - the comment to associate with the bookmark.
    Returns:
      the new bookmark

  - ### getBookmark

    Bookmark getBookmark(Address addr, String type, String category)
    Get a specific bookmark
    Parameters:
      `addr` - the address of the bookmark to retrieve
      `type` - the name of the bookmark type.
      `category` - the category of the bookmark.
    Returns:
      the bookmark with the given attributes, or null if no bookmarks match.

  - ### removeBookmark

    void removeBookmark(Bookmark bookmark)
    Remove bookmark
    Parameters:
      `bookmark` - the bookmark to remove.

  - ### removeBookmarks

    void removeBookmarks(String type)
    Removes all bookmarks of the given type.
    Parameters:
      `type` - bookmark type

  - ### removeBookmarks

    void removeBookmarks(String type, String category, TaskMonitor monitor) throws CancelledException
    Removes all bookmarks with the given type and category.
    Parameters:
      `type` - the type of the bookmarks to be removed.
      `category` - bookmark category of the types to be removed.
      `monitor` - a task monitor to report the progress.
    Throws:
      `CancelledException` - if the user (via the monitor) cancelled the operation.

  - ### removeBookmarks

    void removeBookmarks(AddressSetView set, TaskMonitor monitor) throws CancelledException
    Removes all bookmarks over the given address set.
    Parameters:
      `set` - the set of addresses from which to remove all bookmarks.
      `monitor` - a task monitor to report the progress.
    Throws:
      `CancelledException` - if the user (via the monitor) cancelled the operation.

  - ### removeBookmarks

    void removeBookmarks(AddressSetView set, String type, TaskMonitor monitor) throws CancelledException
    Removes all bookmarks of the given type over the given address set
    Parameters:
      `set` - the set of addresses from which to remove all bookmarks of the given type.
      `type` - the type of bookmarks to remove.
      `monitor` - a task monitor to report the progress.
    Throws:
      `CancelledException` - if the user (via the monitor) cancelled the operation.

  - ### removeBookmarks

    void removeBookmarks(AddressSetView set, String type, String category, TaskMonitor monitor) throws CancelledException
    Removes all bookmarks of the given type and category over the given address set
    Parameters:
      `set` - the set of addresses from which to remove all bookmarks of the given type and category.
      `type` - the type of bookmarks to remove.
      `category` - the category of bookmarks to remove.
      `monitor` - a task monitor to report the progress.
    Throws:
      `CancelledException` - if the user (via the monitor) cancelled the operation.

  - ### getBookmarks

    Bookmark[] getBookmarks(Address address, String type)
    Get bookmarks of the indicated type on a specific address
    Parameters:
      `address` - the address at which to search for bookmarks.
      `type` - bookmark type to search for
    Returns:
      array of bookmarks

  - ### getBookmarks

    Bookmark[] getBookmarks(Address addr)
    Get all bookmarks on a specific address
    Parameters:
      `addr` - the address at which to retrieve all bookmarks.
    Returns:
      array of bookmarks

  - ### getBookmarkAddresses

    AddressSetView getBookmarkAddresses(String type)
    Get addresses for bookmarks of a specified type.
    Parameters:
      `type` - bookmark type
    Returns:
      address set containing bookmarks of the specified type.

  - ### getBookmarksIterator

    Iterator<Bookmark> getBookmarksIterator(String type)
    Get iterator over all bookmarks of the specified type.
    Parameters:
      `type` - the bookmark type to search for
    Returns:
      an iterator over all bookmarks of the specified type.

  - ### getBookmarksIterator

    Iterator<Bookmark> getBookmarksIterator()
    Returns an iterator over all bookmarks
    Returns:
      an iterator over all bookmarks

  - ### getBookmarksIterator

    Iterator<Bookmark> getBookmarksIterator(Address startAddress, boolean forward)
    Returns an iterator over all bookmark types, starting at the given address, with traversal in the given direction.
    Parameters:
      `startAddress` - the address at which to start
      `forward` - true to iterate in the forward direction; false for backwards
    Returns:
      an iterator over all bookmark types, starting at the given address, with traversal in the given direction.

  - ### getBookmark

    Bookmark getBookmark(long id)
    Returns the bookmark that has the given id or null if no such bookmark exists.
    Parameters:
      `id` - the id of the bookmark to be retrieved.
    Returns:
      the bookmark

  - ### hasBookmarks

    boolean hasBookmarks(String type)
    Returns true if program contains one or more bookmarks of the given type
    Parameters:
      `type` - the type of bookmark to check for.
    Returns:
      true if program contains one or more bookmarks of the given type

  - ### getBookmarkCount

    int getBookmarkCount(String type)
    Return the number of bookmarks of the given type
    Parameters:
      `type` - the type of bookmarks to count
    Returns:
      the number of bookmarks of the given type

  - ### getBookmarkCount

    int getBookmarkCount()
    Returns the total number of bookmarks in the program
    Returns:
      the total number of bookmarks in the program

  - ### getProgram

    Program getProgram()
    Returns the program associated with this BookmarkManager.
    Returns:
      the program associated with this BookmarkManager.