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 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:
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.