We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

The Tkinter 3000 WCK Drawing Interface

August 17, 2002 | Fredrik Lundh

The WCK C/C++ Drawing API

Somewhat ironically, the Tkinter WCK provides a C version of its drawing interface. This can be used by widgets that need to be partially implemented in C or C++ for performance reasons, or to be able to reuse an existing code base.

To get a handle to the C API, call the getcapi method on the drawing context. This returns a Python CObject, which contains a pointer to a WCKSimple2DAPI method table for the current device:

# mywidget.py

class MyWidget(Widget):
    def ui_handle_repair(self, draw, x0, y0, x1, y1):
        capi = draw.getcapi() # get handle to C API
        mymodule.repair(draw, capi)

...
/* mymodule.c */

#include "tk3000.h"

static PyObject*
mymodule_repair(PyObject* self, PyObject* args)
{
    WCKSimple2DAPI* api;

    PyObject* capi;
    PyObject* draw;
    if (!PyArg_ParseTuple(args, "OO:widget", &draw, &capi))
        return NULL;

    api = PyCObject_AsVoidPtr(capi);

    ...

    Py_INCREF(Py_None);
    return Py_None;
}

The methods in this table are described below:

The WCKSimple2DAPI Core Interface

The core interface includes a number of primitives that must be supported by all drivers.

api->getpen(). Create a pen object for use with this instance. The pen is returned as a PyObject, and should be treated as an opaque object by the application code. To release the pen, use Py_DECREF.

api->getbrush(). Create a brush object for use with this instance.

api->line(). Draw a line segment.

api->rectangle(). Draw a rectangle.

api->getfont(). Create a font object for use with this instance.

api->text(). Draw text using the given font. The reference coordinate is the left end of the baseline.

api->textsize(). Determine the size of a string if drawn on this device.

Declarations:

struct WCKSimple2DAPI {
  ...
  PyObject* getpen(PyObject* draw, int color, int width)
  PyObject* getbrush(PyObject* draw, int color, int style)
  int line(PyObject* draw, int x0, int y0, int x1, int y1,
           PyObject* pen)
  int rectangle(PyObject* draw, int x0, int y0, int x1, int y1,
                PyObject* pen, PyObject* brush)
  PyObject* getfont(PyObject* draw, int color, char* fontname)
  int text(PyObject* draw, int x0, int y0, char* text,
           int textsize, PyObject* font)
  int textsize(PyObject* draw, char* text, int textsize,
               PyObject* font, int* width, int* height)
  ...

The WCKSimple2DAPI Draw Extensions Interface

The extension interface provides additional methods.

api->pyline(). Draw a line segment, or a number of connected line segments.

api->pyrectangle(). Draw a rectangle.

api->pytext(). Draw text using the given font. The reference coordinate is the left end of the baseline.

api->pypolygon(). Draw a polygon.

api->pyellipse(). Draw an ellipse.

The WCKSimple2DAPI Pixmap Interface

api->getpixmap(). Create a pixmap object for use with this instance.

api->paste(). Copy pixmap to drawing target.

api->getimage(). Create a pixmap object for use with this instance, and copy an image object into it.