ObjectRequires a module. Automatically loads dependencies.
Prepends a path to GObject-Introspection search path (for typelibs)
Prepends a path to GObject-Introspection library path (for shared libraries)
Object
Requires a module. Automatically loads dependencies.
**Returns**: Object - the loaded module
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| ns | string | | namespace to load |
| version | string | null | version to load (null for latest) |
#### prependSearchPath(path)
Prepends a path to GObject-Introspection search path (for typelibs)
| Param | Type |
| --- | --- |
| path | string |
#### prependLibraryPath(path)
Prepends a path to GObject-Introspection library path (for shared libraries)
| Param | Type |
| --- | --- |
| path | string |
### Signals (event handlers)
Signals (or events, in NodeJS semantics) are dispatched through the usual `.on`,
`.off`, and `.once` methods.
Returning `true` from an event handler can have the special semantic of stopping the event
from being propagated or preventing the default behavior. Refer to GTK documentation for details.
(E.g. [GtkWidget signals](https://developer.gnome.org/gtk3/stable/GtkWidget.html#GtkWidget.signals))
```javascript
const input = new Gtk.Entry()
/**
* GObject.on - associates a callback to an event
* @param {String} name - Name of the event
* @param {Function} callback - Event handler
*/
input.on('key-press-event', onKeyPress)
/**
* GObject.off - dissociates callback from an event
* @param {String} name - Name of the event
* @param {Function} callback - Event handler
*/
input.off('key-press-event', onKeyPress)
/**
* GObject.once - as GObject.on, but only runs once
* @param {String} name - Name of the event
* @param {Function} callback - Event handler
*/
input.once('key-press-event', onKeyPress)
function onKeyPress(event) {
// event.__proto__ === Gdk.EventKey
console.log(event.string, event.keyval)
}
```
Low-level methods `.connect(name: String, callback: Function) : Number` and
`.disconnect(name: String, handleID: Number) : void` are also available.
### Gtk
For GTK objects and functions documentation, please refer to [gnome documentation](https://developer.gnome.org/gtk3/stable/), or any other GIR generated documentation as [valadoc](https://valadoc.org/gtk+-3.0/index.htm).
### Naming conventions
- **Functions, Methods & Virtual Functions**: `lowerCamelCase`
Methods on GObject, structs, unions and functions on namespaces.
Example:
`GLib.randomIntRange(0, 100)`
`textBuffer.placeCursor(0)`
- **Fields & Properties**: `lowerCamelCase`
Fields are on structs and unions.
Properties are on GObjects.
Example:
`textView.showLineNumbers = true`
`new Gdk.Color().blue = 200`
- **Structs, Unions, GObjects & Interfaces**: `UpperCamelCase`
Defined on namespaces.
Example:
`Gtk.Button`
`Gdk.Color`
- **Enums, Flags**: `UpperCamelCase`
Defined on namespaces.
Example:
`Gtk.AttachOptions`
`Gdk.EventType`
- **Constants & Values**: `SNAKE_CASE` (not modified, may contain lowercase)
Can be attached on namespaces or on specific objects.
Example:
`Gdk.KEY_g !== Gdk.KEY_G`
`Gdk.EventType.KEY_PRESS`
- **Signals**: `dash-case`
Events triggered by GObjects.
Example:
`gtkEntry.on('key-press-event', (ev) => { ... })`
## Installing and building
### Target Platforms (so far)
We're planning to serve pre-built binaries in order to make this project as cross platform and easy to install
as possible. However, right now we support only **Linux** and experimentally **OSX** but in both targets
_the project will falback to build_.
### Requirements
In order to clone, install, and build this project you'll need a working copy of git, nodejs 8 or higher, npm,
python2, and either gcc 8 (other versions may fail) or clang.
In the _not-working-yet_ Windows platform, all dependencies must be available under [MSYS2 shell](https://msys2.github.io).
### How to build on Ubuntu
Be sure `node` is version **8** or higher.
Ignore the following step iv `node --version` is already 8 or higher.
```sh
# setup node 10
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
```
Install basic dependencies.
```sh
# install dependencies
sudo apt-get install \
build-essential git \
nodejs \
gobject-introspection \
libgirepository1.0-dev
```
At this point `npm install node-gtk` should already install, fallback and build `node-gtk` without problems.
### How to build on ArchLinux
The following should be the bare minimum to be able to build the project.
```sh
pacman -S --needed \
base-devel git \
nodejs npm \
gtk3 gobject-introspection
```
Feel free to install all `base-devel` utilities.
After installing those packages, `npm install node-gtk` would do.
### How to build on OSX
Assuming you have [brew](http://brew.sh) installed, the following has been successfully tested on El Captain.
```sh
# basic dependencies to build this repo
brew install git node gtk+3
```
At this point `npm install node-gtk` should already install, fallback and build `node-gtk` without problems.
### Testing the project
If you'd like to test everything builds and work properly, find a target to clone this project, then run `npm install`.
```sh
# clone and build
git clone https://github.com/romgrk/node-gtk.git
cd node-gtk
npm install
# how to verify from node-gtk folder
./examples/hello-gtk.js
```
If you'll see a little window saying hello that's it: it works!
Please note in OSX 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+](http://webkitgtk.org/) libary.
* in **Ubuntu**, you can `apt-get install libwebkit2gtk-3.0` (`4.0` works too) and try it out.
* in **ArchLinux**, you can `pacman -S --needed webkitgtk` and try it out.
* in **OSX**, 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
# OSX needs to have the Adwaita theme installed
# brew install adwaita-icon-theme
# Usage: ./examples/browser.js