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 be a device which might be used many times but it is called differently for each instance.

        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