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