Package ghidra.framework.plugintool

Class PluginTool

    • Field Detail

      • TOOL_NAME_PROPERTY

        public static final java.lang.String TOOL_NAME_PROPERTY
        Name of the property for the tool name.
        See Also:
        Constant Field Values

      • ICON_PROPERTY_NAME

        public static final java.lang.String ICON_PROPERTY_NAME
        Name of the property for the tool icon.
        See Also:
        Constant Field Values

      • DESCRIPTION_PROPERTY_NAME

        public static final java.lang.String DESCRIPTION_PROPERTY_NAME
        Name of the property for the description of the tool.
        See Also:
        Constant Field Values

      • PLUGIN_COUNT_PROPERTY_NAME

        public static final java.lang.String PLUGIN_COUNT_PROPERTY_NAME
        Name of the property for the number of plugins the tool has.
        See Also:
        Constant Field Values

      • toolName

        protected java.lang.String toolName

      • isDisposed

        protected boolean isDisposed

    • Constructor Detail

      • 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,
                  java.lang.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,
                  java.lang.String name,
                  boolean isDockable,
                  boolean hasStatus,
                  boolean isModal)

      • PluginTool

        protected PluginTool()

    • Method Detail

      • 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()

      • initActions

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

      • optionsChanged

        protected void optionsChanged​(Options options,
                              java.lang.String name,
                              java.lang.Object oldValue,
                              java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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.

      • 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.

      • 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)

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.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

      • exit

        public void exit()

      • dispose

        protected void dispose()

      • firePluginEvent

        public void firePluginEvent​(PluginEvent event)

      • getConsumedToolEventNames

        public java.lang.String[] getConsumedToolEventNames()

      • getDomainFiles

        public DomainFile[] getDomainFiles()

      • getIcon

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

      • getInstanceName

        public java.lang.String getInstanceName()

      • getName

        public java.lang.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 java.lang.Class<?>[] getSupportedDataTypes()

      • getToolEventNames

        public java.lang.String[] getToolEventNames()

      • getToolName

        public java.lang.String getToolName()

      • putInstanceName

        public void putInstanceName​(java.lang.String newInstanceName)

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.beans.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​(java.lang.String name)

      • processToolEvent

        public void processToolEvent​(PluginEvent toolEvent)

      • execute

        public boolean execute​(Command command,
                       DomainObject 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:
        executeBackgroundCommand(BackgroundCommand, UndoableDomainObject)

      • 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 void executeBackgroundCommand​(BackgroundCommand cmd,
                                     UndoableDomainObject 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

      • terminateBackgroundCommands

        public void terminateBackgroundCommands​(boolean wait)
        Cancel any running command and clear the command queue.
        Parameters:
        wait - if true wait for current task to cancel cleanly

      • scheduleFollowOnCommand

        public void scheduleFollowOnCommand​(BackgroundCommand cmd,
                                    UndoableDomainObject 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​(java.lang.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​(java.lang.String oldName,
                                      java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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

        public void addPlugins​(java.lang.String[] classNames)
                throws PluginException
        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

      • hasUnsavedData

        public boolean hasUnsavedData()

      • removePlugins

        public void removePlugins​(Plugin[] plugins)
        Remove the array of plugins from the tool.
        Parameters:
        plugins - array of plugins to remove

      • getManagedPlugins

        public java.util.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​(javax.swing.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​(javax.swing.JComponent c)
        Remove the status component.
        Parameters:
        c - status component to remove

      • addExitAction

        protected void addExitAction()

      • addOptionsAction

        protected void addOptionsAction()

      • addSaveToolAction

        protected void addSaveToolAction()

      • 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()
        Close this tool:
        1. if there are no tasks running.
        2. resolve the state of any plugins so they can be closed.
        3. Prompt the user to save any changes.
        4. close all associated plugins (this closes the domain object if one is open).
        5. pop up dialog to save the configuration if it has changed.
        6. notify the project tool services that this tool is going away.

      • shouldSave

        public boolean shouldSave()

      • doSaveTool

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

      • canClose

        public boolean canClose​(boolean isExiting)
        Can this tool be closed?
        Note: This forces plugins to terminate any tasks they have running and apply any unsaved data to domain objects or files. If they can't do this or the user cancels then this returns false.
        Parameters:
        isExiting - whether the tool is exiting
        Returns:
        false if this tool has tasks in progress or can't be closed since the user has unfinished/unsaved changes.

      • 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 java.awt.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 java.awt.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)

      • addListenerForAllPluginEvents

        public void addListenerForAllPluginEvents​(PluginEventListener listener)

      • removeListenerForAllPluginEvents

        public void removeListenerForAllPluginEvents​(PluginEventListener listener)

      • showEditWindow

        public void showEditWindow​(java.lang.String defaultText,
                           java.awt.Component comp,
                           java.awt.Rectangle rect,
                           EditListener listener)
        Display an text edit box on top of the specified component.
        Parameters:
        defaultText - initial text to be displayed in edit box
        comp - component over which the edit box will be placed
        rect - specifies the bounds of the edit box relative to the component. The height is ignored. The default text field height is used as the preferred height.
        listener - when the edit is complete, this listener is notified with the new text. The edit box is dismissed prior to notifying the listener.

      • cancelCurrentTask

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

      • 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,
                       java.awt.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 java.awt.Window getActiveWindow()

      • refreshKeybindings

        public void refreshKeybindings()

      • setUnconfigurable

        public void setUnconfigurable()

      • isConfigurable

        public boolean isConfigurable()

      • removePreferenceState

        public void removePreferenceState​(java.lang.String name)

      • getDefaultToolContext

        public ActionContext getDefaultToolContext()
        Description copied from interface: Tool
        Returns the default ActionContext for the tool. The default context is the context the default ComponentProvider for the tool.
        Returns:
        the default ActionContext for the tool

      • 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