<html> <head> <title>Developer's Guide: Plugin Objects </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="devguide-23.html">Export Filters </A></TD> <TD ALIGN="center"><A HREF="devguide-20.html">Plugins </A></TD> <TD ALIGN="right"><A HREF="devguide-25.html">User Interface </A></TD> </TR> </TABLE> <HR NOSHADE> <H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Plugin Objects </font></H2> <P>Plugin objects provide a way to define new types of objects. Plugin objects can define how the user interacts with them and they can be saved to and loaded from sk files. The design of plugin objects takes the problem of loading files containing plugin objects that a particular Sketch installation doesn't know about into account.</P> <P>An example of a plugin object is the regular polygon object that comes with Sketch.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Design Philosophy</font></H3> <P>The idea behind plugin objects is that they're groups of builtin objects with some special attributes and behavior on top of that. </P> <P>What a plugin object looks like is completely defined by the children. This is the key to being able to load drawings with unknown plugin objects. Because the children are builtin objects Sketch can display and print them without problems by treating them more or less as ordinary groups.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N3"></A>Saving and Loading a Plugin Object</font></H3> <P>A plugin object is saved as a special compound object together with all its children. When Sketch reads an sk file with a plugin object that it doesn't know about it can still treat is like a normal group and since all drawing is done by the children it can still display and print it.</P> <P>Sketch is actually a bit smarter than that. It doesn't turn unknown plugin objects into normal groups, it turns them into an UnknownPlugin object that remembers which class the object belongs to and what parameters were used. As long as the object isn't changed it is saved as a plugin object again.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N4"></A>Configuration Variables</font></H3> <P>For plugin object configuration, Sketch uses the following variables: <DL> <DT><B><CODE>type</CODE></B><DD> <P>The type must be <CODE>PluginCompound</CODE>. This identifier is defined in the globals() dictionary.</P> <DT><B><A NAME="N5"></A> <CODE>class_name</CODE></B><DD> <P>A string containing the name of a Python class defined in the module. See below for the interface this class has to provide.</P> <P>Sketch uses the class_name to distinguish different plugin types and should therefore be unique. A future version of Sketch will probably use a different name for that purpose.</P> <DT><B><CODE>menu_text</CODE></B><DD> <P>The text to display in the menu as a string. In the 0.6.x, this text is used for the entry in the Edit->Create menu.</P> <DT><B><CODE>standard_messages</CODE> (optional)</B><DD> <P>A boolean indicating whether the messages in the plugin are standard messages that are defined in Sketch's message catalogs. For third-party plugins this should be omitted.</P> <DT><B><A NAME="N6"></A> <CODE>parameters</CODE> (optional)</B><DD> <P>A tuple of tuples describing the parameters of the object. This information is used to create a dialog that allows the user to set the parameters for new objects and modify those of existing objects.</P> <P>See below for more detail.</P> <DT><B><CODE>factory</CODE> (optional)</B><DD> <P>The name of a function that is to be called by the user interface code instead of the class to create a new object. The sk import filter always calls the class directly.</P> <DT><B><CODE>uses_selection</CODE> (optional)</B><DD> <P>If this boolean is true, the factory, if defined, or the class will be called with a list of objects as the only parameter. These objects are the ones currently selected.</P> <P>When omitted, it defaults to 0.</P> <DT><B><A NAME="N7"></A> <CODE>custom_dialog</CODE> (optional)</B><DD> <P>The name of a dialog class that is to be used instead of the dialog automatically built from the parameters information.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N8"></A>Implementation of a Plugin Object</font></H3> <P>Many plugin objects have some parameters that the user can set and modify and that have to be saved and read in again. </P> <P>For the user interface part, there are two mechanism to deal with parameters. They can either be defined by the <A HREF="#N6"><CODE>parameters</CODE></A> configuration variable in which case Sketch automatically builds a dialog from the description or the plugin can implement a custom dialog and tell Sketch to use it with the <A HREF="#N7"><CODE>custom_dialog</CODE></A> configuration variable.</P> <P>The <CODE>parameters</CODE> variable has to be sequence of pentuples each of which defines one parameter. The pentuple has the form</P> <P><CODE> (<i>name</i>, <i>type</i>, <i>default</i>, <i>range</i>, <i>label</i>)</CODE></P> <P>where <EM>label</EM> is text suitable for a label in the dialog box. <i>name</i> is the internal name for that property. The constructor of the plugin object must accept a keyword argument name. Also, the plugin object must have a method <i>Capname</i> to read the current value of that property and a method <tt>SetParameters</tt> accepting a dictionary of parameters and returning undo information. <i>Capname</i> is a `Capitalized' version of the lowercase name (if <i>name</i> is `the_parameter', <i>Capname</i> is `TheParameter')</P> <P><i>type</i> describes the type of the parameter, <i>default</i> is the initial value and <i>range</i> describes the valid values.</P> <P>Supported types:</P> <P> <TABLE> <TR> <TH>type</TH> <TH>range</TH> </TR> <TR> <TD VALIGN="top">int</TD> <TD VALIGN="top">(<i>MIN</i>, <i>MAX</i>)</TD> <TD VALIGN="top">the minimal and maximal value. <i>MIN</i> and/or <i>MAX</i> may be None indicating no limit (apart from the builtin limits).</TD> </TR> <TR> <TD>float</TD> <TD>(<i>MIN</i>, <i>MAX</i>)</TD> <TD>same as for int</TD> </TR> <TR> <TD>length</TD> <TD>(<i>MIN</i>, <i>MAX</i>)</TD> <TD>A length in pt. The user can change the unit.</TD> </TR> <TR> <TD>text</TD> <TD>ignored</TD> <TD>A text string (the range should be None for now)</TD> </TR> </TABLE> </P> <P>Saving of plugin objects works a little differently for sk-files than for other, non-native file formats.</P> <P>Export filters for non-native file formats treat plugin objects just like groups. That means you don't have to do anything special, but it also means that any extra information associated with the plugin-object will be lost.</P> <P>Saving to an sk-file is done by the <tt>SaveToFile</tt> method which is called with an <tt>SKSaver</tt> instance, customarily called <CODE>file</CODE>. <tt>SKSaver</tt> is defined by the sksvaver plugin. The plugin-object is expected to first call <CODE>file.BeginPluginCompound</CODE> with appropriate arguments, then to call each child's SaveToFile method with <CODE>file</CODE> as the only argument and finally <CODE>file.EndPluginCompound</CODE> with no arguments.</P> <P><CODE>BeginPluginCompound</CODE> has the following syntax: <DL> <DT><B><A NAME="N9"></A><tt>BeginPluginCompound(<i>plugin_name</i> [, <i>arg1</i>, ...] [, <i>kwarg1</i> = <i>value1</i>, ...])</tt></B><DD> <P>Start a plugin compound object in the sk file. <i>plugin_name</i> has to be the same as the configuration variable <A HREF="#N5">class_name</A>.</P> <P>All remaining arguments, whether positional or keyword arguments, should be builtin python types. They're written to the file as is. The keywords if used must be names of parameters if the configuration variable <A HREF="#N6">parameters</A> is used.</P> <P>When the file is read in again the plugin class is called with these arguments to create the instance.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N10"></A>The class <A NAME="N11"></A><tt>PluginCompound</tt></font></H3> <P>To make implementation easier, Sketch provides a base class for plugin objects. <tt>PluginCompound</tt> has a default implementation of <tt>SetParameters</tt> which assumes that the parameters are instance variables that have the same name as the parameters.</P> <P>Furthermore, it has an implementation of <tt>SaveToFile</tt> that has to be extended by the derived class. All the derived class has to do in its implementation of <tt>SaveToFile</tt> is to call the inherited method with the same arguments as the SKSaver method <A HREF="#N9"><tt>BeginPluginCompound</tt></A> except the class name. The class name is expected to be in a (class-)attribute called <CODE>class_name</CODE>.</P> <P>For examples see the regular polygon and the LCD-text objects in <tt>Plugin/Objects</tt>.</P> <HR NOSHADE> <TABLE WIDTH="100%"> <TR> <TD ALIGN="left"><A HREF="devguide-23.html">Export Filters </A></TD> <TD ALIGN="center"><A HREF="devguide-20.html">Plugins </A></TD> <TD ALIGN="right"><A HREF="devguide-25.html">User Interface </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>
