README.md

# My Pekwm Setup

I run **pekwm** on **GhostBSD** with **Xorg** as my daily window manager.  
It’s light, fast, and highly configurable — exactly what I want for a simple yet powerful desktop environment.  

My workflow is mostly **keyboard-driven**, with custom keybindings for navigation, window management, and launching applications.  
I also rely on pekwm’s **grouping feature** to keep things organized: all my PDFs open in a single tabbed frame, and I can launch multiple terminal windows grouped together for easier handling.  

On top of that, I’ve added a few helper scripts, a custom menu generator, and some small tweaks for hardware control like volume, brightness, and touchscreen toggling.  
I've added a simple system that save and restore your pekwm session. So you retreive your environment exactly where it was before shutdown. 
The result is a **minimalist, efficient, and responsive environment** that fits my workflow perfectly, without unnecessary overhead.

# Theme

My theme is a slightly modified version of **Minimalst** by [Myugan](https://www.gnome-look.org/p/1137146).
My main modificaitons concern the sizes and the slight modificaitons of border's colors. 

Thus a window having the focus is white, the orhers are lighblue

# Config

I mostly use the default configuration and have not made major changes.

# Autoproperties

Since I often open a large number of PDFs, I make use of the **grouping feature** in pekwm.  
This allows me to collect similar windows into tabs, and I can even define how many tabs a group can hold.

Here is the rule I use for **Atril** (PDF reader):

    Property = "^atril,^Atril" {
        ApplyOn = "New"
        Group = "pdf" {
            Size = "15"
            FocusedFirst = "True"
            Raise = "True"
        }
    }

I also use a similar rule for **Alacritty** terminals that I launch with a special class (`grouped`):

    Property = "^grouped,^grouped" {
        ApplyOn = "New"
        Group = "grouped" {
            Size = "15"
            FocusedFirst = "True"
            Raise = "True"
        }
        ClientGeometry = "1280x640+50+200"
    }

Such grouped Alacritty windows are created with:

    alacritty --class grouped

I have a specific config for my pseudo lockscreen made with xterm. 
It display in full screen and without border an xterm window displaying battery info. 

     Property = "xterm,Bigscreen" {
           # ApplyOn = "Start New"
           ApplyOn = "New"
           Border = "False"; Titlebar = "False"
           Sticky = "True"
           Fullscreen = "True"
     }

To use this autoproperties, I lauch my app via the following command:

    xterm -fa Monospace -fs 26 -bg black -fg black -title mybattery -class Bigscreen -e $HOME/.pekwm/scripts/xterm_mybattery.sh

The keyword here is the "-class BigScreen" which tels to pekwm to make it fullscreen and without borders, title, ...

A good way to defined what must be the Property value, you can use the following command:

    xprop WM_CLASS | sed 's/.*"\(.*\)", "\(.*\)".*/ "\1,\2" /g'


# Vars

I define a few environment variables to simplify launching applications:

    $BROWSER="firefox"
    $EDITOR="alacritty -e nvim"
    $FILEMANAGER="spacefm"
    $EMAILS="thunderbird"
    $TERM="alacritty --class grouped"

For keyboard-driven window movement and resizing, I also set:

    $MOVERESIZE_INCREMENT="15"

# Keys

## Pekwm Keybindings Documentation

This section explains my **`keys`** configuration for **pekwm**, a lightweight and flexible window manager.
It details the key bindings, actions, and custom scripts referenced in my setup.

### 1. Includes

At the top of the config, I include common variables and modular keybinding files:

    INCLUDE = "vars"
    INCLUDE = "$_PEKWM_ETC_PATH/keys_inputdialog"
    INCLUDE = "$_PEKWM_ETC_PATH/keys_menu"
    INCLUDE = "$_PEKWM_ETC_PATH/keys_moveresize"

* **vars** – user-defined environment variables (`$TERM`, `$EDITOR`, `$BROWSER`, etc.).
* **keys_inputdialog**, **keys_menu**, **keys_moveresize** – modular sets of bindings for input dialogs, menus, and resizing.

### 2. Global Bindings

These are the most frequently used shortcuts available everywhere.

#### Frame Navigation

* **Alt+Tab** – Next frame (raise temporarily).
* **Alt+Shift+Tab** – Previous frame (raise temporarily).
* **Alt+Ctrl+Tab** – Next frame (raise permanently).
* **Alt+Ctrl+Shift+Tab** – Previous frame (raise permanently).
* **Super+Tab / Super+Shift+Tab** – Cycle through clients within a frame.
* **Super+Ctrl+Left/Right** – Move client left/right in frame.
* **Super+Arrow keys** – Focus neighboring windows (directional).

#### Workspace Navigation

* **Ctrl+Alt+Arrow** – Switch workspace in the given direction.
* **Ctrl+Super+Shift+Left/Right** – Jump to next/previous workspace (wrap).
* **Super+1..9** – Switch directly to workspace 1–9.
* **Ctrl+Alt+Shift+Arrow** – Send window to another workspace and follow it.
* **Super+Shift+1..9** – Send window to workspace 1–9.

#### Window Management

* **Super+M** – Toggle maximized.
* **Super+F** – Toggle fullscreen.
* **Super+Shift+U** – Resize to 50% × 50%.
* **Super+Shift+Z** – Resize to 50% × 100%.
* **Super+Shift+H** – Resize to 100% × 50%.
* **Super+Return** – Interactive move/resize.
* **Super+Shift+Arrow** – Snap window to screen edge.
* **Super+Q** – Close window.
* **Super+S** – Shade window (roll up).
* **Super+I** – Iconify (minimize).

#### Marking / Tagging

* **Super+Z** – Toggle window mark.
* **Super+A** – Attach marked windows into one frame.
* **Super+T** – Toggle tagged state.

#### Menus

* **Super+Space** – Show root menu.
* **Super+W** – Show window menu.
* **Super+L** – Show workspace navigation menu.
* **Super+C** – Show client menu.
* **Super+Shift+I** – Show icon menu.
* **Super+X** – Hide all menus.

#### External Commands

* **Print** – Run screenshot script.
* **Super+E** – Launch terminal.

#### Pekwm Control

* **Ctrl+Alt+Delete** – Restart pekwm.
* **Super+V** – Show search dialog.
* **Super+H** – Toggle harbour (dock/panel).

### 3. Chains

Chains are shortcuts with a **prefix key** followed by a second key.

* **Ctrl+Super+C** – Move windows to corners/edges.
* **Ctrl+Super+M** – Open menus (root, window, icon, goto, etc.).
* **Ctrl+Super+T** – Grouping & tagging.
* **Ctrl+Super+D** – Toggle borders/titlebars.
* **Ctrl+Super+W** – Window management (resize, maximize, geometry presets).
* **Ctrl+Super+F** – Frame navigation (cycle, move clients, focus).
* **Ctrl+Super+S** – Full workspace management.
* **Ctrl+Super+E** – Launch external apps (`$TERM`, `$BROWSER`, `$EMAILS`, `$FILEMANAGER`).
* **Ctrl+Super+H** – Quick-open config files in `$EDITOR`.
* **Ctrl+Super+P** – Reload, restart, exit pekwm, or show command dialog.

### 4. Custom Additions

I also added some personal bindings for hardware control and scripts:

* **F1** – Toggle audio mute.
* **F2/F3** – Volume down/up by 5%.
* **F5/F6** – Screen brightness down/up.
* **Ctrl+Alt+T** – Toggle touchscreen.
* **Super+B** – a kind of lock screen which show battery info in xterm.
* **Super+D** – Run `displayVaico.sh` my panel (cfr vaico project).

### 5. Notes

* `$TERM`, `$EDITOR`, `$BROWSER`, `$EMAILS`, `$FILEMANAGER` are defined in **vars**.
* Helper scripts are in `$_PEKWM_CONFIG_PATH/scripts/` (e.g. `takeScreenShot.sh`, `toggle_touchscreen.sh`).
* The **Harbour** is pekwm’s dock-like bar, which can be hidden or shown.

# Menu

I use a dedicated script to generate my **pekwm menu** from installed XDG `.desktop` entries.
It automatically categorizes applications, adds system utilities, and builds a structured `~/.pekwm/menu` file ready to use.

For details, see **README_createMenu.md**.

# Save and restore pekwm sessions

Thanks to pekwm_ctrl we list all opened windows. We check their associated PID and analyse their window's title. 
This is consolidated in a small Python script called saveSassesion.py.

This information is saved into ~/.local/db/pekwm-session. 

In order to save this information, small halt.sh, reboot.sh and logout.sh scripts have been made. They also store logging information in ~/.pekwm/pekwm_scripts.log. 

Once you restart you pekwm session, the "start" script is automatically triggered by pekwm. So, this script initiate restoreSession.py. This python script look at ~/.local/db/pekwm-session and decide which applications must be restarted.