==========================
ExtensionManager (hwx.gui)
==========================

The ExtensionManager class is used to register and load user-defined extensions
in the Extension Manager.

An extension provides the means to extend the application through shared
libraries or scripts.
Use extensions to create new clients, profiles, contexts, model views etc.
Sample extensions that illustrate the various use cases are included in the
Extension Manager. All the extensions located under the default extensions directory
(/Documents/Altair/CustomPlugins) specified under the preferences dialog are
automatically registered by the Extension Manager.

An Extension is a physical folder with extension.xml and related scripts and
resources placed in it.
An extension.xml is the manifest file for the extension that defines metadata of
the extension such as name, version, minimum supported product version etc.

Table 1. Supported attributes in extension.xml

+------------------------+---------------------------------------------------+
|Attributes              | Description                                       |
+========================+===================================================+
| name                   | Name of the Extension                             |
+------------------------+---------------------------------------------------+
| minProductVersion      | The minimum version of the product that is        |
|                        | supported by this extension.                      |
+------------------------+---------------------------------------------------+
| description            | A short description about this extension that is  |
|                        | displayed in the Extension Manager user interface.|
+------------------------+---------------------------------------------------+
| documentation          | HTML file with the detailed description of the    |
|                        | extension that can be opened in a web browser     |
|                        | through the Extension Manager UI.                 |
+------------------------+---------------------------------------------------+
| author                 | The author of this extension.                     |
+------------------------+---------------------------------------------------+
| script                 | Script that should be executed when this extension|
|                        | is loaded.                                        |
+------------------------+---------------------------------------------------+
| resources              | Location of the resourcess' directory relative to |
|                        | the extensions' directory.                        |
+------------------------+---------------------------------------------------+
| settings               | An xml file that defines the settings of this     |
|                        | extension.                                        |
+------------------------+---------------------------------------------------+
| advancedToolTip        | An xml file that defines the tooltips related to  |
|                        | this extension.                                   |
+------------------------+---------------------------------------------------+
| workFlowHelp           | An xml file that defines the workflow help content|
|                        | of this extension.                                |
+------------------------+---------------------------------------------------+
| required               | The plugin that should be loaded as a             |
|                        | pre-requisite for this extension.                 |
+------------------------+---------------------------------------------------+
| extends                | The plugin after which this plugin is an          |
|                        | auto loaded.                                      |
+------------------------+---------------------------------------------------+
| client                 | The name of the client that is implemented in this|
|                        | extension or the name of the client to which the  |
|                        | profile implemented in this extension belongs to. |
+------------------------+---------------------------------------------------+
| profile                | The name of the profile implemented in            |
|                        | this extension.                                   |
+------------------------+---------------------------------------------------+

--------------
Public Methods
--------------

  +----------------------------+
  | get_ (self)                |
  +----------------------------+
  | getExtensionManager_ ()    |
  +----------------------------+
  | load_ (self, name)         |
  +----------------------------+
  | onUnload_ (self, callback) |
  +----------------------------+
  | register_ (self, path)     |
  +----------------------------+
  | unload_ (self, name)       |
  +----------------------------+
  | unregister_ (self, name)   |
  +----------------------------+

--------------
Method Details
--------------

.. _get:
.. method:: get(self)

Returns the singleton instance of the Extension Manager.


.. _getExtensionManager:
.. method:: getExtensionManager()

Returns the singleton instance of the Extension Manager.

.. _load:
.. method:: load(self, name)

Load a registered extension.

This runs the plugin script making it active.

:param name: The name specified in the extensions's plugin.xml
:type name: str


.. _onUnload:
.. method:: onUnload(self, callback)

Register function to cleanup the currently loading plugin.

Make sure to remove any gui (typically SpriteActions).

:param callback: Cleanup function
:type callback: function


.. _register:
.. method:: register(self, path)

Register an extension

This makes it appear in the File->Extension Manager.
Use extensionManager.load to activate it.

:param path: Path to a plugin.xml or a directory containing one.
:type path: str

:raises: :exc:`FileNotFoundError`


.. _unload:
.. method:: unload(self, name)

Unloads an extension.

Any Actions added by the plugin are removed from the gui.

:param name: The name specified in the extensions's plugin.xml
:type name: str


.. _unregister:
.. method:: unregister(self, name)

Unregister an extension.

:param name: The name specified in the extensions's plugin.xml
:type name: str