Package net.emustudio.emulib.plugins

Interface Plugin

  • All Known Subinterfaces:
    Compiler, CPU, Device, Memory
    All Known Implementing Classes:
    AbstractCompiler, AbstractCPU, AbstractDevice, AbstractMemory
    public interface Plugin
    Plugin main interface. This interface is available only to emuStudio, not to other plugins. Plugins communicate with each other using special entities called "contexts".

    CONTRACT:

    Each plugin must meet several requirements:

    - this interface, or its derivative, must be implemented by one and only one class (so-called "root class") - the root class has to be annotated with PluginRoot annotation with required parameters - the root class has to have single constructor with 3 parameters (see below).

    The constructor signature has to look like this:

    \@PluginRoot(...) SamplePlugin(long pluginId, ApplicationApi emustudio, PluginSettings settings) { ... }

    1. pluginId is a unique plugin identification. Operations around plugin contexts require it as input argument.

    2. emustudio is the API provided by emuStudio application, to be used by plugins.

    3. settings plugin's settings. A plugin can use it for reading/writing its custom settings. Updated settings are saved immediately in the configuration file, in the same thread.

    NOTE: Plugins should register the contexts they provide into the ContextPool, which can be obtained from ApplicationApi API.

    Plugins must not try to obtain contexts from the context pool from plugin constructor. The reason is that the order of plugin context registration is fixed, and in the plugin construction time some contexts don't need to be available yet. Plugin contexts can be safely obtained within initialize() method.

    • Method Detail

      • reset

        void reset()
        Reset plugin.

        "Reset" means to bring the plugin to its "initial state", as it was after calling initialize().

      • destroy

        void destroy()
        Destroys all plugin resources.

        This method is called immediately after user closes the emulator.

        Inside the method, the plugin should: - unregister all registered contexts for this plugin - execute clean-up/destroy code for used resources (timers, threads, sockets, memory, etc). - dispose all GUIs

        NOTE: If not all resources are properly cleared, emuStudio will forcibly exit anyway, which may cause unexpected damage.

      • showSettings

        void showSettings​(javax.swing.JFrame parent)
        Show GUI of plugin settings, if it is provided.

        Each plugin can have a nice GUI for settings manipulation. plugins should display the GUI, if they support it. Note that each window should be properly disposed when method destroy() is called.

        In the case of memory plugin, show GUI of a memory. Each memory plugin should have a GUI, but it is not a must.

        Parameters:
        parent - emuStudio main window (if plugin wants to show a dialog which has a parent)

      • isShowSettingsSupported

        boolean isShowSettingsSupported()
        Check if showSettings() is supported by this plugin.
        Returns:
        true if the plugin has a GUI for settings; false otherwise

      • getTitle

        java.lang.String getTitle()
        Get run-time title of this plugin.

        The title is a matter of change during runtime - for example there might exist a device instantiated more than once, and each instance can have different title assigned at runtime.

        Returns:
        run-time title of the plugin

      • getVersion

        java.lang.String getVersion()
        Get version of the plugin.
        Returns:
        version string

      • getCopyright

        java.lang.String getCopyright()
        Get copyright string.
        Returns:
        copyright string

      • getDescription

        java.lang.String getDescription()
        Get plugin short description.
        Returns:
        plugin description

      • isAutomationSupported

        boolean isAutomationSupported()
        Determines if this plugin supports emulation automation
        Returns:
        true if the plugin supports emulation automation; false otherwise