<type>documentation</type>
<domain>scripting</domain>
<id>script-attribs</id>
<title>Script Attributes</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

The scripting API uses function attributes as a way to annotate script functions that
define a new command for the IDE. These are used to define the type of arguments the
command expects, command availability, the display name and documentation for the command,
and the contexts in which the command should be made available in the GUI.

The following function attributes may be set.  Each one can be a value or a callable
object that returns the value:

  **arginfo** defines the argument types for any arguments passed to the command. This is
  used by Wing to drive automatic collection of argument values from the user. When this
  is missing, all arguments are treated as strings. See `Argument Collection
  <ref:scripting/arginfo>`__ for details.
  
  **available** defines whether or not the command is available. If missing, the command
  is always available. If set to a constant, ``bool(available)`` defines availability of
  the command. If set to a callable object, it is invoked with the same arguments as the
  command and the return value determines availability of the command.
  
  **label** provides the label to use when referring to the command in menus and elsewhere.
  When omitted, the label is derived from the command name by replacing underscores with a
  space and capitalizing each word (``cmdname.replace('_', ' ').title()``)
    
  **contexts** lists the GUI contexts the which the command should appear. See `Adding
  Scripts to the GUI <ref:scripting/gui-contexts>`__ for details.
    
  **doc** is the documentation for the command if for some reason a docstring in the function
  definition can't be used.
    
  **flags** is a dictionary of options that control behavior of the script.  Currently the 
  only option is ``force_dialog_argentry`` which may be set to ``True`` to collect
  arguments for the script in a dialog, rather than at the bottom of the IDE window.

  **plugin_override** may be set in scripts that are designated as plugins, in order to
  indicate that the command should be enabled even if the plugin is not.
  
The following example uses the above to add a script-defined command to the editor context
menu, set the label used in the menu, and indicate when the command is available:

.. python::

  import wingapi
  def test_script():
    pass
  test_script.contexts = [wingapi.kContextEditor()]
  test_script.label = "Do Nothing"
  def _test_script_available():
    return 1
  test_script.available = _test_script_available
  
**Script-Wide Default Attributes**

Default values for some of the attributes defined above can be set at the top level of the
script file:

  **_arginfo** is the default argument information to use for scripts that don't have
  an ``arginfo`` attribute of their own.
  
  **_available** defines the default availability of scripts without an ``available`` 
  attribute.
  
  **_contexts** sets the default GUI contexts into which scripts should be added if
  they do not have their own ``contexts`` attribute.

Some additional attributes are also supported, to control how Wing treats the script
file as a whole:

  **_ignore_scripts** can be set to ``True`` to completely ignore this script file.
  
  **_i18n_module** names the ``gettext`` internationalized string database to use when
  translating docstrings in this script. See `Internationalization and Localization
  <ref:scripting/i18n>`__ for details.
  
  **_plugin** indicates that the script is a plugin that can be selectively enabled and
  disabled either according to IDE state or by the user in preferences. See `Plugins
  <ref:scripting/plugins>`__ for details.

