<type>documentation</type>
<domain>scripting</domain>
<id>gui-contexts</id>
<title>Adding Scripts to the GUI</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Scripts that define a new command for the IDE may add that command to the user interface
in various ways. This is done by setting the ``contexts`` attribute on the function that
implements the command.

The following example adds the script-provided command ``test-script`` to a new menu
``Scripts`` and the editor's right-click context menu:

.. python::

  test_script.contexts = [
    wingapi.kContextNewMenu("Scripts"),
    wingapi.kContextEditor(),
  ]

These contexts are available for script-provided commands:

  **kContextNewMenu(title, group=0)** adds an item to a menu in the menu bar. If multiple
  scripts use the same context, they are all added to the same menu. The required argument
  ``title`` specifies the title to use for the menu, and the optional argument ``group``
  is a number that allows separating items in the menu into groups. Groups are created as
  needed and items are listed in alphabetical order within them.
  
  **kContextEditor()** adds an item to the end of the editor's right-click context menu.
    
  **kContextProject()** adds an item to the end of the project's right-click context menu.
  
  **kContextCommonMenu** adds an item to the end of the common actions item in the top right
  of Wing's window.
  
Regardless of whether script-provided command is added to any GUI context, it will always
be listed under both short and fully qualified name in the auto-completer for ``Command by
Name`` in the ``Edit`` menu, and in the `User Interface > Keyboard > Custom Key Bindings
<script:show_preferences_gui#prefname="gui.keymap-override">`__ preference.

