node-gtk 1.0.0 → 2.0.0

package/README.md

@@ -16,7 +16,7 @@
 </p>
 
 Node-Gtk is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library for nodejs. It makes it possible to
-use any introspected library, such as Gtk+, usable.  It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) or [PyGObject](https://pygobject.readthedocs.io). Please note this project is currently in a _beta_ state and is being developed. Any contributors willing to help
+use any introspected library, such as Gtk+, usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) or [PyGObject](https://pygobject.readthedocs.io). 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: **20**, **22**, **24** (other versions may work but are untested)<br>
@@ -26,232 +26,123 @@ Pre-built binaries available for: **Linux**, **macOS**
 
 - [Usage](#usage)
 - [Documentation](#documentation)
+- [TypeScript](#typescript)
 - [Installing and building](#installing-and-building)
-  - [Target Platforms](#target-platforms)
-  - [Requirements](#requirements)
-  - [How to build on Ubuntu](#how-to-build-on-ubuntu)
-  - [How to build on Fedora](#how-to-build-on-fedora)
-  - [How to build on ArchLinux](#how-to-build-on-archlinux)
-  - [How to build on macOS](#how-to-build-on-macos)
-  - [How to build on Windows](#how-to-build-on-windows)
-  - [Testing the project](#testing-the-project)
-    - [Browser demo](#browser-demo)
 - [Contributing](#contributing)
 
 ## Usage
 
-Below is a minimal example of how to use the code, but take a look at
-our [template](https://github.com/romgrk/node-gtk-template) or at
-[react-gtk](https://github.com/codejamninja/react-gtk) to bootstrap your
-project.
+Below is a [minimal example](./examples/hello-world.js) of how to use node-gtk:
 
 ```javascript
-const gi = require('node-gtk')
-const Gtk = gi.require('Gtk', '3.0')
-
-gi.startLoop()
-Gtk.init()
+const gi = require('node-gtk');
+const GLib = gi.require('GLib', '2.0');
+const Gtk = gi.require('Gtk', '4.0');
+const Adw = gi.require('Adw', '1');
+
+const loop = GLib.MainLoop.new(null, false);
+const app = new Adw.Application('com.github.romgrk.node-gtk.hello', 0);
+
+app.on('activate', () => {
+  const content = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL });
+  content.append(new Adw.HeaderBar());
+  content.append(new Gtk.Label({ label: 'Hello Adwaita!', vexpand: true }));
+
+  const window = new Adw.ApplicationWindow(app);
+  window.setTitle('node-gtk');
+  window.setDefaultSize(300, 120);
+  window.setContent(content);
+  window.on('close-request', () => (loop.quit(), app.quit(), false));
+  window.present();
+
+  gi.startLoop();
+  loop.run();
+});
+
+process.exit(app.run([]));
+```
 
-const win = new Gtk.Window()
-win.on('destroy', () => Gtk.mainQuit())
-win.on('delete-event', () => false)
+<p align="center">
+  <img src="./img/hello-world.png" style="width: 290px; height: auto;"/>
+</p>
 
-win.setDefaultSize(200, 80)
-win.add(new Gtk.Label({ label: 'Hello Gtk+' }))
+You can also easily create custom applications:
 
-win.showAll()
-Gtk.main()
-```
+[A web browser (using WebKit2GTK)](./examples/browser.js)
 
 <p align="center">
-  <img src="./img/hello-node-gtk.png" alt="Hello Gtk" style="width: 220px; height: auto;"/>
+  <img src="./img/browser.png" style="max-width: 500px; height: auto;"/>
 </p>
 
-See our [examples](./examples) folder for more examples, and in particular the
-[browser demo source](https://github.com/romgrk/node-gtk/blob/master/examples/browser.js) for
-a more complex application.
+[A system monitor](./examples/system-monitor.js)
 
 <p align="center">
-  <img src="./img/browser.png" alt="Hello Gtk" style="max-width: 500px; height: auto;"/>
+  <img src="./img/system-monitor.png" style="width: 400px; height: auto;"/>
 </p>
 
+#### Other projects
+
+The [react-gtk](https://github.com/codejamninja/react-gtk) project may also allow you to use GTK via React (unmaintained).
 
 ## Documentation
 
 [Read our documentation here](./doc/index.md)
 
-## Installing and building
-
-Note that prebuilt binaries are available for common systems, in those cases building is not necessary.
+## TypeScript
 
-##### 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.
+node-gtk can generate TypeScript declarations for the libraries you use,
+straight from the GObject-Introspection typelibs installed on your machine — so
+the types always match your actual library versions and node-gtk's own runtime
+shape (camelCase methods, signal callbacks, nullability, etc.).
 
 ```sh
-sudo apt-get install \
-  build-essential git \
-  gobject-introspection \
-  libgirepository1.0-dev \
-  libcairo2 \
-  libcairo2-dev
+# generates ./node_modules/.node-gtk-types (a hidden, git-ignored cache)
+npx node-gtk generate-types Gtk-4.0 Adw-1
 ```
 
-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:
+The command emits one declaration file per namespace (plus the full dependency
+closure) and a `node-gtk.d.ts` shim. Point your `tsconfig.json` at it:
 
-```sh
-sudo dnf install \
-  @development-tools \
-  nodejs \
-  nodejs-devel \
-  gobject-introspection \
-  gobject-introspection-devel \
-  gtk3 \
-  gtk3-devel \
-  cairo \
-  cairo-devel
+```jsonc
+{
+  "compilerOptions": {
+    "moduleResolution": "node16",
+    "paths": { "node-gtk": ["./node_modules/.node-gtk-types/node-gtk.d.ts"] }
+  }
+}
 ```
 
-After installing of packages, run `npm install node-gtk`.
-
-### How to build on ArchLinux
+Then `gi.require` is fully typed — the namespace is inferred from the string
+arguments:
 
-The following should be the bare minimum to be able to build the project.
+```ts
+import * as gi from 'node-gtk'
 
-```sh
-pacman -S --needed \
-  base-devel git \
-  nodejs npm \
-  gtk3 gobject-introspection \
-  cairo
+const Gtk = gi.require('Gtk', '4.0')   // typed as the Gtk-4.0 namespace
+const win = new Gtk.ApplicationWindow({ title: 'Hello', defaultWidth: 400 })
+win.on('close-request', () => false)   // signal name + callback are typed
 ```
 
-Feel free to install all `base-devel` utilities.
-
-After installing those packages, `npm install node-gtk` would do.
+You get typed constructor properties (including inherited and interface ones),
+camelCase methods with real return types, GI nullability, typed signal
+overloads, enums, `bigint` for 64-bit integers, out-parameters surfaced as the
+return value, and cross-namespace types. GNOME's API documentation is included
+as JSDoc (with `@param`/`@returns`), so editors show it on hover — this reads the
+`.gir` files installed by the libraries' `-dev`/`-devel` packages; pass
+`--no-docs` for leaner output if they aren't installed or you don't want them.
 
-### How to build on macOS
+Because the output is a generated cache under `node_modules`, add a `postinstall`
+script so it regenerates on install:
 
-Assuming you have [brew](http://brew.sh) installed, the following has been successfully tested on El Captain.
-
-```sh
-brew install git node gobject-introspection gtk+3 cairo
+```json
+{ "scripts": { "postinstall": "node-gtk generate-types Gtk-4.0 Adw-1" } }
 ```
 
-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](https://msys2.github.io/).
-
-Once VS and its C++ compiler is available and MSYS2 installed, launch the MinGW shell.
-
-```sh
-# 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
+Run `npx node-gtk generate-types --help` for options.
 
-# 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](https://github.com/nodejs/node-gyp#installation)
-
-The below blog post series will help you get started:
-
-1. [Node.js GTK Hello World on Windows](https://ten0s.github.io/blog/2022/07/22/nodejs-gtk-hello-world-on-windows)
-2. [Find DLLs and Typelibs dependencies for Node.js GTK Application on Windows](https://ten0s.github.io/blog/2022/07/25/find-dlls-and-typelibs-dependencies-for-nodejs-gtk-application-on-windows)
-3. [Package Node.js GTK Application on Windows](https://ten0s.github.io/blog/2022/07/27/package-nodejs-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:
-
-```sh
-# 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:
-
-```sh
-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 <kbd>Cmd</kbd> + <kbd>Tab</kbd> if you don't see it.
-
-#### Browser demo
-
-If you'd like to test `./examples/browser.js` you'll need [WebKit2 GTK+](http://webkitgtk.org/) 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:
-
-```sh
-# macOS needs to have the Adwaita theme installed
-# brew install adwaita-icon-theme
+## Installing and building
 
-# Usage: ./examples/browser.js <url> [theme]
-./examples/browser.js  google.com  dark
-```
+See [Installing & building](./doc/installation.md) for prebuilt-binary notes, per-platform build instructions (Linux, macOS, Windows), and how to run the tests and examples.
 
 ## Contributing
 
@@ -259,9 +150,9 @@ If you'd like to help, we'd be more than happy to have support. To setup your de
 run `npm run configure`. You can then build the project with `npm run build`. To generate the `compile_commands.json`
 for LSP to work nicely, you can use [bear](https://github.com/rizsotto/Bear) as `bear -- npm run build`.
 
- - https://developer.gnome.org/gi/stable/index.html
- - https://v8docs.nodesource.com/
- - https://github.com/nodejs/nan#api
+- https://developer.gnome.org/gi/stable/index.html
+- https://v8docs.nodesource.com/
+- https://github.com/nodejs/nan#api
 
 There is a [Discord channel](https://discord.gg/r2VqPUV) but it receives little monitoring, use github issues or
 discussions preferably.

package/bin/node-gtk.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/*
+ * node-gtk CLI
+ *
+ * Subcommands:
+ *   generate-types   Generate TypeScript declarations from the installed typelibs.
+ */
+
+const cmd = process.argv[2]
+
+switch (cmd) {
+  case 'generate-types':
+    require('../tools/generate-types.js').run(process.argv.slice(3))
+    break
+  case undefined:
+  case '-h':
+  case '--help':
+    console.log(`node-gtk — GNOME GObject-Introspection bindings for Node.js
+
+Usage: node-gtk <command> [options]
+
+Commands:
+  generate-types <Namespace-Version> [...]   Generate TypeScript types (.d.ts)
+
+Run \`node-gtk generate-types --help\` for details.`)
+    process.exit(cmd ? 0 : 1)
+    break
+  default:
+    console.error(`node-gtk: unknown command '${cmd}'. Try 'node-gtk --help'.`)
+    process.exit(1)
+}

package/lib/bootstrap.js

@@ -82,11 +82,26 @@ function extendBaseClass(BaseClass) {
   }
 
   BaseClass.prototype.once = function once(event, callback, after) {
+    defineListeners(this)
+
+    if (!this._listeners.has(event))
+      this._listeners.set(event, new WeakMap())
+
+    const fnMap = this._listeners.get(event)
+
     const newCallback = (...args) => {
-      callback(...args)
-      this.off(event, newCallback)
+      this.off(event, callback)
+      return callback(...args)
+    }
+
+    const handlerID = this.connect(event, newCallback, after)
+    if (handlerID === 0) {
+      throw new Error(`Could not connect to signal ${event}`)
     }
-    this.on(event, newCallback, after)
+    // Key the listener map by the user's original callback so that it can be
+    // cancelled with off(event, callback), even though the connected handler
+    // is the wrapper.
+    fnMap.set(callback, handlerID)
     return this
   }
 
@@ -220,7 +235,10 @@ function makeEnum(info) {
   for (let i = 0; i < nValues; i++) {
     const valueInfo = GI.enum_info_get_value(info, i);
     const valueName = getName(valueInfo).toUpperCase()
-    const value = GI.value_info_get_value(valueInfo)
+    // g_value_info_get_value returns a gint64 (-> BigInt since #323), but enum
+    // and flags members are small integers and are compared/bitwise-combined
+    // as Numbers throughout, so coerce here.
+    const value = Number(GI.value_info_get_value(valueInfo))
     Object.defineProperty(object, valueName, {
       configurable: true,
       enumerable: true,

package/lib/index.js

@@ -11,6 +11,30 @@ const module_ = require('./module.js')
 const loop = require('./loop.js')
 const registerClass = require('./register-class.js')
 
+/**
+ * Returns the GType (as a BigInt) of a GObject/boxed class, an instance of one,
+ * or a GType passed through as-is. See #286.
+ *
+ * @param {Function|object|bigint} value a class, an instance, or a GType
+ * @returns {bigint} the associated GType
+ */
+function getGType(value) {
+  if (typeof value === 'bigint')
+    return value
+
+  if (value != null) {
+    // A class: the GType lives on its prototype.
+    if (typeof value === 'function' && value.prototype != null && value.prototype.__gtype__ !== undefined)
+      return value.prototype.__gtype__
+
+    // An instance (or prototype).
+    if (value.__gtype__ !== undefined)
+      return value.__gtype__
+  }
+
+  throw new TypeError('getGType: expected a GObject/boxed class, instance, or GType')
+}
+
 /*
  * Exports
  */
@@ -20,6 +44,7 @@ module.exports = {
   ...module_,
   startLoop: loop.start,
   registerClass: registerClass,
+  getGType: getGType,
   System: internal.System,
 
   // Private API

package/lib/overrides/Gtk-4.0.js

@@ -112,7 +112,8 @@ exports.apply = (Gtk) => {
    */
   Gtk.FileChooserDialog.prototype.getFile = function getFile() {
     const file = originalGetFile.call(this)
-    file.__proto__= Gio.File.prototype
+    if (file)
+      file.__proto__= Gio.File.prototype
     return file
   }
 
@@ -122,7 +123,8 @@ exports.apply = (Gtk) => {
    */
   Gtk.FileChooserWidget.prototype.getFile = function getFile() {
     const file = originalGetFile.call(this)
-    file.__proto__= Gio.File.prototype
+    if (file)
+      file.__proto__= Gio.File.prototype
     return file
   }
 }

package/lib/register-class.js

@@ -119,7 +119,7 @@ function findVFuncOnParents(info, name) {
 function findVFuncOnInterfaces(gtype, name) {
   const interfaces = GObject.typeInterfaces(gtype);
 
-  for (i = 0; i < interfaces.length; i++) {
+  for (let i = 0; i < interfaces.length; i++) {
     const interfaceInfo = findInfoByGtype(interfaces[i])
 
     /* The interface doesn't have to exist, it could be private

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "node-gtk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "GNOME Gtk+ bindings for NodeJS",
   "main": "lib/index.js",
+  "bin": {
+    "node-gtk": "bin/node-gtk.js"
+  },
   "scripts": {
     "install": "npx node-pre-gyp install --fallback-to-build",
+    "build:test-fixtures": "node scripts/build-test-fixtures.js",
+    "pretest": "node scripts/build-test-fixtures.js",
     "test": "mocha tests/__run__.js",
     "build": "npx node-pre-gyp build",
     "build:full": "npx node-pre-gyp rebuild",
@@ -36,7 +41,7 @@
     "lodash.camelcase": "4.3.0",
     "lodash.isequal": "4.5.0",
     "lodash.snakecase": "^4.1.1",
-    "nan": "^2.23.0",
+    "nan": "^2.27.0",
     "node-gyp": "^11.2.0",
     "remove-trailing-spaces": "^1.0.7",
     "unindent": "^2.0.0"
@@ -51,9 +56,11 @@
     "node-pre-gyp-github": "^1.4.5"
   },
   "files": [
+    "/bin",
     "/lib",
     "/src",
     "/scripts",
+    "/tools",
     "binding.gyp"
   ],
   "binary": {