Package ghidra.framework.plugintool

Class PluginTool

java.lang.Object
docking.AbstractDockingTool
ghidra.framework.plugintool.PluginTool
All Implemented Interfaces:
Tool, ServiceProvider
Direct Known Subclasses:
FrontEndTool, GhidraTool, ModalPluginTool, StandAlonePluginTool
public abstract class PluginTool extends AbstractDockingTool
Base class that is a container to manage plugins and their actions, and to coordinate the firing of plugin events and tool events. A PluginTool may have visible components supplied by 
ComponentProviders
. These components may be docked within the tool, or moved out into their own windows.

Plugins normally add actions via AbstractDockingTool.addAction(DockingActionIf). There is also an alternate method for getting actions to appear in the popup context menu (see AbstractDockingTool.addPopupActionProvider(PopupActionProvider)). The popup listener mechanism is generally not needed and should only be used in special circumstances (see PopupActionProvider).

The PluginTool also manages tasks that run in the background, and options used by the plugins.

  • Field Details

    • TOOL_NAME_PROPERTY

      public static final String TOOL_NAME_PROPERTY
      Name of the property for the tool name.
      See Also:

    • ICON_PROPERTY_NAME

      public static final String ICON_PROPERTY_NAME
      Name of the property for the tool icon.
      See Also:

    • DESCRIPTION_PROPERTY_NAME

      public static final String DESCRIPTION_PROPERTY_NAME
      Name of the property for the description of the tool.
      See Also:

    • PLUGIN_COUNT_PROPERTY_NAME

      public static final String PLUGIN_COUNT_PROPERTY_NAME
      Name of the property for the number of plugins the tool has.
      See Also:

    • toolName

      protected String toolName

    • manageDialog

      protected ManagePluginsDialog manageDialog

    • iconURL

      protected ToolIconURL iconURL

    • isDisposed

      protected boolean isDisposed

  • Constructor Details

    • PluginTool

      public PluginTool(Project project, ToolTemplate template)
      Construct a new PluginTool.
      Parameters:
      project - project that contains this tool
      template - the template from which to load this tool

    • PluginTool

      public PluginTool(Project project, String name, boolean isDockable, boolean hasStatus, boolean isModal)
      Construct a new PluginTool.
      Parameters:
      project - project that contains the tool
      name - the name of the tool
      isDockable - true if the tool contains components that can be docked
      hasStatus - true if the tool should display a status component
      isModal - true if the tool is modal, meaning that while this tool is visible, no other tool or dialog in Ghidra can have focus

    • PluginTool

      public PluginTool(Project project, ProjectManager projectManager, ToolServices toolServices, String name, boolean isDockable, boolean hasStatus, boolean isModal)

    • PluginTool

      protected PluginTool()

  • Method Details

    • createPluginsConfigurations

      protected PluginsConfiguration createPluginsConfigurations()

    • getPluginsConfiguration

      public PluginsConfiguration getPluginsConfiguration()

    • createDockingWindowManager

      protected DockingWindowManager createDockingWindowManager(boolean isDockable, boolean hasStatus, boolean isModal)
      This method exists here, as opposed to inline in the constructor, so that subclasses can alter the behavior of the DockingWindowManager construction.
      Parameters:
      isDockable - true if the tool contains components that can be docked
      hasStatus - true if the tool should display a status component
      isModal - true if the tool is modal, meaning that while this tool is visible, no other tool or dialog in Ghidra can have focus
      Returns:
      a new DockingWindowManager

    • installHomeButton

      protected void installHomeButton()

    • installUtilityPlugins

      protected void installUtilityPlugins()
      Loads all application-level utility classes into this tool. This should only be called by tools that represent the global application tool and not for sub-tools.

    • initActions

      protected void initActions()
      Placeholder for subclasses to get a chance to install actions before plugins.

    • optionsChanged

      protected void optionsChanged(Options options, String name, Object oldValue, Object newValue)

    • setWindowsOnTop

      public void setWindowsOnTop(boolean b)
      Set the Tool option (GhidraOptions.OPTION_DOCKING_WINDOWS_ON_TOP) for whether a docked window will always be shown on top of its parent window.
      Parameters:
      b - true means that the docked window will always appear on top of its parent window; false means to allow the docked window to be "hidden" under its parent dialog

    • isWindowsOnTop

      public boolean isWindowsOnTop()
      Return the value of the Tool option (GhidraOptions.OPTION_DOCKING_WINDOWS_ON_TOP) for whether docked windows will always be shown on top of their parent windows.
      Returns:
      value of the Tool option, GhidraOptions.OPTION_DOCKING_WINDOWS_ON_TOP

    • getManagePluginsDialog

      public ManagePluginsDialog getManagePluginsDialog()
      Returns the manage plugins dialog that is currently being used.
      Returns:
      the current manage plugins dialog

    • showConfig

      public void showConfig(boolean addSaveActions, boolean isNewTool)
      Displays the manage plugins dialog.
      Parameters:
      addSaveActions - if true show save actions
      isNewTool - true if creating a new tool

    • showExtensions

      public void showExtensions()
      Displays the extensions installation dialog.

    • showComponentHeader

      public void showComponentHeader(ComponentProvider provider, boolean b)
      Set whether a component's header should be shown; the header is the component that is dragged in order to move the component within the tool, or out of the tool into a separate window
      Parameters:
      provider - provider of the visible component in the tool
      b - true means to show the header

    • isService

      public boolean isService(Class<?> serviceInterface)
      Returns true if the specified serviceInterface is a valid service that exists in this tool.
      Parameters:
      serviceInterface - the service interface
      Returns:
      true if the specified serviceInterface

    • getService

      public <T> T getService(Class<T> c)
      Description copied from interface: ServiceProvider
      Returns the Service object that implements the given service interface.
      Parameters:
      c - the interface class.

    • getServices

      public <T> T[] getServices(Class<T> c)
      Get the objects that implement the given service.
      Parameters:
      c - service class
      Returns:
      array of Objects that implement the service, c.

    • addServiceListener

      public void addServiceListener(ServiceListener listener)
      Description copied from interface: ServiceProvider
      Adds a listener that will be called as services are added and removed from this ServiceProvider.
      Parameters:
      listener - The listener to add.

    • removeServiceListener

      public void removeServiceListener(ServiceListener listener)
      Description copied from interface: ServiceProvider
      Removes the given listener from this ServiceProvider. This method does nothing if the given listener is not contained by this ServiceProvider.
      Parameters:
      listener -

    • beep

      public void beep()
      A convenience method to make an attention-grabbing noise to the user

    • setDefaultComponent

      public void setDefaultComponent(ComponentProvider provider)
      Sets the provider that should get the default focus when no component has focus.
      Parameters:
      provider - the provider that should get the default focus when no component has focus.

    • registerDefaultContextProvider

      public void registerDefaultContextProvider(Class<? extends ActionContext> type, ActionContextProvider provider)
      Registers an action context provider as the default provider for a specific action context type. Note that this registers a default provider for exactly that type and not a subclass of that type. If the provider want to support a hierarchy of types, then it must register separately for each type. See ActionContext for details on how the action context system works.
      Parameters:
      type - the ActionContext class to register a default provider for
      provider - the ActionContextProvider that provides default tool context for actions that consume the given ActionContext type

    • unregisterDefaultContextProvider

      public void unregisterDefaultContextProvider(Class<? extends ActionContext> type, ActionContextProvider provider)
      Removes the default provider for the given ActionContext type.
      Parameters:
      type - the subclass of ActionContext to remove a provider for
      provider - the ActionContextProvider to remove for the given ActionContext type

    • getToolTemplate

      public ToolTemplate getToolTemplate(boolean includeConfigState)

    • saveToolToToolTemplate

      public ToolTemplate saveToolToToolTemplate()

    • saveWindowingDataToXml

      public org.jdom.Element saveWindowingDataToXml()

    • restoreWindowingDataFromXml

      public void restoreWindowingDataFromXml(org.jdom.Element element)

    • acceptDomainFiles

      public boolean acceptDomainFiles(DomainFile[] data)

    • accept

      public boolean accept(URL url)
      Request tool to accept specified URL. Acceptance of URL depends greatly on the plugins configured into tool. If no plugin accepts URL it will be rejected and false returned. If a plugin can accept the specified URL it will attempt to process and return true if successful. The user may be prompted if connecting to the URL requires user authentication.
      Parameters:
      url - read-only resource URL
      Returns:
      true if URL accepted and processed else false

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener l)

    • addToolListener

      public void addToolListener(ToolListener listener)

    • hasToolListeners

      public boolean hasToolListeners()
      Returns true if there is at least one tool listening to this tool's plugin events
      Returns:
      true if there is at least one tool listening to this tool's plugin events

    • dispose

      protected void dispose()

    • firePluginEvent

      public void firePluginEvent(PluginEvent event)

    • getConsumedToolEventNames

      public String[] getConsumedToolEventNames()

    • getDomainFiles

      public DomainFile[] getDomainFiles()

    • getIcon

      public ImageIcon getIcon()
      Description copied from interface: Tool
      Get the icon that the tool is using
      Returns:
      the icon that the tool is using

    • getIconURL

      public ToolIconURL getIconURL()

    • getInstanceName

      public String getInstanceName()

    • getName

      public String getName()
      Description copied from interface: Tool
      Returns a combination of the tool name and the instance name of the form tool name(instance name), e.g., SomeTool(2)
      Returns:
      the tool name

    • getSupportedDataTypes

      public Class<?>[] getSupportedDataTypes()

    • getToolEventNames

      public String[] getToolEventNames()

    • getToolName

      public String getToolName()

    • putInstanceName

      public void putInstanceName(String newInstanceName)

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener l)

    • removeToolListener

      public void removeToolListener(ToolListener listener)

    • restoreDataStateFromXml

      public void restoreDataStateFromXml(org.jdom.Element root)

    • saveDataStateToXml

      public org.jdom.Element saveDataStateToXml(boolean savingProject)

    • restoreFromXml

      protected boolean restoreFromXml(org.jdom.Element root)

    • saveToXml

      public org.jdom.Element saveToXml(boolean includeConfigState)

    • setConfigChanged

      public void setConfigChanged(boolean changed)
      Description copied from interface: Tool
      Toggles the "change" state of the tool...
      Specified by:
      setConfigChanged in interface Tool
      Overrides:
      setConfigChanged in class AbstractDockingTool
      Parameters:
      changed - true indicates that the tool config has changed.

    • setIconURL

      public void setIconURL(ToolIconURL newIconURL)

    • setToolName

      public void setToolName(String name)

    • processToolEvent

      public void processToolEvent(PluginEvent toolEvent)

    • execute

      public <T extends DomainObject> boolean execute(String commandName, T domainObject, Function<T,Boolean> f)
      Execute the given command in the foreground. Required domain object transaction will be started with delayed end to ensure that any follow-on analysis starts prior to transaction end.
      Type Parameters:
      T - DomainObject implementation interface
      Parameters:
      commandName - command name to be associated with transaction
      domainObject - domain object to be modified
      f - command function callback which should return true on success or false on failure.
      Returns:
      result from command function callback

    • execute

      public <T extends DomainObject> void execute(String commandName, T domainObject, Runnable r)
      Execute the given command in the foreground. Required domain object transaction will be started with delayed end to ensure that any follow-on analysis starts prior to transaction end.
      Type Parameters:
      T - DomainObject implementation interface
      Parameters:
      commandName - command name to be associated with transaction
      domainObject - domain object to be modified
      r - command function runnable

    • execute

      public <T extends DomainObject> boolean execute(Command<T> command, T obj)
      Call the applyTo() method on the given command to make some change to the domain object; the command is done in the AWT thread, therefore, the command that is to be executed should be a relatively quick operation so that the event queue does not appear to "hang." For lengthy operations, the command should be done in a background task.
      Parameters:
      command - command to apply
      obj - domain object that the command will be applied to
      Returns:
      status of the command's applyTo() method
      See Also:

    • isExecutingCommand

      public boolean isExecutingCommand()
      Return whether there is a command being executed
      Returns:
      true if there is a command being executed

    • threadIsBackgroundTaskThread

      public boolean threadIsBackgroundTaskThread()
      Returns:
      true if the current thread group or its ancestors is a member of this tools background task thread group, else false

    • executeBackgroundCommand

      public <T extends DomainObject> void executeBackgroundCommand(BackgroundCommand<T> cmd, T obj)
      Start a new thread that will call the given command's applyTo() method to make some change in the domain object. This method should be called for an operation that could potentially take a long time to complete.
      Parameters:
      cmd - command that will be executed in another thread (not the AWT Thread)
      obj - domain object that the command will be applied to

    • scheduleFollowOnCommand

      public <T extends DomainObject> void scheduleFollowOnCommand(BackgroundCommand<T> cmd, T obj)
      Add the given background command to a queue that is processed after the main background command completes.
      Parameters:
      cmd - background command to submit
      obj - the domain object to be modified by the command.

    • execute

      public void execute(Task task, int delay)
      Launch the task in a new thread
      Parameters:
      task - task to run in a new thread
      delay - number of milliseconds to delay the display of task monitor dialog

    • execute

      public void execute(Task task)
      Launch the task in a new thread
      Parameters:
      task - task to run in a new thread

    • getOptions

      public ToolOptions getOptions(String categoryName)
      Description copied from interface: Tool
      Get the options for the given category name; if no options exist with the given name, then one is created.
      Parameters:
      categoryName - the category name
      Returns:
      the options

    • registerOptionsNameChange

      public void registerOptionsNameChange(String oldName, String newName)
      Updates saved options from an old name to a new name. NOTE: this must be called before any calls to register or get options.
      Parameters:
      oldName - the old name of the options.
      newName - the new name of the options.

    • hasOptions

      public boolean hasOptions(String category)
      Return true if there is an options category with the given name
      Parameters:
      category - name of the options set
      Returns:
      true if there is an options category with the given name

    • getOptions

      public ToolOptions[] getOptions()
      Get all options.
      Returns:
      zero-length array if no options exist.

    • getProject

      public Project getProject()
      Get the project associated with this tool. Null will be returned if there is no project open or if this tool does not use projects.
      Returns:
      null if there is no open project

    • getProjectManager

      public ProjectManager getProjectManager()
      Returns the project manager associated with this tool.

      Null will be returned if this tool does not use projects.

      Returns:
      the project manager associated with this tool

    • getToolServices

      public ToolServices getToolServices()
      Returns an object that provides fundamental services that plugins can use
      Returns:
      the services instance

    • setSubTitle

      public void setSubTitle(String subTitle)
      Sets the subtitle on the tool; the subtitle is extra text in the title.
      Parameters:
      subTitle - the subtitle to display on the tool

    • addPlugin

      public void addPlugin(String className) throws PluginException
      Add a plugin to the tool.
      Parameters:
      className - name of the plugin class, e.g., "MyPlugin.class.getName()"
      Throws:
      PluginException - if the plugin could not be constructed, or there was problem executing its init() method, or if a plugin of this class already exists in the tool

    • addPlugins

      @Deprecated(since="10.2", forRemoval=true) public void addPlugins(String[] classNames) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      use addPlugins(Collection)
      Add plugins to the tool.
      Parameters:
      classNames - array of plugin class names
      Throws:
      PluginException - if a plugin could not be constructed, or there was problem executing its init() method, or if a plugin of this class already exists in the tool

    • addPlugins

      public void addPlugins(Collection<String> classNames) throws PluginException
      Add plugins to the tool.
      Parameters:
      classNames - collection of plugin class names
      Throws:
      PluginException - if a plugin could not be constructed, or there was problem executing its init() method, or if a plugin of this class already exists in the tool

    • addPlugin

      public void addPlugin(Plugin p) throws PluginException
      Throws:
      PluginException

    • removePlugins

      @Deprecated(since="10.2", forRemoval=true) public void removePlugins(Plugin[] plugins)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use removePlugins(List)
      Remove the array of plugins from the tool.
      Parameters:
      plugins - array of plugins to remove

    • removePlugins

      public void removePlugins(List<Plugin> plugins)
      Remove the array of plugins from the tool.
      Parameters:
      plugins - array of plugins to remove

    • hasUnsavedData

      public boolean hasUnsavedData()

    • getManagedPlugins

      public List<Plugin> getManagedPlugins()
      Return a list of plugins in the tool
      Returns:
      list of plugins in the tool

    • saveTool

      public void saveTool()
      Save this tool's configuration.

    • saveToolAs

      public boolean saveToolAs()
      Triggers a 'Save As' dialog that allows the user to save off the tool under a different name. This returns true if the user performed a save.
      Returns:
      true if a save happened

    • addStatusComponent

      public void addStatusComponent(JComponent c, boolean addBorder, boolean rightSide)
      Add a status component to the tool.
      Parameters:
      c - component to add
      addBorder - true if a border should be added to the component
      rightSide - true if the component should be placed in the right side of the tool

    • removeStatusComponent

      public void removeStatusComponent(JComponent c)
      Remove the status component.
      Parameters:
      c - status component to remove

    • addExitAction

      protected void addExitAction()

    • addOptionsAction

      protected void addOptionsAction()

    • addSaveToolAction

      protected void addSaveToolAction()

    • addNextPreviousProviderActions

      protected void addNextPreviousProviderActions()
      Adds actions to the tool for transferring focus to the first component in the next or previous dockable component provider.

    • addExportToolAction

      protected void addExportToolAction()

    • addHelpActions

      protected void addHelpActions()

    • clearLastEvents

      public void clearLastEvents()
      Clear the list of events that were last generated.

    • close

      public void close()
      Closes this tool, possibly with input from the user. The following conditions are checked and can prompt the user for more info and allow them to cancel the close.
      1. Running tasks. Closing with running tasks could lead to data loss.
      2. Plugins get asked if they can be closed. They may prompt the user to resolve some plugin specific state.
      3. The user is prompted to save any data changes.
      4. Tools are saved, possibly asking the user to resolve any conflicts caused by changing multiple instances of the same tool in different ways.
      5. If all the above conditions passed, the tool is closed and disposed.

    • canClose

      protected boolean canClose()

    • allowTerminatingTasksWhenClosing

      protected boolean allowTerminatingTasksWhenClosing()
      Normally, tools are not allowed to close while tasks are running in that tool as it could leave the application in an unstable state. Tools that exit the application (such as the FrontEndTool) can override this so that the user can terminate running tasks and not have that prevent exiting the application.
      Returns:
      whether the user is allowed to terminate tasks so that the tool can be closed.

    • canClosePlugins

      protected boolean canClosePlugins()
      Checks if this tool's plugins are in a state to be closed.
      Returns:
      true if all the plugins in the tool can be closed without further user input.

    • canStopTasks

      protected boolean canStopTasks()
      Checks if this tool has running tasks, with optionally giving the user an opportunity to cancel them.
      Returns:
      true if this tool has running tasks

    • shouldSave

      public boolean shouldSave()
      Returns true if this tool needs saving
      Returns:
      true if this tool needs saving

    • doSaveTool

      protected boolean doSaveTool()
      Called when it is time to save the tool. Handles auto-saving logic.
      Returns:
      true if a save happened

    • canCloseDomainObject

      public boolean canCloseDomainObject(DomainObject domainObject)
      Can the domain object be closed?
      Note: This forces plugins to terminate any tasks they have running for the indicated domain object and apply any unsaved data to the domain object. If they can't do this or the user cancels then this returns false.
      Parameters:
      domainObject - the domain object to check
      Returns:
      false any of the plugins reports that the domain object should not be closed

    • canCloseDomainFile

      public boolean canCloseDomainFile(DomainFile domainFile)

    • prepareToSave

      public void prepareToSave(DomainObject dobj)
      Called when the domain object is about to be saved; this allows any plugin that has a cache to flush out to the domain object.
      Parameters:
      dobj - domain object that is about to be saved

    • setSize

      public void setSize(int width, int height)
      Sets the size of the tool's main window
      Parameters:
      width - width in pixels
      height - height in pixels

    • getSize

      public Dimension getSize()
      Return the dimension of this tool's frame.
      Returns:
      dimension of this tool's frame

    • setLocation

      public void setLocation(int x, int y)
      Set the location of this tool's frame on the screen.
      Parameters:
      x - screen x coordinate
      y - screen y coordinate

    • getLocation

      public Point getLocation()
      Return the location of this tool's frame on the screen.
      Returns:
      location of this tool's frame

    • restoreOptionsFromXml

      protected void restoreOptionsFromXml(org.jdom.Element root)

    • setProject

      protected void setProject(Project project)

    • restorePluginsFromXml

      protected void restorePluginsFromXml(org.jdom.Element elem) throws PluginException
      Throws:
      PluginException

    • addEventListener

      public void addEventListener(Class<? extends PluginEvent> eventClass, PluginEventListener listener)

    • addListenerForAllPluginEvents

      public void addListenerForAllPluginEvents(PluginEventListener listener)

    • removeListenerForAllPluginEvents

      public void removeListenerForAllPluginEvents(PluginEventListener listener)

    • removeEventListener

      public void removeEventListener(Class<? extends PluginEvent> eventClass, PluginEventListener listener)

    • cancelCurrentTask

      public void cancelCurrentTask()
      Cancel the current task in the tool.

    • getTransientState

      public TransientToolState getTransientState()

    • getUndoRedoToolState

      public UndoRedoToolState getUndoRedoToolState(DomainObject domainObject)

    • showDialogOnActiveWindow

      @Deprecated public void showDialogOnActiveWindow(DialogComponentProvider dialogComponent)
      Deprecated.
      dialogs are now always shown over the active window when possible
      Shows the dialog using the tool's currently active window as a parent. Also, remembers any size and location adjustments made by the user for the next time the dialog is shown.
      Parameters:
      dialogComponent - the DialogComponentProvider object to be shown in a dialog.

    • showDialog

      public void showDialog(DialogComponentProvider dialogComponent, ComponentProvider centeredOnProvider)
      Shows the dialog using the window containing the given componentProvider as its parent window. Remembers the last location and size of this dialog for the next time it is shown.
      Parameters:
      dialogComponent - the DialogComponentProvider object to be shown in a dialog.
      centeredOnProvider - the component provider that is used to find a parent window for this dialog. The dialog is centered on this component provider's component.

    • showDialog

      public void showDialog(DialogComponentProvider dialogComponent, Component centeredOnComponent)
      Shows the dialog using the tool's parent frame, but centers the dialog on the given component
      Parameters:
      dialogComponent - the DialogComponentProvider object to be shown in a dialog.
      centeredOnComponent - the component on which to center the dialog.

    • getActiveWindow

      public Window getActiveWindow()

    • getActiveComponentProvider

      public ComponentProvider getActiveComponentProvider()
      Description copied from interface: Tool
      Returns the active component provider, that which has focus
      Specified by:
      getActiveComponentProvider in interface Tool
      Overrides:
      getActiveComponentProvider in class AbstractDockingTool
      Returns:
      the active provider

    • setUnconfigurable

      public void setUnconfigurable()

    • isConfigurable

      public boolean isConfigurable()

    • removePreferenceState

      @Deprecated(since="11.3", forRemoval=true) public void removePreferenceState(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use the DockingWindowManager
      This method will be deleted. Preference state should be managed with the DockingWindowManager.
      Parameters:
      name - the name

    • contextChanged

      public void contextChanged(ComponentProvider provider)
      Description copied from interface: Tool
      Signals to the tool that the provider's context has changed. This lets toolbar and menu actions update enablement based on current context.

      Pass null to signal that the entire tool's context has changed

      Specified by:
      contextChanged in interface Tool
      Overrides:
      contextChanged in class AbstractDockingTool
      Parameters:
      provider - the provider whose context changed; null to signal the tool's context

    • isRestoringDataState

      public boolean isRestoringDataState()