romgrk / node-gtk

GTK+ bindings for NodeJS (via GObject introspection)

node-gtk

GNOME Gtk+ bindings for NodeJS

Node-Gtk is a gobject-introspection library for nodejs. It makes it possible to use any introspected library, such as Gtk+, usable. It is similar in essence to GJS or PyGObject. Please note this project is currently in a beta state and is being developed. Any contributors willing to help will be welcomed.

Supported Node.js versions: 16, 18 (other versions should work but are untested)
Pre-built binaries available for: Linux, macOS (all supported versions except 18)

Table of contents

• Usage
• Documentation
• Installing and building
  • Target Platforms
  • Requirements
  • How to build on Ubuntu
  • How to build on Fedora
  • How to build on ArchLinux
  • How to build on macOS
  • How to build on Windows
  • Testing the project
    • Browser demo
• Contributing

Usage

Below is a minimal example of how to use the code, but take a look at our template or at react-gtk to bootstrap your project.

const gi = require('node-gtk')
const Gtk = gi.require('Gtk', '3.0')

gi.startLoop()
Gtk.init()

const win = new Gtk.Window()
win.on('destroy', () => Gtk.mainQuit())
win.on('delete-event', () => false)

win.setDefaultSize(200, 80)
win.add(new Gtk.Label({ label: 'Hello Gtk+' }))

win.showAll()
Gtk.main()

See our examples folder for more examples, and in particular the browser demo source for a more complex application.

Documentation

Read our documentation here

Installing and building

Note that prebuilt binaries are available for common systems, in those cases building is not necessary.

Target Platforms

• Linux: prebuilt binaries available
• macOS: prebuilt binaries available
• Windows: no prebuilt binaries

Requirements

• git
• nodejs@10 or higher
• python3 (for node-gyp)
• C compiler (gcc@8 or higher, or clang)

How to build on Ubuntu

Install basic dependencies.

sudo apt-get install \
  build-essential git \
  gobject-introspection \
  libgirepository1.0-dev \
  libcairo2 \
  libcairo2-dev

At this point npm install node-gtk should already install, fallback and build node-gtk without problems.

How to build on Fedora

Install basic dependencies:

sudo dnf install \
  @development-tools \
  nodejs \
  gobject-introspection \
  gtk3 \
  cairo

After installing of packages, run npm install node-gtk.

How to build on ArchLinux

The following should be the bare minimum to be able to build the project.

pacman -S --needed \
  base-devel git \
  nodejs npm \
  gtk3 gobject-introspection \
  cairo

Feel free to install all base-devel utilities.

After installing those packages, npm install node-gtk would do.

How to build on macOS

Assuming you have brew installed, the following has been successfully tested on El Captain.

brew install git node gobject-introspection gtk+3 cairo

At this point npm install node-gtk should already install, fallback and build node-gtk without problems.

How to build on Windows

Mandatory dependency is Visual C++ Build Environment: Visual Studio Build Tools (using "Visual C++ build tools" workload) or Visual Studio Community (using the "Desktop development with C++" workload).

The easiest/tested way to build this repository is within a MinGW shell provided by the MSYS2 installer.

Once VS and its C++ compiler is available and MSYS2 installed, launch the MinGW shell.

# update the system
# in case of errors, wait for the update to complete
# then close and open again MingW shell
pacman -Syyu --noconfirm

# install git, gtk3 and extra dependencie
pacman -S --needed --noconfirm git mingw-w64-$(uname -m)-{gtk3,gobject-introspection,pkg-config,cairo}

# where to put the repository clone?
# pick your flder or use ~/oss (Open Source Software)
mkdir -p ~/oss/
cd ~/oss

# clone node-gtk there
git clone https://github.com/romgrk/node-gtk
cd node-gtk

# don't include /mingw64/include directly since it conflicts with
# Windows SDK headers. we copy needed headers to __extra__ directory:
./windows/mingw_include_extra.sh

# if MSYS2 is NOT installed in C:/msys64 run:
export MINGW_WINDOWS_PATH=$(./windows/mingw_windows_path.sh)

# first run might take a while
GYP_MSVS_VERSION=2017 npm install

The GYP_MSVS_VERSION could be 2017 or above. Please verify which version you should use

The below blog post series will help you get started:

1. Node.js GTK Hello World on Windows
2. Find DLLs and Typelibs dependencies for Node.js GTK Application on Windows
3. Package Node.js GTK Application on Windows

Possible issue on MinGW shell

In case you are launching the general executable without knowing the correct platform, the binary path might not be available.

In such case python won't be available either, and you can check via which python command.

If not found, you need to export the platform related binary path:

# example for the 32bit version
export PATH="/mingw32/bin:$PATH"
npm run install

This should do the trick. You can also check if there is any python at all via pacman -Qs python.

Testing the project

If you'd like to test everything builds and work properly, after installing and building you can run any of the examples:

node ./examples/hello-gtk.js

If you'll see a little window saying hello that's it: it works!

Please note in macOS the window doesn't automatically open above other windows. Try Cmd + Tab if you don't see it.

Browser demo

If you'd like to test ./examples/browser.js you'll need WebKit2 GTK+ libary.

• in Ubuntu, you can apt-get install libwebkit2gtk-3.0 (4.0 works too) and try it out.
• in Fedora, you should run sudo dnf install webkit2gtk3
• in ArchLinux, you can pacman -S --needed webkitgtk and try it out.
• in macOS, there is no way to run it right now because webkitgtk was removed from homebrew

Once installed, you can ./examples/browser.js google.com or any other page, and you might try the dark theme out too:

# macOS needs to have the Adwaita theme installed
# brew install adwaita-icon-theme

# Usage: ./examples/browser.js <url> [theme]
./examples/browser.js  google.com  dark

Contributing

If you'd like to help, we'd be more than happy to have support. To setup your development environment, you can run npm run configure. You can then build the project with npm run build.

• https://developer.gnome.org/gi/stable/index.html
• https://v8docs.nodesource.com/
• https://github.com/nodejs/nan#api

Don't hesitate to join our Discord channel.

Contributors

• magcius
• WebReflection
• romgrk
• wotzlaff

node-gtk's Issues

Add tests

• List the features that need testing
• function call: multiple return values
• function call: inout parameters
• conversion: c-array, GArray, GByteArray, GPtrArray
• conversion: GList, GSList
• conversion: GHashTable
• conversion: enum, flag
• conversion: Object
• conversion: boxed
• property: get/set
• fields: get/set
• GObject: events
• ParamSpec

Attract maintainers

In order to have higher quality bindings, we need to put more work into this. More maintainers means more work. Therefore, we need to find more maintainers. (also, our bus factor is very bad)
The general strategy will be to generate noise about the project in order to get more popularity. More people seeing the project means more potential maintainers.

• Find which kind of people are interested in having Gtk NodeJS bindings (besides me)
• Add pre-built binaries for easy installation
• Blog entries about the project (Medium?)
• Short release cycle on NPM, to show there is activity

Support class extends

class CustomWindow extends Gtk.Window { 
  constructor() {
    super();
  }
}

Support V8 Array to C array conversion

Pass https://github.com/romgrk/node-gtk/blob/master/tests/function_call__inout.js

Optimization: cache call_parameters on function call

Boxed: preserve identity when GType is none

Some boxeds don't have a GType apparently, for example GdkEventKey. Thus whenever we create one of those, we recreate a new FunctionTemplate.

Ping @Place1, I think this should also affect you. Have you ever had problems with some structs having no GType? Have you ever noticed something like this?

assertion object != null failed

const gi = require('node-gtk');
const Pango = gi.require('Pango');

var attrs = new Pango.AttrList();
attrs.insert(new Pango.AttrSize(300));

error: Pango-CRITICAL **: pango_attr_list_insert: assertion 'list != NULL' failed

Signals: re-throw exceptions in handlers

Pass tests/object__signal__throws.js

Document and standardize naming conventions

• Make namespace level functions camelCase
• Document naming conventions

Struct: initialize from object on creation

const c = new Gdk.Color({ blue: 77 })
// => c.blue === 77

Optimization: cache interface templates

Start up time has increased since adding support for interfaces. Need to be mindful of the load order.

Support G(S)Lists in GIArgumentToV8

When tag == GI_TYPE_TAG_GSLIST.

• Handle case GI_TRANSFER_CONTAINER
• Check if there are cases with GI_TRANSFER_EVERYTHING
• Check if element type can vary (the fact that we can query for the type of each element suggests that they can.)

Errors in signal callbacks are swallowed

Function call: find GI_DIRECTION_INOUT parameter example

And assert that everything works

Core dump when method is called with invalid type

https://github.com/romgrk/node-gtk/blob/master/tests/method_call__invalid_type.js

Support interfaces

• find how interface are used in GLib
• implement interfaces
• add tests
• pass tests

keeping same npm name

I'm seeing a lot of effort going on in here, I wouldn't mind giving you the rights to publish in npm as node-gtk package neither.

any interest ? or were you planing to massively PR my repo after ?

Support unions

In lib/index.js :: makeInfo, when type == GI_INFO_TYPE_STRUCT or type == GI_INFO_TYPE_UNION.

Support signal annotations

Some arguments of signal handlers are not relevant outside C. GISignalInfo contains annotations to keep only relevant parameters (e.g. https://developer.gnome.org/gtk3/stable/GtkWidget.html#GtkWidget-key-press-event)

Support multiple return values

Function calls have a return-value, but they also have C-style out-parameters.
out-parameters can also allow-none. And some parameters might be skippable.

https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Annotations/Examples#A.27out.27_parameters

Boxed: fix issue causing critical warnings

(process:10823): GLib-GObject-CRITICAL **: g_boxed_free: assertion 'G_TYPE_IS_BOXED (boxed_type)' failed

At https://github.com/romgrk/node-gtk/blob/master/src/boxed.cc#L149

Related to this: https://github.com/romgrk/node-gtk/blob/master/src/boxed.cc#L97-L114

Related to #10

Make node-pre-gyp work

Closure::Marshal is receiving GValue with invalid g_type

Steps:

• node example/browser.js
• change the URL + Enter

Arrays: Type checking on function call

Check types more strictly. (Note to self: do not try to support messy JS conversions; be strict)

> gtk.init(0, null)

(process:11805): GLib-CRITICAL **: g_array_free: assertion 'array' failed
**
ERROR:../src/function.cc:31:int GNodeJS::GetV8ArrayLength(v8::Local<v8::Value>): code should not be reached
[1]    11805 abort (core dumped)  node

debug.h missing

Hi, tried to test your fork after this discussion but can't build it, seems like some files are missing? Right now it can't find debug.h, which doesn't seem to have been added to the repo.

Support interface conversion in GIArgumentToV8

support node 10.4

Generate typescript definitions & documentation for common GIR libraries

Fix license issues

Some functions are copied from PyGObject, which is LGPL, incompatible with our license. We need to remove those.

Automate node-pre-gyp publication

https://github.com/mapbox/node-pre-gyp#travis-automation

GUI doesn't show up

I'm trying the lib out with the simple example:

const gi = require("node-gtk");
const Gtk = gi.require("Gtk", "3.0");

gi.startLoop();
Gtk.init();

const win = new Gtk.Window();
win.on("destroy", () => Gtk.mainQuit());
win.on("delete-event", () => false);

win.setDefaultSize(200, 80);
win.add(new Gtk.Label({ label: "Hello Gtk+" }));

win.showAll();

When running the script with node ., it closes after a second, without showing any window/ui.

Am I missing something?

Update readme and publish npm minor version

• Update readme
• Switch package.json repository to point here
• Publish minor release with latest features

Fix memory leaks

In FreeGIArgument:

• GList/GSList
• IN-arguments when GI_TRANSFER_NOTHING
• IN-arrays
• OUT-arrays
• INOUT-arrays

Others:

• check BoxedDestroyed()

Inspiration: https://gitlab.gnome.org/GNOME/pygobject/blob/master/gi/pygi-argument.c#L1006

InitGParameterFromProperty: throw when property has invalid type

Throw an error (instead of dumping) when a property is initialized with an invalid type.

const gi = require('../lib/')
const Soup = gi.require('Soup')

const message = new Soup.Message({
  method: 'GET',
  uri: 'http://google.com', // invalid type, should be SoupURI
})

Support GArrays in GIArgumentToV8

When tag == GI_TYPE_TAG_ARRAY.

• find all cases that must be supported
• add tests

Support GParameterSpec

Implement Gtk/Gdk overrides to expose a nice API

We need to implement overrides on the JS side to expose a nice API for users. One such example is described here: #4 (comment)

Off the top of my head, the things that need to be overriden are:

• Multiple return values are returned as arrays [retval, out1, out2, ...]
  • Strip boolean return values that indicate failure (example)
  • Return objects when it's nicer to do so (as described in the issue #4 comment)

For more inspiration, look at https://gitlab.gnome.org/GNOME/pygobject/blob/master/gi/overrides/Gtk.py.
The file in which those overrides would be (for Gtk-3.0) is https://github.com/romgrk/node-gtk/blob/master/lib/overrides/Gtk-3.0.js.

ping @WebReflection

Core dump when using Gtk without having called Gtk.init()

We should find a way to warn the user that gi.startLoop() and Gtk.init() must be called before using Gtk elements.

V8ToGValue: support conversion to flags, pointer & variant

Support GType in GIArgumentToV8

GI_TYPE_TAG_GTYPE

Allow preventing signals

g_signal_stop_emission

Use Node's EventEmitter semantics

Bindings should integrate smoothly with target language, therefore:

EventEmitter#on <--> GObject#connect

Maybe even inherit from EventEmitter?

Signals: make sure "notify::<prop>" works

Reference: Place1/node-gir@109efbd

Support callback arguments

Pass tests/conversion__callback.js

• https://github.com/GNOME/gjs/blob/57d562d0cd4c4bae0748fbd5fc7ead9c64d41a8b/gi/function.cpp#L494
• https://github.com/GNOME/gjs/blob/57d562d0cd4c4bae0748fbd5fc7ead9c64d41a8b/gi/function.cpp#L939

Release 1.0

Technical stuff:

• Signals #45
• Overrides #31

Non-technical stuff:

• list supported nodejs versions
• list supported platforms
• update package.json
• Add tests #14
• License issues #34
• Make node-pre-gyp work #46

CI

Personally, i prefer circleci, but travis is fine too

Optimization: cache boxed constructor

Handle failures in V8ToGIArgument for container types

Core dump in examples/editor.js

const gi = require('../');
const Gtk = gi.require('Gtk');
const GtkSource = gi.require('GtkSource', '3.0')
const common = require('./__common__.js')

Gtk.init()

const textView = new GtkSource.View()
const buffer = textView.getBuffer()

buffer.placeCursor(buffer.getEndIter())

Output:

[1]    20786 segmentation fault  rr record -n node tests/gtk_text_buffer_place_cursor.js

Boxed: use constructor function when size is zero

const gi = require('node-gtk');
const Gtk = gi.require('Gtk');
const Pango = gi.require('Pango');

Gtk.init();

var label = new Gtk.Label({ label: 0 });
var attrs = new Pango.AttrList();
attrs.insert(new Pango.AttrSize(300));
label.attributes = attrs;