<type>documentation</type>
<domain>scripting</domain>
<id>example</id>
<title>Scripting Example Tutorial</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Trying a simple example script is the best way to get started with Wing's scripting API.
The following quick tutorial will take you through the process.

**Creating an Extension Script**

User-defined scripts are usually placed inside a directory named ``scripts`` located
inside the `Settings Directory <ref:install/user-settings-dir>`__. The ``scripts``
sub-directory needs to be created if it does not already exist.

Try adding a simple script now by pasting the following into a file called ``test.py``
inside the ``scripts`` directory:

.. python::

  import wingapi
  def test_script(test_str):
    app = wingapi.gApplication
    v = "Product info is: " + str(app.GetProductInfo())
    v += "\nAnd you typed: %s" % test_str
    wingapi.gApplication.ShowMessageDialog("Test Message", v)
  
Then select ``Reload All Scripts`` from the ``Edit`` menu. This is only needed the first
time a new script file is added, in order to get Wing to discover it. Afterward, Wing
automatically reloads scripts whenever they are saved to disk from the IDE.

**Executing the Script**

Try executing the script by selecting ``Command by Name`` in the ``Edit`` menu. This
displays an entry area at the bottom of the window, where you can type ``test-script`` and
then press the ``Enter`` key. Since the script has an argument without a default value,
Wing will collect that in the same entry area at the bottom of the IDE window. Type a
string and then press ``Enter``. The script will pop up a modal message dialog containing
the text that you typed.

Of course this is not how you will usually invoke a script. Instead, scripts be assigned
to a key binding or added to a menu, as described in the next section.

Try assigning a key binding now to the command ``test-script`` with the `User Interface >
Keyboard > Custom Key Bindings
<script:show_preferences_gui#prefname="gui.keymap-override">`__ preference. For details on
adding key bindings in Wing, see `Key Bindings <ref:custom/key-equivalents>`__.

**Editing the Script**

In order to place your script in a new menu in the menu bar, add the following after the
function definition:

.. python::

  test_script.contexts = [wingapi.kContextNewMenu("Scripts")]
  
As soon as you save this change, a menu ``Scripts`` should appear in the menu bar
with one item ``Test Script``.  This illustrates how scripts are auto-reloaded as
they are saved from Wing.  For more information on adding scripts to menus, see
`Adding Scripts to the GUI <ref:scripting/gui-contexts>`__.

Next, make an edit to the script that introduces an error into it. For example, change
``import wingapi`` to ``import wingapi2``. Save the script and Wing will show a clickable
traceback in the ``Scripts`` channel of the `Messages
<script:show_panel#panel_type="messages">`__ tool.

**Auto-Completion and Integrated Documentation**

With some additional configuration, it is possible to enable auto-completion,
~~~if WINGPRO:
auto-invocation, 
~~~
integrated documentation, and goto-definition for the scripting API. This is done as 
follows: 

**(1)** First create a new project from the ``Project`` menu with the default settings.

**(2)** Next locate the ``src`` directory inside the ``Install Directory`` shown in
Wing's `About box <script:about-application>`__. This is the directory that contains
``wingapi.py``.

**(3)** Finally, add the full path of the directory found in step (2) to the `Python Path
<script:view_project_properties#highlighted_attrib="proj.pypath">`__ in ``Project
Properties``.

Once this is done auto-completion in the editor, documentation in the `Source Assistant
<ref:edit/source-assistant>`__, and goto-definition should all work when you ``import
wingapi`` and work with its contents.
~~~if WINGPRO:
In Wing Pro, ``Find Uses`` and the auto-invocation `auto-editing
<ref:edit/auto-editing>`__ operation will also work for the API.
~~~

**Debugging Extension Scripts**

With some additional project setup, it is also possible to debug scripts using Wing. This
is a much richer way to develop extension scripts than clicking on tracebacks in the
``Messages`` tool.  See `Debugging Extension Scripts <ref:scripting/debugging>`__
for details.

**Other Example Scripts**

Wing ships with many other example scripts. These are in ``scripts`` inside the ``Install
Directory`` listed in Wing's `About box <script:about-application>`__. The most relevant
examples for simple scripting can be found in ``editor-extensions.py``. This shows how to
access and alter text in the current editor, among other things.

Other extensions scripts are available in ``scripts`` in the `contributed extensions
repository <https://github.com/wingware-dev/wing-contrib>`__.
