README.md (7983B)
1 # statnot 2 statnot is a [notification-daemon](http://www.galago-project.org/news/index.php) replacement for lightweight window managers like [dwm](http://dwm.suckless.org) and [wmii](http://wmii.suckless.org). It receives and displays notifications from the widely used [Desktop Notifications](http://www.galago-project.org/specs/notification/0.9/index.html) speficiation. 3 4 * [source repository](http://github.com/halhen/statnot/) 5 6 ## Background 7 In some lightweight window managers, the text in the status bar is fed from an external process. For example dwm (version 5.4 and above) reads the status message from the X root window name, set by `xsetroot -name <text>`. A user typically enters a loop like below in .xinitrc to keep the status bar updating. 8 9 while true 10 do 11 xsetroot -name "$(date +"%F %R")" 12 sleep 30s # update every thirty seconds 13 done & 14 15 This solution works well for status messages that are managed from a single point, for example when printing the same information every time. statnot lets you combine regular status messages with Desktop Notifications in a straightforward way. 16 17 ### Desktop Notifications 18 If you have used a "regular" window manager like KDE or Gnome, you have probably come across notifications. The are typically small windows with text messages and sometimes an icon that shows for a couple of seconds before they fade out. They are for example used to let the user know that a new instant message has arrived or that the battery is running low. Desktop Notifications is a specification created for freedesktop.org that many applications use. For example Pidgin and Evolution can be configured to notify for new messages using Desktop Notifications. 19 20 ## Installation 21 22 To install statnot, first install the required dependencies: 23 24 * [python 3.5+](http://www.python.org) 25 * dbus-python 26 * PyGObject 27 * gtk3 - (not for GUI support) 28 29 Follow the [PyGObject installation instructions](https://pygobject.readthedocs.io/en/latest/getting_started.html) for your system. 30 That should take care of most of your dependencies. 31 32 Next, adjust the target directories in the `config.mk` file to fit your setup. 33 34 To install, run as root: 35 36 # make install 37 38 Finally, statnot needs to start with the window manager. You can for example add the following to .xinitrc: 39 40 killall notification-daemon &> /dev/null 41 statnot & 42 43 Note that the statnot needs to be the only notification tool running. The example above makes sure that `notification-daemon` is not running. 44 45 ## Configuration 46 The major, likely only, part you want to configure in statnot is what the status message should look like. During installation, a file called `.statusline.sh` is created in `$HOME/`. This gets called with regular intervals to retrieve the text that should be printed on the status line. statnot reads STDOUT, so a simple `echo <text>` is a good way to return the text. 47 48 During normal status updates, .statusline.sh is called without parameters. Here, you typically fetch and `echo` information about the computers performance, battery level or current time. 49 50 Any pending notification is passed as the first argument to .statusline.sh. This way you can include additional information to the actual notification. 51 52 Below is an example of .statusline.sh. It prints something like `[load 0.12 0.10 0.7] 11:42` in the status bar. When there is a pending notification, it prints `NOTIFICATION: <notification text>`. 53 54 if [ $# -eq 0 ]; then 55 loadavg="`cat /proc/loadavg | awk '{print $1, $2, $3}'`"; 56 echo "[load ${loadavg}] `date +'%R'`"; 57 else 58 echo "NOTIFICATION: $1"; 59 fi 60 61 For more advanced configuration, a configuration file can be passed to statnot on the command line, which overrides the default settings. This configuration file must be written in valid python, which will be read if the filename is given on the command line. You do only need to set the variables you want to change, and can leave the rest out. 62 63 Below is an example of a configuration which sets the defaults. 64 65 # Default time a notification is show, unless specified in notification 66 DEFAULT_NOTIFY_TIMEOUT = 3000 # milliseconds 67 68 # Maximum time a notification is allowed to show 69 MAX_NOTIFY_TIMEOUT = 5000 # milliseconds 70 71 # Maximum number of characters in a notification. 72 NOTIFICATION_MAX_LENGTH = 100 # number of characters 73 74 # Time between regular status updates 75 STATUS_UPDATE_INTERVAL = 2.0 # seconds 76 77 # Command to fetch status text from. We read from stdout. 78 # Each argument must be an element in the array 79 # os must be imported to use os.getenv 80 import os 81 STATUS_COMMAND = ['/bin/sh', f'{os.getenv('HOME')}/.statusline.sh'] 82 83 # Always show text from STATUS_COMMAND? If false, only show notifications 84 USE_STATUSTEXT=True 85 86 # Put incoming notifications in a queue, so each one is shown. 87 # If false, the most recent notification is shown directly. 88 QUEUE_NOTIFICATIONS=True 89 90 # update_text(text) is called when the status text should be updated 91 # If there is a pending notification to be formatted, it is appended as 92 # the final argument to the STATUS_COMMAND, e.g. as $1 in default shellscript 93 94 # dwm statusbar update 95 import subprocess 96 def update_text(text): 97 # Get first line 98 first_line = text.splitline()[:-1] 99 subprocess.call(["xsetroot", "-name", first_line]) 100 101 ## Possible errors 102 If no status message shows, verify that statnot is running. Also make sure your $HOME/.statusline.sh works and prints properly. 103 104 If notifications are not shown, make sure that no other notification-daemon is running. `killall notification-daemon` is a good command to try. Restart statnot if there was another daemon running. Also make sure that .statusline.sh takes care of and prints the $1 parameter (see section Configuration). 105 106 ## Supported software 107 More and more applications use Desktop Notifications. Use [Google](http://www.google.com) to find solutions for your applications. `libnotify` is a good term to search, since it is a common library used by many applications. 108 109 You can also send your own notifications to statnot. This is easily done with the `notify-send` command. For example, `notify-send "Hello World"` will print `Hello World` in the status bar according to your speficiation. This is useful to notify that a long running task like a download or software build has finished. 110 111 notify-send can also be used for other, more direct messages. For exampe, I call a script called `dwm-volume` when my volume media buttons on the keyboard are pressed. This script adjusts the volume and sends a notification containing e.g. `vol [52%] [on]`. 112 113 #!/bin/sh 114 if [ $# -eq 1 ]; then 115 amixer -q set Master $1 116 fi 117 notify-send -t 0 "`amixer get Master | awk 'NR==5 {print "vol " $4, $6}'`" 118 119 As you can see, I use the option `-t 0` to notify-send, i.e. I request that the notification should show for zero milliseconds. For statnot, this means that the message should show for a regular status tick, by default two seconds, but if other notifications arrive, like a second press on the volume button, it goes away. This setup allows my audio volume to show only when I change it, while it updates instantly when I press the media buttons. Note that this option becomes useless if QUEUE_NOTIFICATIONS is set to False. 120 121 ## Final notes 122 I'm sure there are other ways to use statnot. For example, one can create an update_text() that sends notifications as e-mail or instant messages, or that stores them to a log file. If you create any cool applications with statnot, I'd be happy to hear about them. 123 124 Released under the GPL. Please report any bugs or feature requests by email. Also, please drop me a line to let me know you like and use this software. 125 126 Authors: 127 * Henrik Hallberg (<halhen@k2h.se>); halhen@github 128 * Olivier Ramonat; enzbang@github 129 * Xavier Capaldi; xcapaldi@github