Package ghidra.framework.options

Interface Options

All Known Implementing Classes:
AbstractOptions, FileOptions, SubOptions, ToolOptions
public interface Options

  • Field Details

    • DELIMITER

      static final char DELIMITER
      See Also:

    • DELIMITER_STRING

      static final String DELIMITER_STRING

    • ILLEGAL_DELIMITER

      static final String ILLEGAL_DELIMITER

  • Method Details

    • getName

      String getName()
      Get the name of this options object.
      Returns:
      String

    • getID

      String getID(String optionName)
      Returns a unique id for option in this options with the given name. This will be the full path name to the root options object.
      Parameters:
      optionName - the name of the option for which to get an ID;
      Returns:
      the unique ID for the given option.

    • getType

      OptionType getType(String optionName)
      Returns the OptionType of the given option.
      Parameters:
      optionName - the name of the option for which to get the type.
      Returns:
      the OptionType of option with the given name.

    • getPropertyEditor

      PropertyEditor getPropertyEditor(String optionName)
      Get the property editor for the option with the given name. Note: This method must be called from the swing thread.
      Parameters:
      optionName - the option name
      Returns:
      either the PropertyEditor that was registered for this option or a default editor for the property type if one can be found; otherwise null.
      Throws:
      IllegalStateException - if not called from the swing thread.

    • getRegisteredPropertyEditor

      PropertyEditor getRegisteredPropertyEditor(String optionName)
      Get the property editor that was registered for the specific option with the given name. Unlike the getPropertyEditor() method, this method does not have to be called from the swing thread
      Parameters:
      optionName - the option name
      Returns:
      the PropertyEditor that was registered for this option.

    • getChildOptions

      List<Options> getChildOptions()
      Returns a list of Options objects that are nested one level down from this Options object.
      Returns:
      a list of Options objects that are nested one level down from this Options object.

    • getLeafOptionNames

      List<String> getLeafOptionNames()
      Returns a list of option names that immediately fall under this options. For example, if this options object had the following options named ("a", "b", "c.d"), only "a" and "b" would be returned. The "c.d" leaf option name could be returned by getOptions("c").getLeafOptionNames()
      Returns:
      the list of the names of the options that are immediate children of this options object.

    • setOptionsHelpLocation

      void setOptionsHelpLocation(HelpLocation helpLocation)
      Set the location for where help can be found for this entire options object.
      Parameters:
      helpLocation - location for help on the option

    • getOptionsHelpLocation

      HelpLocation getOptionsHelpLocation()
      Returns the HelpLocation for this entire Options object.
      Returns:
      the HelpLocation for this entire Options object.

    • getHelpLocation

      HelpLocation getHelpLocation(String optionName)
      Get the location for where help can be found for the option with the given name.
      Parameters:
      optionName - name of the option
      Returns:
      null if the help location was not set on the option

    • registerOption

      void registerOption(String optionName, Object defaultValue, HelpLocation help, String description)
      Registers an option with a description, help location, and a default value without specifying the option type. This form requires that the default value not be null so that the option type can be inferred from the default value.

      Note, this method should not be used for colors and font as doing so will result in those colors and fonts becoming disconnected to the current theme. Instead use registerThemeColorBinding(String, String, HelpLocation, String) or registerThemeFontBinding(String, String, HelpLocation, String).

      Parameters:
      optionName - the name of the option being registered.
      defaultValue - the defaultValue for the option. The default value must not be null so that the OptionType can be determined. If the default value should be null, use registerOption(String, OptionType, Object, HelpLocation, String)
      help - the HelpLocation for this option.
      description - a description of the option.
      Throws:
      IllegalArgumentException - if the defaultValue is null

    • registerOption

      void registerOption(String optionName, OptionType type, Object defaultValue, HelpLocation help, String description)
      Registers an option with a description, help location, and a optional default value. With an optional default value, an OptionType must be passed as it is otherwise derived from the default value.

      Note, this method should not be used for colors and font as doing so will result in those colors and fonts becoming disconnected to the current theme. Instead use registerThemeColorBinding(String, String, HelpLocation, String) or registerThemeFontBinding(String, String, HelpLocation, String).

      Parameters:
      optionName - the name of the option being registered.
      type - the OptionType for this options.
      defaultValue - the defaultValue for the option. In this version of the method, the default value may be null.
      help - the HelpLocation for this option.
      description - a description of the option.

    • registerOption

      void registerOption(String optionName, OptionType type, Object defaultValue, HelpLocation help, String description, Supplier<PropertyEditor> editor)
      Registers an option with a description, help location, and a optional default value. With an optional default value, an OptionType must be passed as it is otherwise derived from the default value.

      Note, this method should not be used for colors and font as doing so will result in those colors and fonts becoming disconnected to the current theme. Instead use registerThemeColorBinding(String, String, HelpLocation, String) or registerThemeFontBinding(String, String, HelpLocation, String).

      Note: we use a supplier of a custom editor, instead of a custom editor, to avoid creating PropertyEditors until needed. This allows us to use the same API in both GUI mode and headless mode. If GUI property editors are created in headless mode, exceptions may be thrown. This API will not use the supplier when in headless mode, this avoiding the creation of GUI components. For this to work correctly, clients using custom property editors must defer construction of the editor until the supplier is called.

      Parameters:
      optionName - the name of the option being registered.
      type - the OptionType for this options.
      defaultValue - the defaultValue for the option. In this version of the method, the default value may be null.
      help - the HelpLocation for this option.
      description - a description of the option.
      editor - an optional supplier of a custom editor for this property. Note if the option is a custom option, then the property editor can't be null;
      Throws:
      IllegalStateException - if the options is a custom option and the editor is null.

    • registerOption

      @Deprecated(since="11.0.2", forRemoval=true) default void registerOption(String optionName, OptionType type, Object defaultValue, HelpLocation help, String description, PropertyEditor editor)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use instead registerOption(String, OptionType, Object, HelpLocation, String, Supplier)
      Use instead registerOption(String, OptionType, Object, HelpLocation, String, Supplier)
      Parameters:
      optionName - the name of the option being registered.
      type - the OptionType for this options.
      defaultValue - the defaultValue for the option. In this version of the method, the default value may be null.
      help - the HelpLocation for this option.
      description - a description of the option.
      editor - an optional supplier of a custom editor for this property. Note if the option is a custom option, then the property editor can't be null;

    • registerThemeColorBinding

      void registerThemeColorBinding(String optionName, String colorId, HelpLocation help, String description)
      Register/binds the option to a theme color id. Changing the option's color via the options Gui will result in directly changing the theme color of the given color id.
      Parameters:
      optionName - the name of the color option
      colorId - the theme color id whose color value is changed when the option's color is changed
      help - the HelpLocation for this option
      description - a description of the option

    • registerThemeFontBinding

      void registerThemeFontBinding(String optionName, String fontId, HelpLocation help, String description)
      Register/binds the option to a theme font id. Changing the option's font via the options Gui will result in directly changing the theme color of the given font id.
      Parameters:
      optionName - the name of the font option
      fontId - the theme color id whose color value is changed when the option's color is changed
      help - the HelpLocation for this option
      description - a description of the option

    • registerOptionsEditor

      void registerOptionsEditor(Supplier<OptionsEditor> editor)
      Register the options editor that will handle the editing for all the options or a sub-group of options.

      Note: we use a supplier of a custom editor, instead of a custom editor, to avoid creating PropertyEditors until needed. This allows us to use the same API in both GUI mode and headless mode. If GUI property editors are created in headless mode, exceptions may be thrown. This API will not use the supplier when in headless mode, this avoiding the creation of GUI components. For this to work correctly, clients using custom property editors must defer construction of the editor until the supplier is called.

      Parameters:
      editor - a supplier for the custom editor panel to be used to edit the options or sub-group of options.

    • registerOptionsEditor

      @Deprecated(since="11.0.2", forRemoval=true) default void registerOptionsEditor(OptionsEditor editor)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use instead registerOptionsEditor(Supplier)
      Use instead registerOptionsEditor(Supplier)
      Parameters:
      editor - the editor

    • getOptionsEditor

      OptionsEditor getOptionsEditor()
      Get the editor that will handle editing all the values in this options or sub group of options.
      Returns:
      null if no options editor was registered

    • putObject

      void putObject(String optionName, Object obj)
      Put the object value. If the option exists, the type must match the type of the existing object.
      Parameters:
      optionName - the option name
      obj - the option value
      Throws:
      IllegalStateException - if the object does not match the existing type of the option.
      IllegalArgumentException - if the object is null or not a supported type.

    • getObject

      Object getObject(String optionName, Object defaultValue)
      Get the object value; called when the options dialog is being populated.
      Parameters:
      optionName - option name
      defaultValue - default value
      Returns:
      object with the given option name; if no option was found, return default value (this value is not stored in the option maps)

    • getBoolean

      boolean getBoolean(String optionName, boolean defaultValue)
      Get the boolean value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name.
      Returns:
      boolean option value

    • getByteArray

      byte[] getByteArray(String optionName, byte[] defaultValue)
      Get the byte array for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      byte[] byte array value

    • getInt

      int getInt(String optionName, int defaultValue)
      Get the int value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      int option value

    • getDouble

      double getDouble(String optionName, double defaultValue)
      Get the double value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      double value for the option

    • getFloat

      float getFloat(String optionName, float defaultValue)
      Get the float value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      float value for the option

    • getLong

      long getLong(String optionName, long defaultValue)
      Get the long value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      long value for the option

    • getCustomOption

      CustomOption getCustomOption(String optionName, CustomOption defaultValue)
      Get the custom option value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      WrappedOption value for the option

    • getColor

      Color getColor(String optionName, Color defaultValue)
      Get the Color for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      Color option
      Throws:
      IllegalArgumentException - is a option exists with the given name but it is not a Color

    • getFile

      File getFile(String optionName, File defaultValue)
      Get the File for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      File option
      Throws:
      IllegalArgumentException - is a option exists with the given name but it is not a File options

    • getDate

      Date getDate(String pName, Date date)
      Get the Date for the given option name.
      Parameters:
      pName - the property name
      date - the default date that is stored and returned if there is no option with the given name
      Returns:
      the Date for the option
      Throws:
      IllegalArgumentException - is a option exists with the given name but it is not a Date options

    • getFont

      Font getFont(String optionName, Font defaultValue)
      Get the Font for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      Font option
      Throws:
      IllegalArgumentException - is a option exists with the given name but it is not a Font

    • getKeyStroke

      @Deprecated(since="11.1", forRemoval=true) KeyStroke getKeyStroke(String optionName, KeyStroke defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getActionTrigger(String, ActionTrigger) instead
      Get the KeyStroke for the given action name.
      Parameters:
      optionName - the option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      KeyStroke option
      Throws:
      IllegalArgumentException - is a option exists with the given name but it is not a KeyStroke

    • getActionTrigger

      ActionTrigger getActionTrigger(String optionName, ActionTrigger defaultValue)
      Get the ActionTrigger for the given full action name.
      Parameters:
      optionName - the action name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      the action trigger

    • getString

      String getString(String optionName, String defaultValue)
      Get the string value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - value that is stored and returned if there is no option with the given name
      Returns:
      String value for the option

    • getEnum

      <T extends Enum<T>> T getEnum(String optionName, T defaultValue)
      Get the Enum value for the given option name.
      Parameters:
      optionName - option name
      defaultValue - default value that is stored and returned if there is no option with the given name
      Returns:
      Enum value for the option

    • setLong

      void setLong(String optionName, long value)
      Sets the long value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setBoolean

      void setBoolean(String optionName, boolean value)
      Sets the boolean value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setInt

      void setInt(String optionName, int value)
      Sets the int value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setDouble

      void setDouble(String optionName, double value)
      Sets the double value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setFloat

      void setFloat(String optionName, float value)
      Sets the float value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setCustomOption

      void setCustomOption(String optionName, CustomOption value)
      Sets the Custom option value for the option.
      Parameters:
      optionName - name of the option
      value - the value

    • setByteArray

      void setByteArray(String optionName, byte[] value)
      Sets the byte[] value for the given option name.
      Parameters:
      optionName - the name of the option on which to save bytes.
      value - the value

    • setFile

      void setFile(String optionName, File value)
      Sets the File value for the option.
      Parameters:
      optionName - name of the option
      value - the value

    • setDate

      void setDate(String optionName, Date newSetting)
      Sets the Date value for the option.
      Parameters:
      optionName - name of the option
      newSetting - the Date to set

    • setColor

      void setColor(String optionName, Color value)
      Sets the Color value for the option
      Parameters:
      optionName - name of the option
      value - Color to set
      Throws:
      IllegalArgumentException - if a option with the given name already exists, but it is not a Color

    • setFont

      void setFont(String optionName, Font value)
      Sets the Font value for the option
      Parameters:
      optionName - name of the option
      value - Font to set
      Throws:
      IllegalArgumentException - if a option with the given name already exists, but it is not a Font

    • setKeyStroke

      @Deprecated(since="11.1", forRemoval=true) void setKeyStroke(String optionName, KeyStroke value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setActionTrigger(String, ActionTrigger) instead
      Sets the KeyStroke value for the option
      Parameters:
      optionName - name of the option
      value - KeyStroke to set
      Throws:
      IllegalArgumentException - if a option with the given name already exists, but it is not a KeyStroke

    • setActionTrigger

      void setActionTrigger(String optionName, ActionTrigger value)
      Sets the action trigger value for the option
      Parameters:
      optionName - name of the option
      value - action trigger to set
      Throws:
      IllegalArgumentException - if a option with the given name already exists, but it is not an action trigger

    • setString

      void setString(String optionName, String value)
      Set the String value for the option.
      Parameters:
      optionName - name of the option
      value - value of the option

    • setEnum

      <T extends Enum<T>> void setEnum(String optionName, T value)
      Set the Enum value for the option.
      Parameters:
      optionName - name of the option
      value - Enum value of the option

    • removeOption

      void removeOption(String optionName)
      Remove the option name.
      Parameters:
      optionName - name of option to remove

    • getOptionNames

      List<String> getOptionNames()
      Get the list of option names. This method will return the names (paths) of all options contained in this options object or below. For example, if the options has ("aaa", "bbb", "ccc.ddd"), all three will be returned. the getLeafOptionNames() method will return only the "aaa" and "bbb" names.
      Returns:
      the list of all option names(paths) under this options.

    • contains

      boolean contains(String optionName)
      Return true if a option exists with the given name.
      Parameters:
      optionName - option name
      Returns:
      true if there exists an option with the given name

    • getDescription

      String getDescription(String optionName)
      Get the description for the given option name.
      Parameters:
      optionName - name of the option
      Returns:
      null if the description or option name does not exist

    • isRegistered

      boolean isRegistered(String optionName)
      Returns true if the specified option has been registered. Only registered names are saved.
      Parameters:
      optionName - the option name
      Returns:
      true if registered

    • isDefaultValue

      boolean isDefaultValue(String optionName)
      Returns true if the option with the given name's current value is the default value.
      Parameters:
      optionName - the name of the option.
      Returns:
      true if the options has its current value equal to its default value.

    • restoreDefaultValues

      void restoreDefaultValues()
      Restores all options contained herein to their default values.
      See Also:

    • restoreDefaultValue

      void restoreDefaultValue(String optionName)
      Restores the option denoted by the given name to its default value.
      Parameters:
      optionName - The name of the option to restore
      See Also:

    • getOptions

      Options getOptions(String path)
      Returns a Options object that is a sub-options of this options.

      Note: the option path can have DELIMITER characters which will be used to create a hierarchy with each element in the path resulting in sub-option of the previous path element.

      Parameters:
      path - the path for the sub-options object
      Returns:
      an Options object that is a sub-options of this options

    • createAlias

      void createAlias(String aliasName, Options options, String optionsName)
      Create an alias in this options for an existing option in some other options object.
      Parameters:
      aliasName - the name within this options object that will actually refer to some other options object.
      options - the options object that has the actual option.
      optionsName - the name within the given options object of the actual option.

    • isAlias

      boolean isAlias(String aliasName)
      Returns
      Parameters:
      aliasName - the name of the alias.
      Returns:
      a Options object that is a sub-options of this options.

    • getDefaultValue

      Object getDefaultValue(String optionName)
      Returns the default value for the given option.
      Parameters:
      optionName - the name of the option for which to retrieve the default value.
      Returns:
      the default value for the given option.

    • getValueAsString

      String getValueAsString(String name)
      Returns the value as a string for the given option.
      Parameters:
      name - the name of the option for which to retrieve the value as a string
      Returns:
      the value as a string for the given option.

    • getDefaultValueAsString

      String getDefaultValueAsString(String optionName)
      Returns the default value as a string for the given option.
      Parameters:
      optionName - the name of the option for which to retrieve the default value as a string
      Returns:
      the default value as a string for the given option.

    • hasSameOptionsAndValues

      static boolean hasSameOptionsAndValues(Options options1, Options options2)
      Returns true if the two options objects have the same set of options and values
      Parameters:
      options1 - the first options object to test
      options2 - the second options object to test
      Returns:
      true if the two options objects have the same set of options and values