<html>
<head>
<title>User's Guide: Introduction</title>
</head>
<body bgcolor=white text=black link=blue vlink=navy alink=red>
<TABLE WIDTH="100%">
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
<TR>
<TD ALIGN="left"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"><A HREF="usersguide-7.html">The Example Scripts</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Introduction</font></H2>
<H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Safe and Advanced Scripts</font></H3>
<P>As mentioned above user scripts in Sketch can cause data loss. To make
things easier for you in this regard, Sketch supports two kinds of
user scripts, <EM>safe scripts</EM> and <EM>advanced scripts</EM>.</P>
<P><A NAME="N3"></A>Safe scripts take care of undo handling for you
and they restrict what your script can actually do to keep you from
harm. The disadvantage of this approach is that you can't do everything
you might want to do with a safe script.</P>
<P><A NAME="N4"></A>The advanced script has no restrictions but
it has to take care of undo handling itself, which isn't difficult but
has to be done with care.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N5"></A>The Script Function</font></H3>
<P>Regardless of whether a script is a safe script or an advanced script it
is just a Python function that accepts a context object as parameter.
The context is an instance with three attributes:</P>
<P>
<DL>
<DT><B><CODE>document</CODE></B><DD>
<P>The document for which the script was called.</P>
<P>The document contains all objects that make up the drawing and
it manages the selection.</P>
<DT><B><CODE>application</CODE></B><DD>
<P>The application object.</P>
<P>The application object has methods for setting and retrieving
the application's clipboard and to pop-up message boxes and file
dialogs.</P>
<DT><B><CODE>main_window</CODE></B><DD>
<P>The top-level window containing the
canvas widget that shows the current drawing. It has methods for
loading and saving documents, among others.</P>
</DL>
</P>
<P>A simple 'hello world' type script might look like this:
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
def hello_world(context):
context.application.MessageBox(title = "My Script",
message = "Hello World!")
</PRE>
</td></tr></table>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N6"></A>Registering Scripts</font></H3>
<P>The <b>Script</b> menu just shows all the scripts in the <EM>script
registry</EM>, so to have a script appear in that menu, you have to put it
into the registry. </P>
<P>The registry is managed in a subpackage <CODE>Scripting</CODE> of the toplevel
package <CODE>Sketch</CODE>. The function needed here is <tt>AddFunction</tt> and is called like this:</P>
<P><CODE>AddFunction(<i>name</i>, <i>title</i>, <i>function</i>)</CODE></P>
<P>
<DL>
<DT><B><CODE><i>name</i></CODE></B><DD>
<P>is a name for that script. This name should be
unique, as the scripts are identified in the registry by this
name. It doesn't have to be the same as the function name.</P>
<DT><B><CODE><i>title</i></CODE></B><DD>
<P>The text of the menu entry.</P>
<DT><B><CODE><i>function</i></CODE></B><DD>
<P>the function that implements the
script, e.g. <CODE>hello_world</CODE> above.</P>
</DL>
</P>
<P>There are a few optional keyword arguments, one of which is <i>type</i>.
The value of <i>script_type</i> must be either <CODE>SafeScript</CODE> (the
default) or <CODE>AdvancedScript</CODE>. Both values are defined in the
<CODE>Scripting</CODE> subpackage. The registry functions are covered in more
detail in the <A HREF="usersguide-8.html">script registry section</A>.</P>
<P>As an example, registering the hello world script might look like this:
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
import Sketch.Scripting
Sketch.Scripting.AddFunction("hello_world", "Hello World", hello_world)
</PRE>
</td></tr></table>
</P>
<P>First we import the package <CODE>Sketch.Scripting</CODE> and then we call the
<CODE>AddFunction</CODE> function.</P>
<P>For more information about the organization of Sketch's code have a
look at the <A HREF="usersguide-9.html">API overview</A>.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N7"></A>The Startup Script</font></H3>
<P>The only thing left to do is to get some user supplied code to run on
startup, so it can define and register scripts. To do that just create a
file <tt>userhooks.py</tt> in the directory <tt>~/.sketch/</tt>. If such a
file exists it is automatically executed when Sketch starts. More
precisely, the directory <tt>~/.sketch/</tt> is inserted at the front of
Python's modules search path and a module <tt>userhooks.py</tt> is
imported.</P>
<P>You can put arbitrary code in there not just scripts, but one way to
implement and register our <CODE>hello_world</CODE> script would be a
<tt>userhooks.py</tt> file like this:</P>
<P>
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
# example for ~/.sketch/userhooks.py
def hello_world(context):
context.application.MessageBox(title = "My Script",
message = "Hello World!")
# register script
import Sketch.Scripting
Sketch.Scripting.AddFunction("hello_world", "Hello World", hello_world)
</PRE>
</td></tr></table>
</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"><A HREF="usersguide-7.html">The Example Scripts</A></TD>
</TR>
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
</TABLE>
</body>
</html>
