<commit_before># Hudkit&ensp;[![](https://img.shields.io/travis/anko/hudkit?style=flat-square)](https://travis-ci.org/anko/hudkit) ![](https://raw.githubusercontent.com/gist/anko/8c88a25fb0cf3480bff9f4a2d6091d9c/raw/97ce36a92df2b0f72d6375c9a7e56d10846d80ec/amazing.svg)

Transparent click-through web browser overlay ("[HUD][wiki-hud]") over your
whole desktop, using [WebKit][webkit].

If you know web development, you can use Hudkit to make the _coolest statusbar
in existence_, or _SVG desktop fireworks_, or whatever else you can think of
using a fullscreen transparent web view for.

## Features

 - Works with multiple monitors, and connecting/disconnecting them.
 - Has a [JavaScript API](#javascript-api), so scripts on the page can query
   monitor layout and change which areas of the overlay are clickable, for
   example.
 - Small executable.  Uses native GTK and WebKit libraries.
 - Supports modern web APIs like WebSockets, WebAudio, WebGL, etc.

Platforms:&emsp;:heavy\_check\_mark: Linux (X11)&emsp;:grey\_question: OS X&emsp;:no\_entry\_sign: ~~Linux (Wayland)~~&emsp;:no\_entry\_sign: ~~Windows~~

## Quick start

```sh
cd /tmp
git clone https://github.com/anko/hudkit.git
cd hudkit
make
cd example
./run.sh
```

If `make` complains, check [dependencies](#dependencies).

The [`example/` directory](example/) contains various inspirations and starting
points.  If you come up with any of your own (fairly compact) example ideas,
please PR.

## Usage

```
USAGE: ./hudkit <URL> [--help] [--webkit-settings option1=value1,...]

    <URL>
        Universal Resource Locator to be loaded on the overlay web view.
        For example, to load a local file, you'd pass something like:

            file:///home/mary/test.html

        or to load from a local web server at port 4000:

            http://localhost:4000

    --inspect
        Open the Web Inspector (dev tools) on start.

    --webkit-settings
        Followed by comma-separated setting names to pass to the WebKit web
        view.  Which settings are available depends on what version of WebKit
        this program was compiled against.  See a list of ones supported on
        your system by passing '--webkit-settings help'.

        For details of what the options do, see the list at
        https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html
        Pass setting names as underscore_separated_words.

        Default settings are the same as WebKit's defaults, plus these two:
         - enable_write_console_messages_to_stdout
         - enable_developer_extras

        Boolean options can look like
            option_name
            option_name=TRUE
            option_name=FALSE
        String and integer options can look like
            option_name=foo
            option_name=42
        The enum option hardware_acceleration_policy has these valid values
            ON_DEMAND, ALWAYS, NEVER

    --help
        Print this help text, then exit.

    All of the standard GTK debug options and env variables are also
    supported.  You probably won't need them, but you can find a list here:
    https://developer.gnome.org/gtk3/stable/gtk-running.html
```

## JavaScript API

JavaScript on the web page context has a `Hudkit` object, with these properties:

### `async Hudkit.getMonitorLayout()`

Return: an Array of `{name, x, y, width, height}` objects, representing your
monitors' device names and dimensions.

Example:

```js
await Hudkit.getMonitorLayout()

monitors.forEach((m) => {
  console.log(`${m.name} pos:${m.x},${m.y} size:${m.width},${m.height}`)
})
```

### `Hudkit.on(eventName, listener)`

Registers the given `listener` function to be called on events by the string
name `eventName`.

Currently listenable events:

 - `monitors-changed`: fired when a monitor is logically connected or
   disconnected, such as through `xrandr`.

   No arguments are passed to the `listener`.  Call `Hudkit.getMonitorLayout`
   to get the updated layout.

### `Hudkit.off(eventName, listener)`

De-registers the given `listener` from the given `eventName`, so it will no
longer be called.

### `async Hudkit.setClickableAreas(rectangles)`

Sets which areas of the overlay window are clickable.  By default, it is not
clickable.  The given area replaces the previous.

Parameters:

 - `rectangles`: Array of objects with properties `x`, `y`, `width`, and
   `height`.  Other properties are ignored, and missing properties are treated
   as 0.  Can be an empty Array, to make everything non-clickable.

   The area of the desktop represented by the union of the given rectangles
   become input-opaque (able to receive mouse events).  All other areas become
   input-transparent.

Return:  `undefined`

Example:

```js
// Make a tall narrow strip of the overlay window clickable, in the top left
// corner of the screen. The dimensions are in pixels.
Hudkit.setClickableAreas([
  { x: 0, y: 0, width: 200, height: 1000 }
], err => console.error(err))
```

Notes:

 - If the Web Inspector is attached to the overlay window, the area it occupies
   is automatically kept clickable, independently of calls to this function.

 - When monitors are connected or disconnected, your clickable areas are reset
   to nothing being clickable, because their positioning would be
   unpredictable.  Subscribe to the `'monitors-changed'` event
   (`Hudkit.on('monitors-changed', () => { ... })`) and update your clickable
   areas accordingly!

### `async Hudkit.showInspector([attached])`

Opens the Web Inspector (also known as Developer Tools), for debugging the page
loaded in the web view.

Parameters:

 - `attach`: Boolean.  If `true`, starts the inspector attached to the overlay
   window.  If `false`, start the inspector in its own window.  (Default:
   `false`.)

Return:  `undefined`

:information\_source: You can also start the inspector with the `--inspect`
flag.  That's usually better, because it works even if your JS crashes before
calling this function.


## Install

In the root directory of this project,

    make

### Dependencies

You'll need *GTK 3*, and a corresponding *webkit2gtk*.

On [Arch][arch], the packages are called `gtk3` and `webkit2gtk`.

On [Void][void], they are `gtk+3-devel` and `webkit2gtk-devel`.

On [Ubuntu][ubuntu], they are `libgtk-3-dev` and `libwebkit2gtk-4.0-devel`.
<commit_msg>Fix some readme typos<commit_after># Hudkit&ensp;[![](https://img.shields.io/travis/anko/hudkit?style=flat-square)](https://travis-ci.org/anko/hudkit) ![](https://raw.githubusercontent.com/gist/anko/8c88a25fb0cf3480bff9f4a2d6091d9c/raw/97ce36a92df2b0f72d6375c9a7e56d10846d80ec/amazing.svg)

Transparent click-through web browser overlay ("[HUD][wiki-hud]") over your
whole desktop, using [WebKit][webkit].

If you know web development, you can use Hudkit to make the _coolest statusbar
in existence_, or _SVG desktop fireworks_, or whatever else you can think of
using a fullscreen transparent web view for.

## Features

 - Works with multiple monitors, and connecting/disconnecting them.
 - Has a [JavaScript API](#javascript-api), so scripts on the page can query
   monitor layout and change which areas of the overlay are clickable, for
   example.
 - Small executable.  Uses native GTK and WebKit libraries.
 - Supports modern web APIs like WebSockets, WebAudio, WebGL, etc.

Platforms:&emsp;:heavy\_check\_mark: Linux (X11)&emsp;:grey\_question: OS X&emsp;:no\_entry\_sign: ~~Linux (Wayland)~~&emsp;:no\_entry\_sign: ~~Windows~~

## Quick start

```sh
cd /tmp
git clone https://github.com/anko/hudkit.git
cd hudkit
make
cd example
./run.sh
```

If `make` complains, check [dependencies](#dependencies).

The [`example/` directory](example/) contains various inspirations and starting
points.  If you come up with any of your own (fairly compact) example ideas,
please PR.

## Usage

```
USAGE: ./hudkit <URL> [--help] [--webkit-settings option1=value1,...]

    <URL>
        Universal Resource Locator to be loaded on the overlay web view.
        For example, to load a local file, you'd pass something like:

            file:///home/mary/test.html

        or to load from a local web server at port 4000:

            http://localhost:4000

    --inspect
        Open the Web Inspector (dev tools) on start.

    --webkit-settings
        Followed by comma-separated setting names to pass to the WebKit web
        view.  Which settings are available depends on what version of WebKit
        this program was compiled against.  See a list of ones supported on
        your system by passing '--webkit-settings help'.

        For details of what the options do, see the list at
        https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html
        Pass setting names as underscore_separated_words.

        Default settings are the same as WebKit's defaults, plus these two:
         - enable_write_console_messages_to_stdout
         - enable_developer_extras

        Boolean options can look like
            option_name
            option_name=TRUE
            option_name=FALSE
        String and integer options can look like
            option_name=foo
            option_name=42
        The enum option hardware_acceleration_policy has these valid values
            ON_DEMAND, ALWAYS, NEVER

    --help
        Print this help text, then exit.

    All of the standard GTK debug options and env variables are also
    supported.  You probably won't need them, but you can find a list here:
    https://developer.gnome.org/gtk3/stable/gtk-running.html
```

## JavaScript API

JavaScript on the web page context has a `Hudkit` object, with these properties:

### `async Hudkit.getMonitorLayout()`

Return: an Array of `{name, x, y, width, height}` objects, representing your
monitors' device names and dimensions.

Example:

```js
await Hudkit.getMonitorLayout()

monitors.forEach((m) => {
  console.log(`${m.name} pos:${m.x},${m.y} size:${m.width},${m.height}`)
})
```

### `Hudkit.on(eventName, listener)`

Registers the given `listener` function to be called on events by the string
name `eventName`.

Currently listenable events:

 - `monitors-changed`: fired when a monitor is logically connected or
   disconnected, such as through `xrandr`.

   No arguments are passed to the `listener`.  Call `Hudkit.getMonitorLayout`
   to get the updated layout.

### `Hudkit.off(eventName, listener)`

De-registers the given `listener` from the given `eventName`, so it will no
longer be called.

### `async Hudkit.setClickableAreas(rectangles)`

Sets which areas of the overlay window are clickable.  By default, it is not
clickable.  The given area replaces the previous.

Parameters:

 - `rectangles`: Array of objects with properties `x`, `y`, `width`, and
   `height`.  Other properties are ignored, and missing properties are treated
   as 0.  Can be an empty Array, to make everything non-clickable.

   The area of the desktop represented by the union of the given rectangles
   become input-opaque (able to receive mouse events).  All other areas become
   input-transparent.

Return:  `undefined`

Example:

```js
// Make a tall narrow strip of the overlay window clickable, in the top left
// corner of the screen. The dimensions are in pixels.
Hudkit.setClickableAreas([
  { x: 0, y: 0, width: 200, height: 1000 }
], err => console.error(err))
```

Notes:

 - If the Web Inspector is attached to the overlay window, the area it occupies
   is automatically kept clickable, independently of calls to this function.

 - When monitors are connected or disconnected, your clickable areas are reset
   to nothing being clickable, because their positioning would be
   unpredictable.  Subscribe to the `'monitors-changed'` event
   (`Hudkit.on('monitors-changed', () => { ... })`) and update your clickable
   areas accordingly!

### `async Hudkit.showInspector([attached])`

Opens the Web Inspector (also known as Developer Tools), for debugging the page
loaded in the web view.

Parameters:

 - `attached`: Boolean.  If `true`, starts the inspector attached to the
   overlay window.  If `false`, start the inspector in its own window.
   (Optional.  Default: `false`.)

Return:  `undefined`

:information\_source: You can also start the inspector with the `--inspect`
flag.  That's usually better, because it works even if your JS crashes before
calling this function.


## Install

In the root directory of this project,

    make

### Dependencies

You'll need *GTK 3*, and a corresponding *webkit2gtk*.

On [Arch][arch], the packages are called `gtk3` and `webkit2gtk`.

On [Void][void], they are `gtk+3-devel` and `webkit2gtk-devel`.

On [Ubuntu][ubuntu], they are `libgtk-3-dev` and `libwebkit2gtk-4.0-devel`.

{'fraction_non_alphanumeric': 0.09558707643814027, 'fraction_numerical': 0.012450748620961388, 'mean_word_length': 3.584898843930636, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 13, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '552950', 'n_tokens_mistral': 3959, 'n_tokens_neox': 3648, 'n_words': 1462}