pyemf 2.0.0
01 January 2006
Copyright (c) 2005-2006 Rob McMullen (robm@users.sourceforge.net)

http://pyemf.sourceforge.net



ABSTRACT
========

pyemf is a pure python module that provides bindings for an ECMA-234
compliant vector graphics library.  ECMA-234 is the published
interface for the Windows GDI used in the Microsoft windows
environment and, more importantly, natively supported by the
OpenOffice suite of tools.

http://www.ecma-international.org/publications/standards/Ecma-234.htm



PREREQUISITES
=============

python (tested under 2.2, 2.3 and 2.4)



QUICK INSTALL
=============

python setup.py install

Yep, that's pretty much it, unless you have unpatched versions of
PyRTF or matplotlib.


Patch for PyRTF
---------------

If you have an unpatched version of PyRTF, you may apply the included
patch to provide EMF support.  You can either apply it to the source
distribution, or to the site libraries (where you might have to be
root).

$ cd PyRTF-0.45/PyRTF
$ patch -p0 < PyRTF-0.45-EMF-patch.diff
$ cd ..
$ python setup.py install

or

$ cd [path to python site-packages]/PyRTF
$ patch -p0 < PyRTF-0.45-EMF-patch.diff


Patch for matplotlib
--------------------

The included patch works against matplotlib 0.84 or 0.85; against
earlier versions you may need to edit matplotlib/__init__.py to add
'EMF':1 to the _knownBackends dict and edit
matplotlib/backends/__init__.py to add 'EMF' to the non_interactive_bk
list.  matplotlib/backends/backend_emf.py should be added in all
cases.

$ cd matplotlib-0.85/lib
$ patch -p0 < matplotlib-0.85-EMF-patch.diff
$ python setup.py install

or

$ cd [path to python site-packages]
$ patch -p0 < matplotlib-0.85-EMF-patch.diff




FEATURES
========

Most of the drawing methods of ECMA-234 are supported by pyemf.

Supported
---------

  Drawing parameters:
    GetStockObject, SelectObject, DeleteObject, CreatePen,
    CreateSolidBrush, CreateHatchBrush, SetBkColor, SetBkMode,
    SetPolyFillMode

  Drawing primitives:
    SetPixel, Polyline, Polygon, Rectangle, RoundRect, Ellipse, Arc,
    Chord, Pie, PolyBezier

  Path primitives:
    BeginPath, EndPath, MoveTo, LineTo, PolylineTo, ArcTo,
    PolyBezierTo, CloseFigure, FillPath, StrokePath, StrokeAndFillPath

  Clipping:
    SelectClipPath

  Text:
    CreateFont, SetTextAlign, SetTextColor, TextOut

  Coordinate system transformation:
    SaveDC, RestoreDC, SetWorldTransform, ModifyWorldTransform

Experimental
------------

  Window/Viewport commands:
    SetMapMode, SetViewportOrgEx, GetViewportOrgEx, SetViewportExtEx,
    ScaleViewportExtEx, GetViewportExtEx, SetWindowOrgEx,
    GetWindowOrgEx, SetWindowExtEx, ScaleWindowExtEx, GetWindowExtEx

Unsupported
-----------

  Palettes
  Bitmaps
  Text metrics



DOCUMENTATION
=============

The most current documentation is always available on the web at
http://pyemf.sourceforge.net/api/index.html

Or, in the source distribution, the directory website/api/ contains a
copy of the api documentation for version 2.0.0.  Simply point your
web browser at the index.html within that directory.



EXAMPLES
========

Creating an EMF
---------------

Here's a simple program (available as test-1.py in the distribution)
that connects opposite corners of an 8in by 6in rectangle with lines:

#!/usr/bin/env python

import pyemf

width=8
height=6
dpi=300

emf=pyemf.EMF(width,height,dpi)
thin=emf.CreatePen(pyemf.PS_SOLID,1,(0x01,0x02,0x03))
emf.SelectObject(thin)
emf.Polyline([(0,0),(width*dpi,height*dpi)])
emf.Polyline([(0,height*dpi),(width*dpi,0)])
emf.save("test-1.emf")


Examining an EMF
----------------

pyemf, when run as a standalone program, has the ability to read an
EMF and print out the contents.  Run:

$ pyemf.py -v test-1.emf

and it will print out a text summary of all the metafile records in
the file.


Other tests
-----------

There are many other tests included in the examples/ directory in the
source distribution.  After installing the pyemf library, you should
be able to run them like this:

$ cd examples
$ python test-drawing1.py

and examine the output file 'test-drawing1.emf' by loading it in
OpenOffice Impress.

Also included in the examples directory is the program
'test--run-all.py' that will run all the tests.




KNOWN ISSUES
============

See the website at http://pyemf.sourceforge.net/roadmap.html for more
information on the unsupported parts of the ECMA-234 standard.



DISCLAIMER
==========

pyemf, Copyright (c) 2005-2006 Rob McMullen (robm@users.sourceforge.net)

pyemf comes with ABSOLUTELY NO WARRANTY; for details see the
file COPYING included in the source distribution, or see the web site
http://www.gnu.org/copyleft/lesser.html for more information.