

README: Symbolgroup
===================

This directory contains a plugin-object (symbolgroup.py) and some
support scripts (script.py, userhooks.py) that can be used to build a
simple symbol/object library. 

A symbolgroup is a special kind of group object that has a name and a
'layout point' that used when snapping to guides or the grid.

I wrote this plugin-object for a user who wanted to create a
symbol-library to make drawing electric circuits easier. The
implementatin here is not usable out of the box. You have to do some
manual tweaking and there's no sample symbol library yet. If you do
something with this code, please let me know.



Installation:
-------------

Put symbolgroup.py into a directory in the plugin_path. The plugin_path
is a list of directories where Sketch looks for plugins. A convenient
location for the file is ~/.sketch/Plugins. This directory is not
normally in the plugin_path so you have to add it in your
~/.sketch/userhooks.py file, e.g. like this:

import os
from Sketch import config
config.plugin_path.append(os.path.expanduser('~/.sketch/Plugins'))

If you don't have a userhooks file yet, you can start with the one in
this directory.


Usage:
------

The idea behind the symbolgroup when used for a symbol library is that
there is one .sk file containing one symbolgroup for every symbol. In
addition, there's a menu entry for each symbol in a submenu of the
Scripts menu. Since menus can be torn off, this is even quite usable for
small libraries.

To create a symbolgroup, start with an empty document. Draw the symbol
near the origin (the lower left corner of the page) so that the layout
point is the origin. Then select the objects and invoke
Edit/Create/Symbol Group. Type in the name for the group and save the
drawing into a suitable file. See gnd.sk for an example.

To use such a symbolgroup in a drawing, you have to install a script
like the one in scripts.py. The function insert_file reads a symbolgroup
from a file and lets you place it on the drawing. This function is
registered as a script for every symbol in the library under different
names and with different parameters. It should be quite obvious how to
modify it to suit your needs. A simple extension would be to scan a
directory automatically on startup.

How user scripts work and how they're installed is described in the
User's Guide.
