sxalert

Simple notification system for X
git clone git://mcdim.xyz/sxalert.git
Log | Files | Refs | README | LICENSE

README.txt (3347B)

      1                                ~-.
      2              ,,,;            ~-.~-.~-
      3             (.../           ~-.~-.~-.~-.~-.
      4            <} o~`,         ~-.~-.~-.~-.~-.~-.
      5             (/    \      ~-.~-.~-.~-.~-.~-.~-.
      6              ;    \    ~-.~-.~-.~-.~-.~-.~-.
      7             ;     {_.~-.~-.~-.~-.~-.~-.~
      8            ;:  .-~`    ~-.~-.~-.~-.~-.
      9           ;.: :'    ._   ~-.~-.~-.~-.~-
     10            ;::`-.    '-._  ~-.~-.~-.~-
     11             ;::. `-.    '-,~-.~-.~-.
     12              ';::::.`''-.-'
     13                ';::;;:,:'
     14                   '||"
     15                   / |
     16                 ~` ~"'mic
     17 
     18                        '||                    .   
     19  ....  ... ...  ....    ||    ....  ... ..  .||.  
     20 ||. '   '|..'  '' .||   ||  .|...||  ||' ''  ||   
     21 . '|..   .|.   .|' ||   ||  ||       ||      ||   
     22 |'..|' .|  ||. '|..'|' .||.  '|...' .||.     '|.' 
     23       
     24 
     25 Simple X Alert 
     26 ==============
     27 
     28 Simple alert utility for X.
     29 
     30 Features
     31 --------
     32 + Alert & exit -- no daemon
     33 + Freetype scalable fonts
     34 + UTF-8 support
     35 + Configurable & scriptable with shell
     36 + Dynamic screen positioning & sizing
     37 + Runtime color customization
     38 + Multi-monitor support
     39 + Concurrent notifications serialization
     40 
     41 Dependencies
     42 ------------
     43 A c99 compiler, make, libc, Xlib and Xft.
     44 
     45 Build & install
     46 ---------------
     47 To build:
     48 
     49 	$ git clone git://mcdim.xyz/sxalert.git && cd sxalert
     50 	$ make sxalert
     51 
     52 To install:
     53 
     54 	$ sudo make install
     55 
     56 Usage
     57 -----
     58 You can simply run the tool with each argument representing a line of text:
     59 
     60 	$ sxalert "First line" "Second line"
     61 
     62 You can also set color, border width & duration:
     63 
     64 	$ sxalert -d 1000 -b 5 -t FFFFFF -g 000000 -r FFFFFF "Hello world!"
     65 
     66 These will override the defaults defined in `config.h`
     67 
     68 sxalert can read from standard input:
     69 
     70 	$ sxalert -s < banner.txt
     71 
     72 	$ { printf '%s\n' '===== BUILD FAILED ====='; \
     73 	    tail -n 20 build.log; } \
     74 	  | ./sxalert -s
     75 
     76 Return values
     77 -------------
     78 sxalert returns:
     79 0  - Left click on the notification window
     80 1  - Middle click on the notification window
     81 2  - Right click on the notification window
     82 3  - Time out
     83 
     84 Yes, this does mean that sxalert returns non-zero values even with normal
     85 execution, but for a good reason.  This makes sxalert excellent for shell
     86 scripts. For example:
     87 
     88 You can set your mail to read with an acknowledgment:
     89 
     90 	$ sxalert "New Mail" && mail-set-to-read
     91 
     92 Or you can create a more elaborate interaction:
     93 
     94 	sxalert "New Mail: X" "Left click to set to read" \
     95 		"Middle click to delete" \
     96 		"Right click to close"
     97 	rc=$?
     98 
     99 	case $rc in
    100 	0)
    101 		mail-set-to-read x
    102 		;;
    103 	1)
    104 		mail-delete x
    105 		;;
    106 	2)
    107 		echo "Unread mail"
    108 		;;
    109 	esac
    110 
    111 Optional D-Bus daemon hack
    112 --------------------------
    113 I've created a small Shell script called sxalertd that can run as a pseudo
    114 daemon that intercepts D-Bus and uses sxalert to draw the notifications.
    115 A little hacky but works well enough.
    116 (https://mcdim.xyz/git/sxalertd/log.html) 
    117 
    118 Colophon
    119 --------
    120 Author: Michail Konstantinos Dimopoulos
    121 Copyright (C) 2023, 2026 Michail Konstantinos Dimopoulos
    122 License: GNU General Public License 3.0 or later (GPL-3.0-or-later)
    123          See LICENSE for more information
    124 Patches: <hackers@mcdim.xyz>
    125 
    126 Credit
    127 ------
    128 The logo is the Alectryon! The rooster image is by Leys, Thomson W. from
    129 the 1883 book "Brett's colonists' guide and cyclopaedia" for New Zealand
    130 settlers. The font is Byzantine, and the logo was created in GIMP.