Script Attributes

Index of All Documentation » Wing Pro Reference Manual » Scripting and Extending Wing » Script Syntax »


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 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 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:

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 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 for details.