sites

public wiki contents of suckless.org
git clone git://git.suckless.org/sites
Log | Files | Refs

index.md (4455B)

      1 # statuscmd
      2 
      3 Add clickable status bar sections.
      4 
      5 ## Description
      6 
      7 This patch sends mouse button events to a
      8 [status monitor](https://dwm.suckless.org/status_monitor/). When clicking or
      9 scrolling on a section, dwm detects the section number and mouse button, then
     10 sends them to the status monitor via a signal.
     11 
     12 The nosignal version executes shell commands defined in config.h instead of
     13 using signals.
     14 
     15 ## Usage
     16 
     17 Both the status monitor and nosignal versions will run their respective shell
     18 commands/scripts with the environment variable `BUTTON` set to the pressed
     19 button.
     20 
     21 ### With signals
     22 
     23 Apply the statuscmd patch and set the `STATUSBAR` macro in config.h
     24 to the name of the status monitor.
     25 
     26 Apply the corresponding statuscmd patch to your status monitor if there is one,
     27 or create one yourself. Feel free to add patches for other status monitors.
     28 
     29 #### Patching status monitors
     30 
     31 1. Associate each section with a signal number in the range of 1-31.
     32 2. Print each section's signal number as a raw byte before its text.
     33    * Print the signal number again after the text to end the clickable region.
     34 3. Create a signal handler:
     35 
     36         void sighandler(int signum, siginfo_t *si, void *ucontext)
     37         {
     38             int signal = signum - SIGRTMIN;
     39             /* if button is zero, the signal is not from a button press */
     40             int button = si->si_value.sival_int;
     41             ... /* do whatever you want */
     42         }
     43 
     44 4. Register the signal handler for each section, with `signal` set to the
     45    section number:
     46 
     47         struct sigaction sa = {
     48             .sa_sigaction = sighandler,
     49             .sa_flags = SA_SIGINFO
     50         };
     51         sigaction(SIGRTMIN+signal, &sa, NULL);
     52 
     53 ### Without signals
     54 
     55 Apply the statuscmd-nosignal patch and fill the `statuscmds` array in config.h
     56 with `StatusCmd` structs, which take a shell command string and an integer
     57 identifier.
     58 
     59 When setting the status, print the section number as a raw byte before its
     60 respective text.
     61 
     62 For example, with `statuscmds` defined as such:
     63 
     64     static const StatusCmd statuscmds[] = {
     65         { "volume",  1 },
     66         { "cpu",     2 },
     67         { "battery", 3 },
     68     };
     69 
     70 And root name set like this:
     71 
     72     xsetroot -name "$(printf '\01 Volume \01|\02 CPU \02|\03 Battery \03')"
     73 
     74 Clicking on ' Volume ' would run `volume`, clicking on ' CPU '
     75 would run `cpu` and clicking on ' Battery ' would run `battery`.
     76 
     77 ## Example
     78 
     79 A script run from dwm or dwmblocks with this patch might look like this:
     80 
     81     #!/bin/sh
     82 
     83     case $BUTTON in
     84         1) notify-send 'CPU usage' "$(ps axch -o cmd,%cpu --sort=-%cpu | head)" ;;
     85         3) st -e htop ;;
     86     esac
     87 
     88     printf '\01Click Me!\01'
     89 
     90 * Handle mouse buttons in a switch statement:
     91   * `1`: left button
     92   * `2`: middle button (pressing the scroll wheel)
     93   * `3`: right button
     94   * `4`: scrolling up
     95   * `5`: scrolling down
     96   * `6`: scrolling left
     97   * `7`: scrolling right
     98   * `8`: 4th button (backward)
     99   * `9`: 5th button (forwards)
    100 * Print the status text surrounded by its section number as a raw byte.
    101   * If using printf, use octal codes as they're POSIX compliant. To represent
    102     signal 30, use `\036`.
    103 
    104 ## Notes
    105 
    106 * The signal patch doesn't work on OpenBSD since it relies on `sigqueue`.
    107 * Newline characters (`\n`, `\012`, `\x0a`) get interpreted as a valid signal
    108   number 10.
    109 * This patch skips over undrawable characters when rendering the status bar
    110   text, which fixes a problem that makes dwm lag when trying to draw them.
    111 
    112 ## Download
    113 
    114 ### dwm patches
    115 
    116 * [dwm-statuscmd-20260124-a9aa0d8.diff](./dwm-statuscmd-20260124-a9aa0d8.diff)
    117 * [dwm-statuscmd-20241009-8933ebc.diff](./dwm-statuscmd-20241009-8933ebc.diff)
    118 * [dwm-statuscmd-20210405-67d76bd.diff](./dwm-statuscmd-20210405-67d76bd.diff)
    119 * [dwm-statuscmd-nosignal-20210402-67d76bd.diff](./dwm-statuscmd-nosignal-20210402-67d76bd.diff)
    120 
    121 When using [status2d](https://dwm.suckless.org/patches/status2d/), apply these
    122 patches instead after patching status2d:
    123 
    124 * [dwm-statuscmd-status2d-20210405-60bb3df.diff](./dwm-statuscmd-status2d-20210405-60bb3df.diff)
    125 * [dwm-statuscmd-nosignal-status2d-20210402-60bb3df.diff](./dwm-statuscmd-nosignal-status2d-20210402-60bb3df.diff)
    126 
    127 ### Status monitor patches
    128 
    129 * [dwmblocks-statuscmd-20210402-96cbb45.diff](./dwmblocks-statuscmd-20210402-96cbb45.diff)
    130 * [gocaudices](https://github.com/LordRusk/gocaudices/tree/master/patches/statuscmd)
    131 
    132 ## Authors
    133 
    134 * Daniel Bylinka - <daniel.bylinka@gmail.com>
    135 * Justinas Grigas - <dev@jstnas.com>