Scorpion Plugin Interface¶

A Scorpion plugin is a python module implementing the Scorpion Plugin Interface. The Scorpion Plugin Interface consist in it’s simplest form a stub function and a class with a few required methods.

File header¶

Below is the recommended file header, a Python AutoDoc format for automatic generation of python module documentation. The format generates reStructuredText documents.

"""
:filename:     <filename>
:author:       <author>
:requirements: Scorpion <version> or higher
:copyright:    <year company>
:license:      <license>

<description>

::

  1.0.0.2, 11nov2015, <initials>: modified for autodoc
  1.0.0.1, 03jun2015, <initials>: created

"""
__version__ = '1.0.0.2'

#implementation goes below here....

Field	Deccription
<description>	plugin description/purpose
<filename>	current filename
<author>	author identification, name/email
<requirements>	any requirements/dependencies to run plugin
<copyright>	plugin copyrights ie. 2000-2015 Tordivel AS
<license>	plugin license terms
<version>	Scorpion version, ex. 11.0.0.612
<initials>	responsible initials for revision, ex. RL

Replace the braces content to fit the plugin.

The __version__ variable is used by the PluginManager and should be maintained due to current version.

Example:

"""
:filename:     SamplePlugin.py
:author:       roar@tordivel.no
:requirements: Scorpion 9.0.0.494 or higher
:copyright:    2000-2015 Tordivel AS
:license:      Tordivel AS' Scorpion Python Plugin License

Scorpion sample plugin for hosting controls inside a PluginManager
hosted panel/page

::

  1.0.0.2, 11nov2015, RL: modified for autodoc
  1.0.0.1, 03jun2015, RL: created
"""

__version__ = '1.0.0.2'

Required stub function¶

Below is the required stub function used by Scorpion to instantiate the plugin. This function should have the exact signature as below.

def CreatePlugin(hWnd, name=''):
  """
  Scorpion Plugin Stub - **Required** - called for plugin creation

  ``hWnd`` - parent window handle

  ``name`` - Scorpion supplied unique instance name
  """
  cntr=GetControlByHandle(hWnd)
  return <PluginClass>(cntr,name)

Example

def CreatePlugin(hWnd, name=''):
  """
  Scorpion Plugin Stub - **Required** - called for plugin creation

  ``hWnd`` - parent window handle

  ``name`` - Scorpion supplied unique instance name
  """
  cntr=GetControlByHandle(hWnd)
  return SamplePlugin(cntr,name)

Class implementation¶

Below is the recommended class implementation. Note the comments adapted for autodoc.

from Scorpion import InputDialog, PluginChanged

class <classname> : <baseclass>:
  """This is the documentation sample class implementation"""

def __init__(self,cntr,name):
  """initiate class members"""
  self.name=name                    #name of this instance
  self.cntr=cntr                    #the container control

def __str__(self):
  """
  Returns an instance unique name for the plugin.

  The unique name is used for persistance key by the host application if the
  plugin has configuration. Python objects default's to an instance name like
  "<__main__.A object at 0x053E02D0>" where the address part will change for
  each instance of the plugin.

  This method is not required if the plugin don't have any configuration but
  it's still good practice implementing.
  """
  return '%s_%s'%(self.__class__.__name__,self.name)

def getConfig(self):
  """
  [OPTIONAL]

  Return the plugin configuration as a string, any format. The host application
  don't care the content so any suitable string content may be used. It is still
  recommended to use a format that is prepared for plugin upgrades so the plugin
  will still work with configuration from a previous version of the plugin.

  Dictionaries are well suited for configuration strings
  """
  return str({'version':__version__})

def setConfig(self,value):
  """
  [OPTIONAL]

  Set plugin configuration from the string 'value'. The host application sets the
  configuration after the plugin is created.

  ``value`` - string representation of new configuration
  """
  cfg=eval(value)
  if cfg['version']=='1.0.0.2':
    #do some stuff
  pass

  def configure(self):
  """
  [OPTIONAL]

  Launches the configuration dialog for plugin configuration.

  If changed, notify the host applicaton if the configuration is changed for
  configuration persistance.
  """
  ok,cfg=InputDialog('Plugin configuration',self.getConfig())
  if ok:
    self.setConfig(cfg)
    PluginChanged(self)