Welcome to GRX3’s documentation!

GRX3 is a graphics and input library for (Linux) embedded systems with small screens.

Features

• Can be used with many programming languages via GObject Introspection.
• Supported languages are Python, JavaScript (via gjs engine) and Vala.
• Works with monochome screens.
• Keyboard, mouse and touchscreen input.
• Also runs in a windowed desktop environment (useful for faster development).
• There is a (work-in-progress) widget toolkit for small screens.

Table of Contents

GRX3 Python Tutorial

The GRX3 Python bindings are based on PyGObject. So, if you have not already, you need to install the Python GObject Introspection module.

On Debian/Ubuntu:

sudo apt update
sudo apt install python3-gi

On macOS:

brew install pygobject3

Hello World!

The GRX3 library provides an Application class that is used for taking care of basic stuff for you. The following template can (and should) be used as the basis for any GRX3 Python program. Applications work by creating a main loop that dispatches events.

#!/usr/bin/env python3

# Importing GObject Introspection modules is a bit unusual because we have
# to specify a version in addition to a name. Technically, you can omit
# gi.require_version(), but you will get a warning.

import gi
gi.require_version('GLib', '2.0')
from gi.repository import GLib
gi.require_version('Grx', '3.0')
from gi.repository import Grx

# We are subclassing Grx.Application to provide our implementation
class HelloApp(Grx.Application):
    """A Hello World application"""
    def __init__(self):
        # the usual chaining up to the python superclass
        super(Grx.Application, self).__init__()
        # initialize the GRX graphics library
        self.init()
        # keep a hold on the application so that it does not close (this is
        # a feature of GLib.Application).
        self.hold()

    # GLib.Application requires that we implement (override) the activate
    # method.
    def do_activate(self):
        """called when the application starts
        overrides Grx.Application.do_activate
        """
        # fill the entire screen with white
        Grx.clear_screen(Grx.color_get_white())

        font = Grx.Font.load('fixed', 24)
        to = Grx.TextOptions.new(font, Grx.color_get_black())
        Grx.draw_text('Hello World!', 10, 10, to)

    # Handle input events from the GRX library. Returning True means that
    # the event was handled and that any additional signal handlers will
    # not be called.
    def do_event(self, event):
        """called when an input event occurs
        overrides Grx.Application.do_event
        """
        # Chain up to the superclass method. The superclass handles
        # application events (Grx.EventType.APP_*).
        if Grx.Application.do_event(self, event):
            return True

        # Exit the program on key press, mouse button click or touch
        if event.type in (Grx.EventType.KEY_DOWN, Grx.EventType.BUTTON_PRESS,
                          Grx.EventType.TOUCH_DOWN):
            self.quit()
            return True

        return False

if __name__ == '__main__':
    # This tells GLib what the name of your program will be, otherwise it
    # will be 'python3'.
    GLib.set_prgname('hello.py')
    # This is used by the desktop version of GRX3 to set the window title.
    GLib.set_application_name('GRX3 Hello World!')
    # Create a new instance of our class
    app = HelloApp()
    # Run the main loop
    app.run()

Additional Resources

• GRX3 Python API
• GRX3 Python examples
• PyGObject documentation
• PyGObject API Reference
• Objects section of Python GTK3 tutorial

GRX3 Javascript (gjs) Tutorial

In order to use GRX3 with Javascript, you need a Javascript engine called gjs. It is based on the Mozilla Spidermonkey engine (sorry for those hoping for node.js). If you haven’t already, you will need to install gjs.

On Debian/Ubuntu:

sudo apt update
sudo apt install gjs

On macOS:

brew install gjs

Hello World!

The GRX3 library provides an Application class that is used for taking care of basic stuff for you. The following template can (and should) be used as the basis for any GRX3 Javascript program. Applications work by creating a main loop that dispatches events. The gjs engine also provides some infrastructure for emulating OOP with Javascript.

#!/usr/bin/env gjs

"use strict";

const GLib = imports.gi.GLib;
const Grx = imports.gi.Grx;
const Lang = imports.lang;

// We are subclassing Grx.Application to provide our implementation
const HelloApp = new Lang.Class({
    Name: "HelloApp",
    Extends: Grx.Application,

    _init: function() {
        // chain up to the superclass constructor
        this.parent();
        // initialize the graphics library
        this.init(null);
        // keep the application from automatically closing
        this.hold();
    },

    // override the superclass activate method
    vfunc_activate: function() {
        Grx.clear_screen(Grx.color_get_white());
        const font = Grx.Font.load('fixed', 24)
        const to = Grx.TextOptions.new(font, Grx.color_get_black());
        Grx.draw_text('Hello World!', 10, 10, to);
    },

    // override the superclass event method
    vfunc_event: function(event) {
        // Chain up to the superclass event method. This handles application
        // events (Grx.EventType.APP_*).
        if (this.parent(event)) {
            return true;
        }

        // Quit the application on key press, button click or touch
        const event_type = event.get_event_type();
        if (this._quit_event_types.indexOf(event_type) >= 0) {
            this.quit();
            return true;
        }

        return false;
    },

    _quit_event_types: [Grx.EventType.KEY_DOWN, Grx.EventType.BUTTON_PRESS, Grx.EventType.TOUCH_DOWN]
});

// Set the program name, otherwise it will use 'gjs'
GLib.set_prgname('hello.js');
// In desktop applications, this will be the window title
GLib.set_application_name('GRX3 Hello World!');

// Create a new instance of our class
let app = new HelloApp();
// run the main loop
app.run(ARGV);

Additional Resources

• GRX3 Javascript API
• GRX3 Javascript examples
• Gjs documentation

GRX3 Vala Tutorial

Vala is a programming language that compiles to C, so it is a good choice when performance is an issue. If you have not already, you need to install the Vala compiler and the GRX3 development files.

On Debian/Ubuntu:

sudo apt update
sudo apt install libgrx-3.0-dev valac

On macOS:

brew install vala

Hello World!

The GRX3 library provides an Application class that is used for taking care of basic stuff for you. The following template can (and should) be used as the basis for any GRX3 Vala program. Applications work by creating a main loop that dispatches events.

using Grx;

class HelloApp : Grx.Application {
    public HelloApp () throws GLib.Error {
        // chain up to the parent class constructor
        Object ();
        // initialize the graphics library
        init ();
        // keep the application from automatically closing
        hold ();
    }

    public override void activate () {
        try {
            clear_screen (Color.WHITE);
            var font = Font.load ("fixed", 24);
            var to = new TextOptions (font, Color.BLACK);
            draw_text ("Hello World!", 10, 10, to);
        }
        catch (GLib.Error e) {
            // Font.load() can thow an exception
            critical ("%s", e.message);
        }
    }

    public override bool event (Event event) {
        // Chain up to the superclass method. The superclass handles
        // application events (EventType.APP_*).
        if (base.event (event)) {
            return true;
        }

        // Quit the application on any key press, button click or touch.
        switch (event.type) {
        case EventType.KEY_DOWN:
        case EventType.BUTTON_PRESS:
        case EventType.TOUCH_DOWN:
            quit ();
            break;
        default:
            return false;
        }

        return true;
    }
}

static int main (string [] argv) {
    // In desktop environments, this will be the window title
    Environment.set_application_name ("GRX3 Hello World");
    try {
        // create a new instance of our application
        var app = new HelloApp ();
        // run the main loop
        return app.run ();
    } catch (GLib.Error err) {
        critical ("%s", err.message);
        return 1;
    }
}

Additional Resources

TODO

API Documentation

The following API docs are available:

• C API
• JavaScript (Gjs) API
• Python API
• Vala API

Note

The C API docs are organized nicely and have additional notes, so even if you are using another programming language, you may find it useful to refer to the C API docs as well.