Scripting Example Tutorial
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. 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:
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 preference. For details on adding key bindings in Wing, see Key Bindings.
Editing the Script
In order to place your script in a new menu in the menu bar, add the following after the function definition:
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.
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 tool.
Auto-Completion and Integrated Documentation
With some additional configuration, it is possible to enable auto-completion, 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. 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 in Project Properties.
Once this is done auto-completion in the editor, documentation in the Source Assistant, and goto-definition should all work when you import wingapi and work with its contents. In Wing Pro, Find Uses and the auto-invocation 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 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. 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.
