Modules

GJS includes some built-in modules, as well as helpers for some core APIs like DBus like Variants. The headings below are links to the JavaScript source, which are decently documented and informative of usage.

The Gio override includes a number of utilities for DBus that will be documented further at a later date. Below is a reasonable overview.

Gio.DBus.session, Gio.DBus.system

Convenience properties that wrap Gio.bus_get_sync() to return a DBus connection

Gio.DBusNodeInfo.new_for_xml(xmlString)

Return a new Gio.DBusNodeInfo for xmlString

Gio.DBusInterfaceInfo.new_for_xml(xmlString)

Return a new Gio.DBusInterfaceInfo for the first interface node of xmlString

Gio.DBusProxy.makeProxyWrapper(xmlString)

Returns a function(busConnection, busName, objectPath, asyncCallback, cancellable) which can be called to return a new Gio.DBusProxy for the first interface node of xmlString. See here for the original example.

Gio.DBusExportedObject.wrapJSObject(Gio.DbusInterfaceInfo, jsObj)

Takes jsObj, an object instance implementing the interface described by Gio.DbusInterfaceInfo, and returns an implementation object with these methods:

Mostly GtkBuilder/composite template implementation. May be useful as a reference.

REMINDER: You should specify a version prior to importing a library with multiple versions:

imports.gi.versions.Gtk="3.0";constGtk=imports.gi.Gtk;

Cairo

Import with const Cairo = imports.cairo;

Mostly API compatible with cairo, but using camelCase function names. There is list of constants in cairo.js and functions for each object in its corresponding C++ file (eg. cairo-context.cpp). A simple example drawing a 32x32 red circle:

imports.gi.versions.Gtk="3.0";constGtk=imports.gi.Gtk;constCairo=imports.cairo;letdrawingArea=newGtk.DrawingArea({height_request:32,width_request:32});drawingArea.connect("draw",(widget,cr)=>{// Cairo in GJS uses camelCase function namescr.setSourceRGB(1.0,0.0,0.0);cr.setOperator(Cairo.Operator.DEST_OVER);cr.arc(16,16,16,0,2*Math.PI);cr.fill();// currently when you connect to a draw signal you have to call// cr.$dispose() on the Cairo context or the memory will be leaked.cr.$dispose();returnfalse;});

Lang is a mostly obsolete library, that should only be used in cases where older versions of GJS must be supported. For example, Lang.bind() was necessary to bind this to the function context before the availability of arrow functions:

Mainloop is simply a layer of convenience and backwards-compatibility over some GLib functions (such as GLib.timeout_add() which in GJS is mapped to g_timeout_add_full()). It's use is not generally recommended anymore.

The System module offers a number of useful functions and properties for debugging and shell interaction (eg. ARGV):

addressOf(object)

Return the memory address of any object as a string in hexadecimal, e.g. 0xb4f170f0.
Caution, don't use this as a unique identifier!
JavaScript's garbage collector can move objects around in memory, or deduplicate identical objects, so this value may change during the execution of a program.

refcount(gobject)

Return the reference count of any GObject-derived type (almost any class from GTK, Clutter, GLib, Gio, etc.). When an object's reference count is zero, it is cleaned up and erased from memory.

breakpoint()

This is the real gem of the System module! It allows just the tiniest amount of decent debugging practice in GJS. Put System.breakpoint() in your code and run it under GDB like so:

gdb --args gjs my_program.js

When GJS reaches the breakpoint, it will stop executing and return you to the GDB prompt, where you can examine the stack or other things, or type cont to continue running. Note that if you run the program outside of GDB, it will abort at the breakpoint, so make sure to remove the breakpoint when you're done debugging.

gc()

Run the garbage collector.

exit(error_code)

This works the same as C's exit() function; exits the program, passing a certain error code to the shell. The shell expects the error code to be zero if there was no error, or non-zero (any value you please) to indicate an error. This value is used by other tools such as make; if make calls a program that returns a non-zero error code, then make aborts the build.

version

This property contains version information about GJS.

programInvocationName

This property contains the name of the script as it was invoked from the command line. In C and other languages, this information is contained in the first element of the platform's equivalent of argv, but GJS's ARGV only contains the subsequent command-line arguments, so ARGV[0] in GJS is the same as argv[1] in C.