<type>documentation</type>
<domain>scripting</domain>
<id>plugins</id>
<title>Plugin Extensions</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

When a script contains the ``_plugin`` attribute at the top level, it is treated as a
plugin that can enable or disable its extensions as a whole, usually in response to
inspecting the current project to determine whether the extensions are suitable
for the project.  Scripts that act as plugins in this way should not be confused
with `IDE Plugins <ref:/plugins/index>`__ that extend specific sub-systems of 
functionality in the IDE in a more structured way.

When ``_plugin`` is present, it contains ``(name,`` ``activator_cb``) where ``name`` is
the display name of the plugin and ``activator_cb`` is a function minimally defined as
follows for a plugin that is always enabled:

.. python::

  import wingapi
  def _activator_cb(plugin_id):
    return True
  _plugin = ('myplugin', _activator_cb)

``EnablePlugin`` may also be called from any other script code, including signal handlers.
For example, a script might watch the current project using the ``project-open`` signal on
``CAPIApplication`` and enable or disable the plugin based on which project is open:

.. python::

  import wingapi
  
  # Activator is needed to store the uniquified plugin_id; start out disabled
  _plugin_id = [None]
  def _activator_cb(plugin_id):
      _plugin_id[0] =  plugin_id
      return False
  _plugin = ('myplugin', _activator_cb)
  
  # Watch project and activate plugin based on project name
  def _proj_open(filename):
      wingapi.gApplication.EnablePlugin(_plugin_id[0], 'ide' not  in filename)
  wingapi.gApplication.Connect('project-open', _proj_open)

When a plugin is inactive, its commands are undefined and any menus or menu items it added
to the GUI are removed. Plugins may denote particular commands as always available even
when the plugin is inactive by setting the ``_plugin_override`` function attribute to
``True``.

If the user disables a plugin in the ``Edit`` menu, this completely prevents loading the
plugin, which overrides ``_activator_cb`` and any ``_plugin_override`` attributes for
functions that define commands for the plugin.
