spacetray/README.md

spacetray
=========

A panel Applet using Qt5 for showing the Status of a Hackerspace. Compatible with the SpaceAPI version >= 0.13.

Red = Door/Lock open:

![spacetray](shot-open.png)

Green = Door/Lock closed:

![spacetray](shot-closed.png)

Additionally, a notification is displayed as soon as the status changes.

Installation:
-------------

Requirements:

- Standard tools like g++, cmake, etc.
- Qt5 (Widgets and Network modules)

Use the following command for getting the sources:

    git clone https://github.com/hanez/spacetray.git

Change into the new directory:

    cd spacetray

To configure and compile the sources, run:

    cmake -S . -B build
    cmake --build build

This will compile spacetray with status icon and notification support.

Just copy "build/spacetray" to a folder in your $PATH. I do:

    cp ./build/spacetray ~/bin/

You can copy the file to /usr/bin to make it available to all users but I don't. If you want that just run:

    sudo cp ./build/spacetray /usr/bin/

Configuration:
--------------

Configuration is done via command line arguments.

Usage:
------

Run spacetray with:

    ./build/spacetray <statusurl> &

Or if in your $PATH:

    spacetray <statusurl>

The polling interval defaults to 300 seconds (5 minutes). It can be changed with the `-i` or `--interval` option, given either before or after the status URL:

    ./build/spacetray <statusurl> -i 60 &

    ./build/spacetray -i 60 <statusurl>

The interval is specified in seconds and must be a positive number.

Themes:
-------

You can create your own icon theme by generating a C++ header file containing the icons as raw RGBA8888 pixel data in a `static const quint8` array.

The format should look like this:

    static const quint8 icon_open_data[] = {
      0xRR, 0xGG, 0xBB, 0xAA, ...
    };

    static const quint8 icon_closed_data[] = {
      0xRR, 0xGG, 0xBB, 0xAA, ...
    };

The image size used in the default theme is 52x48 pixels with four channels (RGBA).

To create these arrays from a PNG image, you can use `ImageMagick` to convert the image to raw RGBA data and then format it into a C++ header.

Example using `magick` (ImageMagick 7):

    magick icon_open.png -size 52x48 -depth 8 RGBA:icon_open.raw
    hexdump -v -e '12/1 "0x%02x, " "\n"' icon_open.raw

Or using a simple one-liner to generate the header content:

    echo "static const quint8 icon_open_data[] = {" > themes/my_theme.h
    magick icon_open.png -size 52x48 -depth 8 RGBA:- | hexdump -v -e '12/1 "0x%02x, " "\n"' >> themes/my_theme.h
    echo "};" >> themes/my_theme.h

Repeat the process for `icon_closed_data` and append it to the same header file.

You can then use your custom icon theme by changing the line:

    #include "themes/lock.h"

to:

    #include "themes/THEME_NAME.h"

in:

    ./spacetray.cpp