The WCK Module

The Widget Construction Kit (WCK) is an extension API that allows you to implement all sorts of custom widgets, in pure Python.

For more information on the Widget Construction Kit, see the WCK page over at effbot.org.

Using the WCK Module

To implement a new WCK widget, all you have to do is to subclass the Widget class, and implement one or more hook methods.

Here’s a very simple example. This widget displays the text “hello, world” in the upper left corner:

class HelloWorld(Widget):

    def ui_handle_repair(self, draw, x0, y0, x1, y1):
        font = self.ui_font("black", "times")
        draw.text((0, 0), "hello, world", font)

widget = HelloWorld(root)
widget.pack()

Widget hook methods:

ui_handle_clear is called to redraw the background.
ui_handle_config is called when the widget is (re)configured.
ui_handle_damage is called to indicate that some region needs to be redrawn. The widget should redraw itself in ui_handle_repair, not in this method.
ui_handle_destroy is called to release widget resources.
ui_handle_focus is called to redraw the focus indicator.
ui_handle_repair is called to redraw damaged regions.
ui_handle_resize is called when the widget’s geometry is changed.
ui_handle_select is called to handle cut buffers/selections.

All methods have default implementations, but you probably want to override at least ui_handle_repair in your widget.

Module Contents

ButtonController (class) [#]

Standard controller for the ButtonMixin class and other button-like widgets.

For more information about this class, see The ButtonController Class.

ButtonMixin (class) [#]

Button mixin.

For more information about this class, see The ButtonMixin Class.

ButtonWidget (class) [#]

Standard button widget base class.

For more information about this class, see The ButtonWidget Class.

Controller (class) [#]

Controller base class.

For more information about this class, see The Controller Class.

DrawInterface (class) [#]

Abstract 2D drawing interface.

For more information about this class, see The DrawInterface Class.

EventController (class) [#]

Standard controller for the EventMixin class.

For more information about this class, see The EventController Class.

EventMixin (class) [#]

Event mixin.

For more information about this class, see The EventMixin Class.

getcontroller(controller_factory, widget) [#]

Creates a controller for the given widget.

controller_factory: A controller factory or class (usually a subclass to Controller, or a compatible class).
widget: The widget to create a controller for.
Returns:: A controller instance. The controller is initialized, and has a valid tag attribute.

Observable (class) [#]

Standard observable mixin.

For more information about this class, see The Observable Class.

ScrollMixin (class) [#]

Scroll mixin.

For more information about this class, see The ScrollMixin Class.

SimpleWidget (class) [#]

Simple scrolled event-handling widget base class.

For more information about this class, see The SimpleWidget Class.

Style(widget) (class) [#]

Experimental style object.

For more information about this class, see The Style Class.

TextMixin (class) [#]

Text mixin.

For more information about this class, see The TextMixin Class.

Widget(master, **options) (class) [#]

The WCK widget base class.

For more information about this class, see The Widget Class.

The ButtonController Class

ButtonController (class) [#]: Standard controller for the ButtonMixin class and other button-like widgets.

The ButtonMixin Class

ButtonMixin (class) [#]

Button mixin. This mixin implements basic button widget behaviour (arm/click).

invoke() [#]

Called when the user presses the button, either by clicking the mouse button over the button, or by pressing the space bar.

The default implementation calls the object given by the command option, if callable.

ui_button_arm() [#]

Called when the mouse button is pressed with the mouse placed over the button.

ui_button_disarm() [#]

Called when the mouse button is released after the mouse has been moved out of the button.

ui_button_enter() [#]

Called when the mouse pointer is moved over the button.

ui_button_leave() [#]

Called when the mouse pointer is moved out from the button.

The ButtonWidget Class

ButtonWidget (class) [#]: Standard button widget base class. This widget inherits from ButtonMixin, and adds a relief option, which is changed to “sunken” whenever the button is armed.

The Controller Class

Controller (class) [#]

Controller base class. This class provides a standard implementation of the controller class. To implement a custom controller, create a subclass to this class and implement the create method.

attach(widget) [#]

(Hook) Called when this controller is attached to the given widget.

widget: The widget instance.

create(handle) [#]

Creates a controller. This method must be overridden by the implementation class.

handle: A binding function that takes an event specifier (a string) and an event handler (a function). The handler will be called with an event structure for all matching events.

detach(widget) [#]

(Hook) Called when this controller is detached from the given widget.

widget: The widget instance.

tag [#]

Binding tag for this controller.

ui_gettag(widget) [#]

(Internal) Calculate a unique binding tag for this controller instance.

The DrawInterface Class

DrawInterface (class) [#]

Abstract 2D drawing interface.

All WCK implementations provide a standard 2D drawing interface. By sticking to this interface, your widgets will work on all platforms supported by the WCK.

Note that different implementations use difference classes, and it isn’t always a class either. Make sure your widgets only relies on the interface provided by the drawing object, not the exact implementation.

circle(xy, pen, brush) [#]

(Experimental, not supported in WCK 1.0) Draws a circle.

xy: A bounding rectangle, given as a 4-element Python sequence (x, y, x, y), with the upper left corner given first. The circle is drawn centered in this box.
pen: Optional pen object created by ui_pen.
brush: Optional brush created by ui_brush.

crop(xy) [#]

Extracts a subrectangle from an image object or pixmap.

Example:

draw.paste(image.crop(source), dest)

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
Returns:: A new pixmap object. Note that this object is a reference to the original object, so changes to the original are reflected in the subrectangle.

ellipse(xy, pen, brush) [#]

Draws an ellipse.

xy: A bounding rectangle, given as a 4-element Python sequence (x, y, x, y), with the upper left corner given first. To draw a circle, make sure the coordinates form a square.
pen: Optional pen object created by ui_pen.
brush: Optional brush created by ui_brush.

line(xy, pen) [#]

Draws a line.

Examples:

# a cross
pen = widget.ui_pen(red)
draw.line((x0, y0, x1, y1), pen)
draw.line((x0, y1, x1, y0), pen)

# a character
draw.line((0, 0, 20, 100, 30, 50, 40, 100, 60, 0), pen)

xy: A Python sequence (x, y, x, y, …). If more than two coordinate pairs are given, they are connected in order, to form a polyline.
pen: A pen object created by the ui_pen factory method.

paste(image, xy=(0, 0)) [#]

Draws an image or pixmap object.

image: An image or pixmap object.
xy: A 2-element Python sequence (x, y). If omitted, the image is drawn in the upper left corner of the drawing area.

polygon(xy, pen, brush) [#]

Draws a polygon.

If a brush is given, it is used to fill the polygon. If a pen is given, it is used to draw an outline around the polygon. Either one (or both) can be left out.

xy: A Python sequence (x, y, x, y, …).
pen: Optional pen object created by ui_pen.
brush: Optional brush object created by ui_brush.

rectangle(xy, pen, brush) [#]

Draws a rectangle.

If a brush is given, it is used to fill the rectangle. If a pen is given, it is used to draw an outline around the rectangle. Either one (or both) can be left out.

xy: A 4-element Python sequence (x, y, x, y), with the upper left corner given first.
pen: Optional pen object created by ui_pen.
brush: Optional brush created by ui_brush.

settransform(transform) [#]

Sets the drawing transform. Note that the transform is reset before each call to ui_handle_repair.

Example:

draw.settransform((dx, dy))

transform: The new transform. In the current version, this must be a 2-tuple giving a horizontal and vertical offset.

text(xy, text, font) [#]

Draws text.

Draws a text string at the given position, using the given font.

Example:

font = widget.ui_font(black, times)
draw.text((100, 100), "hello, world", font)

xy: A 2-element Python sequence (x, y).
text: An 8-bit string containing ASCII text, or a Unicode string. Some implementations may attempt to interpret non-ASCII 8-bit strings as ISO-8859-1 or UTF-8; don’t rely on this feature if you can avoid it.
font: A font object created by the ui_font method.

textsize(text, font) [#]

Determines the size of a text string.

text: An 8-bit string containing ASCII text, or a Unicode string. Some implementations may attempt to interpret non-ASCII 8-bit strings as ISO-8859-1 or UTF-8; don’t rely on this feature if you can avoid it.
font: A font object created by the ui_font method.
Returns:: A (width, height) tuple.

The EventController Class

EventController (class) [#]: Standard controller for the EventMixin class.

The EventMixin Class

EventMixin (class) [#]

Event mixin. This mixin simplifies user event handling, by mapping mouse and keyboard events to DOM/DHTML-style method calls.

Note that this mixin overrides the ui_controller attribute.

onclick(event) [#]

Called for mouse clicks.

event: A button press event (ButtonPress). Use event.num to get the button number, event.x and event.y to get the mouse coordinate, relative to the parent widget.

onkey(event) [#]

Called for keyboard events.

event: A keyboard event (Key). Use event.char to get the character string, event.keysym to get the keyboard symbol, and event.keycode to get the key code.

onmousedown(event) [#]

Called for mouse button press events.

event: A button press event (ButtonPress). Use event.num to get the button number, event.x and event.y to get the mouse coordinate, relative to the parent widget.

onmousemove(event) [#]

Called for mouse motion events.

event: A motion event (Motion). Use event.x and event.y to get the mouse coordinate, relative to the parent widget.

onmouseout(event) [#]

Called for window leave events.

event: A leave event (Leave).

onmouseover(event) [#]

Called for window enter events.

event: An enter event (Enter).

onmouseup(event) [#]

Called for mouse button release events.

event: A button release event (ButtonRelease). Use event.num to get the button number, event.x and event.y to get the mouse coordinate, relative to the parent widget.

The Observable Class

Observable (class) [#]

Standard observable mixin. This mixin class can be used to make container objects (including widget models) “observable”.

addobserver(observer) [#]

Add an observer object to the container. The observer should be a callable object which takes two arguments (the event code and associated data).

observer: Observer object.

notify(event, data=None) [#]

Send the event and associated data to all observers. If an exception occurs in an observer, notification is aborted and the exception is propagated back to the caller.

event: Observer event.
data: Optional data associated with the event.

removeobserver(observer) [#]

Remove the given observer object from the container. The observer must exist.

observer: Observer object.

The ScrollMixin Class

ScrollMixin (class) [#]: Scroll mixin. This mixin implements vertical and horizontal scrolling.
ui_scroll_update() [#]: Update scrollbar.
ui_scroll_xinfo() [#]: Get total/left/right indexes.
ui_scroll_xset(left, units, pages) [#]: Set left margin to left + units + pages.
ui_scroll_yinfo() [#]: Get total/top/bottom indexes.
ui_scroll_yset(top, units, pages) [#]: Set top margin to left + units + pages.
xview(command, value, unit=None) [#]: Change the horizonal view.
yview(command, value, unit=None) [#]: Change the vertical view.

The SimpleWidget Class

SimpleWidget (class) [#]: Simple scrolled event-handling widget base class. This class inherits from ScrollMixin and EventMixin.

The Style Class

Style(widget) (class) [#]

Experimental style object.

drawbackground(xy, draw) [#]

Draws the widget background.

xy: Background extent.
draw: Drawing context. This is an object implementing the DrawInterface interface.

drawborder(xy, draw) [#]

Draws the widget border.

xy: Background extent.
draw: Drawing context. This is an object implementing the DrawInterface interface.

getmargin() [#]

Gets the margin width.

Returns:: The margin, in pixels.

The TextMixin Class

TextMixin (class) [#]

Text mixin. This mixin class maps foreground and font options to a font resource attribute, and handles width and height in character units.

To define what should be drawn, override the ui_text_get method.

ui_handle_config() [#]

Default config method. This implementation sets up the font attribute and the widget size, based on the mixin options. If you override this method, you must remember call the mixin version.

ui_handle_repair(draw, x0, y0, x1, y1) [#]

Default repair method. This implementation calls the ui_text_draw method.

ui_text_draw(draw, text=None) [#]

Draws centered text. The default implementation draws centered text, and uses the ui_text_get method to determine what to draw.

draw: Drawing context, as passed to ui_handle_repair.
text: Optional text. If omitted or None, this method calls the ui_text_get method to fetch the text.

ui_text_get() [#]

Get text to draw. This method is only called if ui_text_draw is called without a text argument.

Returns:: The string to draw.

The Widget Class

Widget(master, **options) (class) [#]

The WCK widget base class. This class implements a generic WCK widget, which should be subclassed to provide drawing and event handling behaviour.

__init__(master, **options) [#]

Creates a widget instance.

This method simply calls the ui_init method. If you need to initalize instance variables, you can override this method. You must remember to call ui_init when done (or if you prefer, call Widget.__init__).

master: The parent widget.
**options: Widget configuration options. You can use standard keyword options (listed below), or widget-specific extra options.
background=: The background colour.
relief=: The border style.
borderwidth=: The border width, in pixels.
highlightthickness=: The colour to use for a highlighted border.
cursor=: The cursor to use when the mouse pointer is moved in this widget.

__setitem__(option, value) [#]

Sets the value of a single configuration option.

option: What option to modify.
value: The new value for this option.

cget(option) [#]

Gets the value of a widget configuration option.

option: What option value to fetch.
Returns:: The option value.
Raises AttributeError:: The option was not supported.

config(**options) [#]

Configures a widget instance.

**options: One or more options, given as keyword arguments.

destroy() [#]

Destroys a widget instance.

keys() [#]

Gets a list of all available options.

Returns:: A list of option names.

manage(manager=”pack”, **options) [#]

(Experimental) Attach a geometry manager to this widget.

manager: What manager to use.
**options: Manager options, given as keyword arguments.

ui_brush(color=”black”, **options) [#]

Creates a brush object with the given characteristics. The brush can only be used in this widget.

color: What colour to use. This can be a colour name, a hexadecimal colour specifier (“#rrggbb”), or a packed integer (0xrrggbb).
**options: Additional options (device specific).

ui_controller [#]

(Class attribute) Standard event controller for this widget.

ui_damage(x0=None, y0=None, x1=None, y1=None) [#]

Reports widget damage. This will force the widget to redraw all or parts of it’s screen estate.

x0,y0,x1,y1: What region to redraw. If omitted, the entire widget will be redrawn.

ui_doublebuffer [#]

(Class attribute) Control double buffering for this widget. If set to a true value, the ui_handle_repair method will be set up to draw in an off-screen buffer, which is then copied to the screen in one step.

ui_draw [#]

(Instance attribute) (Experimental) Drawing context for this widget.

ui_font(color=”black”, font=”Courier”, **options) [#]

Creates a font object with the given characteristics, for use in this widget.

color

What colour to use. This can be a colour name, a hexadecimal colour specifier (“#rrggbb”), or a packed integer (0xrrggbb).

font

A font specifier. This should be a string with the following syntax: “{family} size style…”.

If the family name doesn’t contain whitespace, you can leave out the braces. If omitted, the family name defaults to courier.

The size is given in points (defined as 1/72 inch). If omitted, it defaults to 12 points. Note that the toolkit takes the logical screen size into account when calculating the actual font size. On low resolution screens, this means that a 12-point font is usually larger than 12/72 inches.

The style attributes can be any combination of normal, bold, roman (upright), italic, underline, and overstrike. If omitted, it defaults to the default setting for that family; usually normal roman.

For Tkinter compatibility, you can also give the font as a tuple: (“family”, size, style…). Note that there should be no braces around the family name. You can also leave out the size and/or the style arguments. The defaults are the same as for the string syntax.

Returns:

A font object.

ui_handle_clear(draw, x0, y0, x1, y1) [#]

(Hook) Called by the framework to clear a portion of this widget. The default implementations fills the background with the current background style. If you’re drawing the background in the repair method, you should override this method with an empty implementation.

draw: A drawing context. This is an object implementing the DrawInterface interface.
x0,y0,x1,y1: What region to clear. This region usually covers the entire widget.

ui_handle_config() [#]

(Hook) Called by the framework when this widget has been reconfigured. This method should check configuration options (ui_option attributes), and update widget attributes as necessary.

Returns:: A 2-tuple giving the width and height, in pixels, or None to preserve the current size. When the widget is first created, the current size is set to 100x100 pixels.

ui_handle_damage(x0, y0, x1, y1) [#]

(Hook) Called by the framework when some part of this widget has been damaged, and will have to be redrawn. This method will always be called at least once before each call to ui_handle_repair.

x0,y0,x1,y1: The damaged region.

ui_handle_destroy() [#]

(Hook) Called by the framework when this widget is about to be destroyed.

ui_handle_focus(draw, has_focus) [#]

(Hook) Called by the framework when this widget has received or is about to loose focus.

draw: A drawing context. This is an object implementing the DrawInterface interface.
has_focus: A true value if the widget has just received focus, a false value if it is about to loose focus.

ui_handle_repair(draw, x0, y0, x1, y1) [#]

(Hook) Called by the framework when this widget should be redrawn. This call will always be preceeded by one or more calls to ui_handle_damage, and a single call to ui_handle_clear.

draw: A drawing context. This is an object implementing the DrawInterface interface.
x0,y0,x1,y1: What region to redraw. This region usually covers the entire widget. To redraw only portions of the widget, override the ui_handle_damage method and keep track of the damaged region.

ui_handle_resize(width, height) [#]

(Hook) Called by the framework when this widget has been resized, either by a geometry manager, or by the user.

width: The new width, in pixels.
height: The new height, in pixels.

ui_handle_select() [#]

(Hook) Called by the framework when this selection status has changed. In the current implementation, this handler is never called.

ui_image(image=None, size=None, data=None, **options) [#]

Creates an image object with the given characteristics. The image (or a cropped subregion of it) can be pasted onto a a window or a pixmap.

Note that image descriptors are not cached.

Also note that in the current version, this method returns a pixmap. This may change in future versions.

image: The source image. This can be a PIL Image object, or a Tkinter BitmapImage or PhotoImage object. Alternatively, you can pass in a fromstring-style mode string, a size tuple, and a string containing the pixel data.
Returns:: An image object (currently a pixmap).

ui_init(master, options=None) [#]

Initializes a widget instance.

master: The parent widget.
options: A dictionary containing configuration options.

ui_option_background [#]

(Class attribute) Background color.

ui_option_borderwidth [#]

(Class attribute) Border width. If not zero, the border is decorated according to the relief setting.

ui_option_cursor [#]

(Class attribute) Cursor to use when the mouse is moved over this widget. If empty, the default cursor is used.

ui_option_highlightthickness [#]

(Class attribute) Focus region width.

ui_option_relief [#]

(Class attribute) Border relief.

ui_option_takefocus [#]

(Class attribute) Focus handling.

ui_path(xy) [#]

Converts a coordinate list to a more efficient representation. This method can be used to “compile” coordinate lists.

xy: Coordinate list.
Returns:: A path object. Note that this may be a reference to the input list, for WCK platforms that do no support path compilation.

ui_pen(color=”black”, width=1, **options) [#]

Creates a pen object with the given characteristics. The pen can only be used in this widget.

color: What colour to use. This can be a colour name, a hexadecimal colour specifier (“#rrggbb”), or a packed integer (0xrrggbb).
width: Pen width, in pixels.
**options: Additional options (device specific).

ui_pixmap(width, height, **options) [#]

Creates an pixmap object with the given characteristics.

width: The width of the pixmap, in pixels.
height: The height of the pixmap, in pixels.
**options: Additional options (device dependent).
Returns:: A pixmap object. This is an object implementing the DrawInterface interface.

ui_purge() [#]

Clears the resource cache. Clears the cache for this widget (and any other widgets that may share the same cache). Resources that are cached as instance attributes are not affected.

If this method is called from the constructor, before the ui_init is called, caching is disabled for this widget. Widgets that use large numbers of resources (e.g. font and colour browsers) should disable the cache.

ui_setcontroller(controller=None) [#]

Sets the controller for this widget.

controller: Controller class.
Returns:: Controller instance, or None.

ui_size() [#]

Gets the current size of this widget.

Returns:: The size in pixels, as a (width, height) 2-tuple.