blighty.gtk package

Module contents

This module provides support for creating GTK canvases. If you are trying to replicate conky’s behaviour then consider using the blighty.x11 submodule instead.

blighty.gtk.start_event_loop()

Start the main GTK event loop.

blighty.gtk.stop_event_loop()

Stop the main GTK event loop.

Submodules

blighty.gtk.canvas module

Description

This module provides the Canvas class for the creation of X11 canvases.

We advise that you consider using the Canvas class provided by the blighty.x11 submodule instead, as it gives more portability acrossdifferent display managers. The interface of blighty.gtk.canvas.Canvas is identical to that of blighty.x11.canvas.Canvas, so we refer you to the latter for more details of how to deal with GTK canvases. The key difference is basically in the class that your canvases have to extend. For example, if you have an X11-based canvas and you have the following import in your source code:

from blighty.x11 import Canvas, start_event_loop

all you have to do is replace blighty.x11 with blighty.gtk:

from blighty.gtk import Canvas, start_event_loop

and the same code will work just fine and will produce the same result.

Here is the same simple example from the blighty.x11 module, adapted to the GTK case:

from blighty import CanvasGravity
from blighty.gtk import Canvas, start_event_loop

class MyCanvas(Canvas):
    @staticmethod
    def build(x, y):
        return MyCanvas(x, y, 200, 200, gravity = CanvasGravity.NORTH)

    def on_button_pressed(self, button, state, x, y):
        if button == 1:  # Left mouse button pressed
            self.dispose()

    def on_draw(self, ctx):
        ctx.set_source_rgb(1, 0, 0)
        ctx.rectangle(0, 0, ctx.canvas.width >> 1, ctx.canvas.height >> 1)
        ctx.fill()

if __name__ == "__main__":
    # Instantiate the canvas
    canvas = MyCanvas.build()

    # Map it on screen
    canvas.show()

    # Start the event loop
    start_event_loop()

The only difference is on the second line, where we reference the blighty.gtk submodule instead of blighty.x11.

Extra features

There are some features that are unique to GTK canvases only. This implies that, if you have a GTK canvas and you use some of these features, you won’t be able to run the same code as an X11 canvas without changes.

Access the underlying GTK window

GTK canvases are special GTK windows that have been configured to be used as desktop widgets. Every instance of the blighty.gtk.canvas.Canvas class will expose the underlying GTKWindow via self.

Module API

class blighty.gtk.canvas.Canvas(x, y, width, height, interval=1000, screen=0, window_type=1, gravity=1, sticky=True, keep_below=True, skip_taskbar=True, skip_pager=True)

Bases: gi.overrides.Gtk.Window

GTK Canvas object.

This class is meant to be used as a superclass and should not be instantiated directly. Subclasses should implement the on_draw callback, which is invoked every time the canvas needs to be redrawn. Redraws happen at regular intervals in time, as specified by the interval attribute (also passed as an argument via the constructor).

dispose()

Dispose of the canvas.

For GTK-based canvases, this is equivalent to calling the destroy() method.

draw_grid(x=50, y=50)

Draw a grid on the canvas [implicit brush].

This implicit brush method is intended to help with determining the location of points on the canvas during development.

Parameters:

• x (int) – The horizontal spacing between lines.
• y (int) – The vertical spacing between lines.

move(x, y)

Move the canvas to new coordinates.

The x and y coordinates are relative to the canvas gravity.

on_draw(cr)

Draw callback.

Once the show() method is called on a Canvas object, this method gets called at regular intervals of time to perform the draw operation. Every subclass of Canvas must implement this method.

show()

Map the canvas to screen and set it ready for drawing.

write_text(x, y, text, align=3)

Write aligned text [explicit brush].

This explicit brush method helps write aligned text on the canvas. The x and y coordinates are relative to the specified alignment. By default, this is blighty.TextAlign.TOP_LEFT, meaning that the text will be left-aligned and on top of the horizontal line that passes through y on the vertical axis. In terms of the point (x,y) on the Canvas, the text will develop in the NE direction.

The return value is the text extents, in case that some further draw operations depend on the space required by the text to be drawn on the canvas.

Note that font face and size need to be set on the Cairo context prior to a call to this method.

Parameters:

• x (int) – The horizontal coordinate.
• y (int) – The vertical coordinate.
• text (str) – The text to write.
• align (int) – The text alignment. Detaulf is TextAlign.TOP_LEFT.

Returns:

The same return value as cairo.text_extents.

Return type:

tuple