<html> <head> <title>User's Guide: Sketch's API </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-8.html">The Script Registry </A></TD> <TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting </A></TD> <TD ALIGN="right"><A HREF="usersguide-10.html">Common Tasks</A></TD> </TR> </TABLE> <HR NOSHADE> <H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Sketch's API </font></H2> <P>If you want to write scripts for Sketch you have to know how to access the objects in the document and how to manipulate them. This section gives a brief introduction to the structure of Sketch's modules and objects from script author's point of view.</P> <P>A more detailed description of Sketch's internals can be found in the <A HREF="devguide.html">Developer's Guide</A>.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Module Structure</font></H3> <P>Sketch's code is organized in a hierarchy of packages. The top-level package that contains all of Sketch's core components is <CODE>Sketch</CODE>. It directly contains references to most of Sketch's graphics classes and functions.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N3"></A>Conventions</font></H3> <P>Sketch's objects have methods that are meant for public use and methods for internal purposes. Naturally, a script is expected to only use the public interface. Since Python has no builtin distinction between public and private/protected methods we have to rely on conventions. </P> <P>Sketch uses a naming convention for this. Methods with capitalized names, e.g. "<CODE>SetRadius</CODE>", are public methods and Methods with lowercase name, e.g. "<CODE>set_radius</CODE>", are protected.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N4"></A>Undo Handling</font></H3> <P>As pointed out above, advanced scripts have to deal with undo information. This isn't difficult, but you have to know which methods return undo information and what you have to do with it.</P> <P>You only have to deal with undo info if you modify an object that is part of a document. These objects include instances of classes derived from <A HREF="devguide-11.html#N2"><tt>GraphicsObject</tt></A> (<A HREF="devguide-10.html">class hierarchy</A>) and the objects that define the properties of a graphics object, like patterns.</P> <P>All methods that modify such an object return an undo info object. What this object looks like is irrelevant here, all you need to know for now is that you have to pass it immediately on to the document method <tt>AddUndo</tt>.</P> <P>A typical example: <table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0"> <PRE> context.document.AddUndo(object.Translate(offset)) </PRE> </td></tr></table> </P> <P>The <A HREF="devguide-11.html#N8"><tt>Translate</tt></A> method translates an object by <CODE>offset</CODE>, a <A HREF="devguide-5.html">point object</A> that stands for a 2D-vector.</P> <P>There are some exceptions to the rule that methods that modify the document return undo info. </P> <P>Firstly, the document methods that modify the selection, that is, that modify which objects are selected not the selected objects themselves, don't return undo info because changing the selection is not considered changing the document.</P> <P>Secondly, public document methods that modify the selected objects themselves already take care of undo info themselves. The reason for this is that they are called directly as a result of a menu command, button or key-press event.</P> <P>For more information about undo information in Sketch, have a look at the <A HREF="devguide-19.html">corresponding section</A> in the Developer's Guide.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N5"></A>Further Information</font></H3> <P>The example scripts in the <tt>Script</tt> directory contain extensive comments on what's going on.</P> <P>The <A HREF="devguide.html">Developer's Guide</A> covers Sketch's internals in more detail. Although it's incomplete it already contains a lot of information about the structure of Sketch's sources, the class hierarchy and some of the base classes, coordinate systems, plugins and more.</P> <P>And, of course: Use The Source, Luke!</P> <HR NOSHADE> <TABLE WIDTH="100%"> <TR> <TD ALIGN="left"><A HREF="usersguide-8.html">The Script Registry </A></TD> <TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting </A></TD> <TD ALIGN="right"><A HREF="usersguide-10.html">Common Tasks</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>
