Package ghidra.framework.plugintool

Class PluginTool

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

    • 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.
        Specified by:
        getService in interface ServiceProvider
        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.
        Specified by:
        addServiceListener in interface 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.
        Specified by:
        removeServiceListener in interface 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)
        Description copied from interface: Tool
        Returns a ToolTemplate for this Tool that describes the state of the tool.
        Specified by:
        getToolTemplate in interface Tool
        Returns:
        a ToolTemplate for this Tool that describes the state of the tool.

      • saveToolToToolTemplate

        public ToolTemplate saveToolToToolTemplate()
        Description copied from interface: Tool
        Save the tool and return its state as a ToolTemplate. Forces a complete regeneration of the tool template.
        Specified by:
        saveToolToToolTemplate in interface Tool
        Returns:
        a toolTemplate for this tool.

      • saveWindowingDataToXml

        public org.jdom.Element saveWindowingDataToXml()
        Description copied from interface: Tool
        Saves the tool's Docking Window layout and positioning information to an XML element.
        Specified by:
        saveWindowingDataToXml in interface Tool
        Returns:
        the element containing the DockingWindow's layout information.

      • restoreWindowingDataFromXml

        public void restoreWindowingDataFromXml​(org.jdom.Element windowData)
        Description copied from interface: Tool
        Restores the tool's Docking Window layout and positioning information from an XML element.
        Specified by:
        restoreWindowingDataFromXml in interface Tool
        Parameters:
        windowData - the element containing the information.

      • acceptDomainFiles

        public boolean acceptDomainFiles​(DomainFile[] data)
        Description copied from interface: Tool
        When the user drags a data file onto a tool, an event will be fired that the tool will respond to by accepting the data.
        Specified by:
        acceptDomainFiles in interface Tool
        Parameters:
        data - the data to be used by the running tool

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.PropertyChangeListener l)
        Description copied from interface: Tool
        Add property change listener.
        Specified by:
        addPropertyChangeListener in interface Tool

      • addToolListener

        public void addToolListener​(ToolListener listener)
        Description copied from interface: Tool
        Adds a ToolListener to be notified for any of a Tool's ToolEvents. The listener will be notified of any events that this tool generates.
        Specified by:
        addToolListener in interface Tool
        Parameters:
        listener - ToolListener to be added to receive all events

      • 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()
        Description copied from interface: Tool
        Tells the tool to stop functioning and release its resources. The tool should dispose of all its windows and other resources.
        Specified by:
        exit in interface Tool

      • dispose

        protected void dispose()

      • firePluginEvent

        public void firePluginEvent​(PluginEvent event)
        Description copied from interface: Tool
        Fire the plugin event by notifying the event manager which calls the listeners.
        Specified by:
        firePluginEvent in interface Tool
        Parameters:
        event - plugin event

      • getConsumedToolEventNames

        public java.lang.String[] getConsumedToolEventNames()
        Description copied from interface: Tool
        Returns a list of eventNames that this Tool is interested in.
        Specified by:
        getConsumedToolEventNames in interface Tool

      • getDomainFiles

        public DomainFile[] getDomainFiles()
        Description copied from interface: Tool
        Get the domain files that this tool currently has open.
        Specified by:
        getDomainFiles in interface Tool

      • getIcon

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

      • getIconURL

        public ToolIconURL getIconURL()
        Description copied from interface: Tool
        Get the url for the icon that this tool is using.
        Specified by:
        getIconURL in interface Tool

      • getInstanceName

        public java.lang.String getInstanceName()
        Description copied from interface: Tool
        Returns the tool's unique name.
        Specified by:
        getInstanceName in interface Tool

      • getName

        public java.lang.String getName()
        Description copied from interface: DockingTool
        Returns a combination of the tool name and the instance name of the form tool name(instance name), e.g., SomeTool(2)
        Specified by:
        getName in interface DockingTool
        Returns:
        the tool name

      • getSupportedDataTypes

        public java.lang.Class<?>[] getSupportedDataTypes()
        Description copied from interface: Tool
        Get the classes of the data types that this tool supports, i.e., what data types can be dropped onto this tool.
        Specified by:
        getSupportedDataTypes in interface Tool

      • getToolEventNames

        public java.lang.String[] getToolEventNames()
        Description copied from interface: Tool
        Returns the names of all the possible ToolEvents that this tool might generate. Used by the ConnectionManager to connect tools together.
        Specified by:
        getToolEventNames in interface Tool

      • getToolName

        public java.lang.String getToolName()
        Description copied from interface: Tool
        Returns the name associated with the tool
        Specified by:
        getToolName in interface Tool

      • putInstanceName

        public void putInstanceName​(java.lang.String newInstanceName)
        Description copied from interface: Tool
        Associates a unique(within the active project) name to a tool instance.
        Specified by:
        putInstanceName in interface Tool
        Parameters:
        newInstanceName - unique tool instance name

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.beans.PropertyChangeListener l)
        Description copied from interface: Tool
        Remove property change listener.
        Specified by:
        removePropertyChangeListener in interface Tool

      • removeToolListener

        public void removeToolListener​(ToolListener listener)
        Description copied from interface: Tool
        Removes a ToolListener from receiving any event generated by this Tool. The tool will still recieve specific events that it has registered for.
        Specified by:
        removeToolListener in interface Tool
        Parameters:
        listener - The ToolListener to be removed from receiving all events.

      • restoreDataStateFromXml

        public void restoreDataStateFromXml​(org.jdom.Element root)
        Description copied from interface: Tool
        Tells tool to read its data state from the given input stream.
        Specified by:
        restoreDataStateFromXml in interface Tool
        Parameters:
        root - XML data state

      • saveDataStateToXml

        public org.jdom.Element saveDataStateToXml​(boolean savingProject)
        Description copied from interface: Tool
        Tells tool to write its data state from the given output stream.
        Specified by:
        saveDataStateToXml in interface Tool
        Parameters:
        savingProject - true if saving the toolstate is for a potential undo/redo (database transaction)

      • restoreFromXml

        protected boolean restoreFromXml​(org.jdom.Element root)

      • saveToXml

        public org.jdom.Element saveToXml​(boolean includeConfigState)
        Specified by:
        saveToXml in interface Tool

      • setIconURL

        public void setIconURL​(ToolIconURL newIconURL)
        Description copied from interface: Tool
        Set the icon for this tool.
        Specified by:
        setIconURL in interface Tool
        Parameters:
        newIconURL - icon location

      • setToolName

        public void setToolName​(java.lang.String name)
        Description copied from interface: Tool
        Sets the type name of the tool.
        Specified by:
        setToolName in interface Tool
        Parameters:
        name - the basename to use when setting the tool's name

      • processToolEvent

        public void processToolEvent​(PluginEvent toolEvent)
        Description copied from interface: ToolListener
        This method is invoked when the registered ToolEvent event occurs.
        Specified by:
        processToolEvent in interface ToolListener
        Parameters:
        toolEvent - The cross-tool PluginEvent.

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

      • getOptions

        public ToolOptions getOptions​(java.lang.String categoryName)
        Get the options for the given category name; if no options exist with the given name, then one is created.
        Specified by:
        getOptions in interface DockingTool
        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.

      • 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

      • 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.
        Specified by:
        close in interface DockingTool

      • shouldSave

        public boolean shouldSave()
        Description copied from interface: Tool
        Returns true if this tool should save its data, based upon its changed state and the state of Ghidra's saving method.
        Specified by:
        shouldSave in interface Tool
        Returns:
        true if this tool should save its data

      • 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.
        Specified by:
        canClose in interface Tool
        Parameters:
        isExiting - true if all of Ghidra is closing, false if just this tool is closing.
        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)
        Description copied from interface: Tool
        Can the domain File 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.
        Specified by:
        canCloseDomainFile in interface Tool
        Returns:
        false any of the plugins reports that the domain object should not be closed

      • 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

        public void showDialogOnActiveWindow​(DialogComponentProvider dialogComponent)
        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)