Package ghidra.features.base.values

# Class ProgramFileValue

java.lang.Object
docking.widgets.values.AbstractValue<DomainFile>
ghidra.features.base.values.ProjectFileValue
ghidra.features.base.values.ProgramFileValue

public class ProgramFileValue extends ProjectFileValue
Value class for `Program` files. The editor component consists of the `JTextField` and a browse button for bringing up a `DataTreeDialog` for picking programs from the current project. This class also provides a convenience method for opening a program.

This class and other subclasses of `AbstractValue` are part of a subsystem for easily defining a set of values that can be displayed in an input dialog (`ValuesMapDialog`). Typically, these values are created indirectly using a `GValuesMap` which is then given to the constructor of the dialog. However, an alternate approach is to create the dialog without a ValuesMap and then use its `ValuesMapDialog.addValue(AbstractValue)` method directly.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProgramFileValue(String name)`
  Constructor for creating a new ProgramFileValue with the given name.
  `ProgramFileValue(String name, Project project, String startingPath)`
  Constructor for ProgramValue when wanting to pick from a different project than the active project, such as a read-only project.
  `ProgramFileValue(String name, String startingPath)`
  Constructor for creating a new ProgramFileValue with the given name and a starting folder when using the project file chooser.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Program`
  `openProgram(Object consumer, Tool tool, boolean upgradeIfNeeded, TaskMonitor monitor)`
  Convenience method for opening the program for the current program file value.

  ### Methods inherited from class ghidra.features.base.values.ProjectFileValue

  `fromString, getComponent, toString, updateComponentFromValue, updateValueFromComponent`

  ### Methods inherited from class docking.widgets.values.AbstractValue

  `copyValue, getAsText, getName, getValue, hasValue, reset, setAsText, setValue`

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

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

- ## Constructor Details

  - ### ProgramFileValue

    public ProgramFileValue(String name)
    Constructor for creating a new ProgramFileValue with the given name.
    Parameters:
      `name` - the name of the value

  - ### ProgramFileValue

    public ProgramFileValue(String name, String startingPath)
    Constructor for creating a new ProgramFileValue with the given name and a starting folder when using the project file chooser.
    Parameters:
      `name` - the name of the value
      `startingPath` - the path to a starting folder

  - ### ProgramFileValue

    public ProgramFileValue(String name, Project project, String startingPath)
    Constructor for ProgramValue when wanting to pick from a different project than the active project, such as a read-only project.
    Parameters:
      `name` - the name of the value
      `project` - The project from which to pick a project.
      `startingPath` - the path to a starting folder (Can also be a path to program)

- ## Method Details

  - ### openProgram

    public Program openProgram(Object consumer, Tool tool, boolean upgradeIfNeeded, TaskMonitor monitor) throws VersionException, IOException, CancelledException
    Convenience method for opening the program for the current program file value. If the program is already open, then the consumer will be added to the program. The caller of this method is responsible for calling `DomainObject.release(Object)` with the same consumer when it is done using this program. Program are only closed after all consumers are released. If multiple calls are made to this method, then the consumer will be added multiple times and must be released multiple times.

    The consumer can be any object, but since the consumer's purpose is to keep the program open while some object is using it, the object itself is typically passed in as the consumer. For example, when used in a script, passing in the java keyword "this" as the consumer will make the script itself the consumer.

    Parameters:
      `consumer` - the consumer to be used to open the program
      `tool` - optional tool that if non-null, the program will also be opened in the tool
      `upgradeIfNeeded` - if true, program will be upgraded if needed and possible. If false, the program will only be upgraded after first prompting the user. In headless mode, it will attempt to upgrade only if the parameter is true.
      `monitor` - task monitor for cancelling the open program.
    Returns:
      a program for the currently selected program file. If no file chosen, returns null
    Throws:
      `VersionException` - if the Program is out-of-date from the version of GHIDRA and an upgrade was not been performed. In non-headless mode, the user will have already been notified via a popup dialog. current Ghidra Program version.
      `IOException` - if there is an error accessing the Program's DomainObject
      `CancelledException` - if the operation is cancelled