PowerPad Developer Center

Because the scripting engine in PowerPad has very few features and is still in its early stages, this brief tutorial will serve for now as the scripting engine's documentation.

Introduction

In order to develop scripts for PowerPad, it is necessary to know how the scripting engine works. For this reason, the tutorial will begin by describing the ins and outs of the engine.

PowerPad uses version 3.1 of the Python programming language to provide scripting capabilities. If you are familiar with Python, you will have no difficulty working with PowerPad scripts. If you are not familiar with Python, you can find the documentation here.

PowerPad stores its scripts in the current user's application-data directory. For example, on Windows Vista, the path to PowerPad's scripts would look like:

C:\Users\username\AppData\Roaming\PowerPad\Scripts\

It may take a bit of searching to find the script directory.

Once you have found the directory, you will find zero or more sub-folders that represent the scripts currently installed.

Creating the Script

The best way to illustrate development for the script engine is by example. Throughout this next section, I will demonstrate the process of script development by creating a simple example.

Begin by creating a folder inside the scripts folder. Give the folder the name of your script. For this example, we'll call our script NameAsker.

Inside the folder, create a script named pp_yourscriptname.py where yourscriptname is the name you gave the folder. In our example, this would be pp_NameAsker.py (make sure the capitalization is the same, or your script won't run on Linux versions of PowerPad).

Next, open the file and type the following:

# This line imports PowerPad's built-in
# module containing functions for interfacing
# with the current document.

import powerpad

def AskName():
    username = powerpad.Prompt("What is your name?")
    powerpad.DisplayMessage("Hello " + username + "!")
    return 1

def Init():
# Add the item to the menu
    powerpad.AddMenuItem("Ask my name",AskName)
    return 1

# These functions return informative
# information about the script
# and are used in the Script Manager
# dialog

def GetName():
    return "Ask My Name v1.1"

def GetAuthor():
    return "Your Name Here"

def GetDescription():
    return "Demonstrates use of the PowerPad script API."

The first line 'import powerpad' imports the PowerPad API into the script. This line is required.

The next few lines define 5 functions and their purpose is described below:

Function:	Description:
AskName	This is the function called when the user clicks on the 'Ask my name' menu item.
Init*	This function is called every time PowerPad starts up. Use this function to register menu items and perform any initialization necessary.
GetName*	This function should return a string with the name of the script.
GetAuthor*	This function should return a string with the author of the script.
GetDescription*	This function should return a string with the description of the script.

* denotes a required function

This is all that is required for this script to run. Simply start PowerPad and there should be a menu item with 'Ask my name' under the Scripts menu. Try clicking it to verify that the script runs as intended.

Functions Available

At this point, there are few functions from the PowerPad API available for the script to call. (Note that you can use any standard Python modules in your script, such as sys and os.) If your script requires a graphical user interface, tkinter can be used as it is bundled with the Windows version of PowerPad. The following describes the functions available currently:

DisplayMessage(string message)
        Displays a dialog box containing the text "message"
string Prompt(string message)
        Prompts the user for a string
string GetPowerPadVersion()
        Returns a string representation of the PowerPad version currently running the script
string GetOperatingSystem()
        Returns a string representation of the current operating system
SpeakText(string message)
        Speaks "message" out loud to the user on Windows; displays "message" in a dialog on Linux.
AddMenuItem(string title,callback_function)
        Adds "title" to the scripts menu. callback_function is the function called when the menu item is clicked.
GetDocumentText()
        Returns the contents of the document
SetDocumentText(string text)
        Sets the contents of the document
GetSelectionText()
        Returns the text of the current selection
SetSelectionText(string text)
        Sets the text of the current selection
GetSelection()
        Returns a tuple consisting of the starting and ending offset of the current selection
SetSelection(int start,int end)
        Sets the current selection to the range defined by start to end

Distributing Your Script

PowerPad has an online repository of scripts referred to as the "script database." You can browse and install scripts simply by going to the "Download Scripts" tab of the script manager within PowerPad. Plans are underway for an automated method of submitting scripts to the database. Until then, if you create a script that you would like to make available in the repository, simply email it to me at admin@quickmediasolutions.com. Also, please include an icon that can be used beside the listing for your script. (This is not required or even in use at the moment, but if you do not include one, a generic icon will be used in its place when needed.)

When you package your script, please do so as follows:

Create a zip file containing your script and any other files it needs. Make sure you do not nest folders inside the zip file as this will prevent PowerPad from being able to remove the script.
Send the zip file to the address above. All scripts submitted will be reviewed before approval.

Script Tutorial

Introduction

Creating the Script

Functions Available

Distributing Your Script