\n
![\"Austin\"](\"art/logo.svg\"){kind=logo}
\n \n
\n Think of Conky, but with Python instead of Lua.
\n\n\n \n ![\"Travis](\"https://travis-ci.org/P403n1x87/blighty.svg?branch=master\"\n)
\n \n \n \n \n \n
![\"PyPI](\"https://badge.fury.io/py/blighty.svg\"){kind=icon}
\n \n \n \n \n
![\"Version](\"https://img.shields.io/badge/version-3.0.0%20(canaletto)-blue.svg\"\n){kind=icon}
\n \n ![\"source{d}](\"https://img.shields.io/badge/license-GPLv3-ff69b4.svg\"\n){kind=icon}
\n \n
\n ![](\"https://upload.wikimedia.org/wikipedia/commons/3/3a/Tux_Mono.svg\")
\n \n \n
\n Synopsis •\n Requirements •\n Installation •\n Usage\n
\n\n\n## Synopsis\n\nThe **Blighty** project is inspired by Conky. In essence, it is a collection of\nobjects that allow you to quickly create a transparent window that you can draw\non with cairo. But instead of coding your widgets in Lua, that perhaps end up\ncalling Python as external tools, you can now code them natively in Python.\n\nPerformance won't be as great as Conky, with probably more resource being used\nfor the same end result, but native Python support opens up for a lot more\ncustomisation possibilities in a snap of your fingers.\n\nThere won't be much you can do with minimal effort out of the box while the\nproject is in its infancy. If you like the idea, you are more than welcome to\ncontribute to this project!\n\n## Requirements\n\n- X11\n- Xinerama\n- cairo\n- python3\n- python3-gi (only for GTK Windows)\n- gir1.2-gtk-3.0 (only for GTK Windows)\n- gir1.2-glib-2.0 (only for GTK Windows)\n\n\n## Installation\n\nCurrently, Blighty needs to be built from its source code. The following\ninstallation instructions have been tested on Ubuntu 18.04. If you are using a\ndifferent distribution, make sure that you install all the listed dependencies\nfrom your package repository.\n\nTo install the required dependencies, use the following command\n\n~~~\nsudo apt install xorg libxinerama-dev libcairo2-dev python3-gi gir1.2-gtk-3.0 gir1.2-glib-2.0\n~~~\n\nTo install Blighty from PyPI, use the command\n\n~~~\nsudo -H python3 -m pip install blighty --upgrade\n~~~\n\nShould you encounter any problems installing Blighty from PyPI, then install it\ndirectly from GitHub with the following command.\n\n~~~\nsudo -H python3 -m pip install git+https://github.com/P403n1x87/blighty.git --upgrade\n~~~\n\n\n## Usage\n\nThe official documentation is hosted on\n[ReadTheDocs.io](https://blighty.readthedocs.io/en/latest/). Refer to the code\nin the `examples` folder for some simple examples.\n\nThis package makes it easy to create transparent windows that you can draw on\nwith `cairo`. It takes all the boilerplate code away from you so that you can\njust focus on the artwork, pretty much as with Conky.\n\n### X11 Canvases\n\nThis is the closest to Conky that you can get for the moment, and the\nrecommended way of using Blighty. Use the following approach to create a window\nwith the Xlib directly.\n\n~~~ python\nfrom blighty import CanvasGravity\nfrom blighty.x11 import Canvas, start_event_loop\n\nclass MyCanvas(Canvas):\n def on_draw(self, context):\n # context is an instance of a cairo context.\n # Refer to the Pycairo documentation.\n\nif __name__ == \"__main__\":\n x, y, width, height = 10, 10, 200, 200\n\n # Instantiate the canvas\n canvas = MyCanvas(10, 10, width = 200, height = 200, gravity = CanvasGravity.SOUTH_EAST)\n\n # Map it on screen\n canvas.show()\n\n # Start the event loop\n start_event_loop()\n~~~\n\nThe module implements a basic event loop so that the user interactions with the\ncanvas can be handled. You can capture key and button presses by implementing\nthe `on_key_pressed(self, keysym, state)` and `on_button_pressed(self, button,\nstate, x, y)` method in your subclass of `Canvas`.\n\n### GTK Canvases\n\nTo create GTK-based canvases you can use the `blighty.gtk.Canvas` class, which\nis just a subclass of `Gtk.Window`.\n\n~~~ python\nfrom time import sleep\nimport blighty.gtk as b\n\n\nclass MyCanvas(b.Canvas):\n def on_draw(self, widget, cr):\n # Similar to the X11 case. However, note how\n # you have access to the whole GTK window\n # via the `widget` parameter. In principle you\n # can exploit it to add extra child widgets.\n # Use wisely.\n\nif __name__ == \"__main__\":\n canvas = MyCanvas(0, 0, width=320, height=240)\n canvas.show_all()\n b.start_event_loop()\n~~~\n\n### Animations\n\nAnimations can be controlled via the `Canvas.interval` attribute. This is the\ntime in milliseconds that elapses between consecutive redraws of the Canvas.\n\n### Brushes\n\n_Since version 1.1.0_.\n\nConsider the following simple example of a clock widget.\n\n~~~ python\nfrom blighty import CanvasGravity\nfrom blighty.x11 import Canvas, start_event_loop\n\nimport datetime\n\nfrom math import pi as PI\n\n\nclass Clock(Canvas):\n def on_button_pressed(self, button, state, x, y):\n self.dispose()\n\n def hand(self, ctx, angle, length, thickness):\n ctx.save()\n ctx.set_source_rgba(1, 1, 1, 1)\n ctx.set_line_width(thickness)\n ctx.rotate(angle)\n ctx.move_to(0, length * .2)\n ctx.line_to(0, -length)\n ctx.stroke()\n ctx.restore()\n\n def on_draw(self, ctx):\n now = datetime.datetime.now()\n\n ctx.translate(self.width >> 1, self.height >> 1)\n\n self.hand(ctx,\n angle = now.second / 30 * PI,\n length = (self.height >> 1) * .9,\n thickness = 1\n )\n\n mins = now.minute + now.second / 60\n self.hand(ctx,\n angle = mins / 30 * PI,\n length = (self.height >> 1) * .8,\n thickness = 3\n )\n\n hours = (now.hour % 12) + mins / 60\n self.hand(ctx,\n angle = hours / 6 * PI,\n length = (self.height >> 1) * .5,\n thickness = 6\n )\n~~~\n\nIt is clear that the `hand` method would be more appropriate for the instance of\nthe cairo Context `ctx`. The coding would be simpler if we could call it as\n`ctx.hand`. _Brushes_ allow you to re-bind methods from the `Canvas` subclass to\nthe cairo context. Import the `brush` decorator from `blighty` with\n\n~~~ python\nfrom blighty import brush\n~~~\n\nand the use it to decorate the `hand` method. The `self` argument is no longer\nnecessary, since it will be replaced by the cairo context instance. So the above\ncode becomes\n\n~~~ python\nfrom blighty import CanvasGravity, brush\nfrom blighty.x11 import Canvas, start_event_loop\n\nimport datetime\n\nfrom math import pi as PI\n\n\nclass Clock(Canvas):\n def on_button_pressed(self, button, state, x, y):\n self.dispose()\n\n @brush\n def hand(ctx, angle, length, thickness):\n ctx.save()\n ctx.set_source_rgba(1, 1, 1, 1)\n ctx.set_line_width(thickness)\n ctx.rotate(angle)\n ctx.move_to(0, length * .2)\n ctx.line_to(0, -length)\n ctx.stroke()\n ctx.restore()\n\n def on_draw(self, ctx):\n now = datetime.datetime.now()\n\n ctx.translate(self.width >> 1, self.height >> 1)\n\n ctx.hand(\n angle = now.second / 30 * PI,\n length = (self.height >> 1) * .9,\n thickness = 1\n )\n\n mins = now.minute + now.second / 60\n ctx.hand(\n angle = mins / 30 * PI,\n length = (self.height >> 1) * .8,\n thickness = 3\n )\n\n hours = (now.hour % 12) + mins / 60\n ctx.hand(\n angle = hours / 6 * PI,\n length = (self.height >> 1) * .5,\n thickness = 6\n )\n~~~\n\nBy default, methods of subclasses of `Canvas` that begin with `draw_` are\nre-bound to the cairo context in the `on_draw` method. So the same as the above\ncode could be achieved without the use of the `brush` decorator with\n\n~~~ python\nfrom blighty import CanvasGravity\nfrom blighty.x11 import Canvas, start_event_loop\n\nimport datetime\n\nfrom math import pi as PI\n\n\nclass Clock(Canvas):\n def on_button_pressed(self, button, state, x, y):\n self.dispose()\n\n def draw_hand(ctx, angle, length, thickness):\n ctx.save()\n ctx.set_source_rgba(1, 1, 1, 1)\n ctx.set_line_width(thickness)\n ctx.rotate(angle)\n ctx.move_to(0, length * .2)\n ctx.line_to(0, -length)\n ctx.stroke()\n ctx.restore()\n\n def on_draw(self, ctx):\n now = datetime.datetime.now()\n\n ctx.translate(self.width >> 1, self.height >> 1)\n\n ctx.draw_hand(\n angle = now.second / 30 * PI,\n length = (self.height >> 1) * .9,\n thickness = 1\n )\n\n mins = now.minute + now.second / 60\n ctx.draw_hand(\n angle = mins / 30 * PI,\n length = (self.height >> 1) * .8,\n thickness = 3\n )\n\n hours = (now.hour % 12) + mins / 60\n ctx.draw_hand(\n angle = hours / 6 * PI,\n length = (self.height >> 1) * .5,\n thickness = 6\n )\n~~~\n\n_Brushes_ are implemented via the class `ExtendedContext`, which is just a\nwrapper around `cairo.Context`. The argument passed to the `on_draw` callback is\nhence an instance of this class. For convenience, it exposes the containing\ncanvas instance via the `canvas` attribute so that it doesn't need to be passed\nto the brush method when you need to access some of the canvas attributes (e.g.\nits size) or methods.\n\n\n## Conky-like Graphs\n\n_Since version 3.0.0_\n\nIf you really can't do without the Conky look, Blighty offers you Conky-like graphs out of the box.\n\n![](\"art/legacy-graph.gif\"/)