commit f5a66e22aad9ed70c7ab678ffce9d461de4c5ef2 from: Brett Fisher date: Thu Jun 18 06:25:28 2026 UTC LICENSE.md, README.md, bxnotify.1: Add user-facing documentation. - Adopt ISC licnese. - Create README.md detailing build, configuration, and usage. - Create bxnotify.c manual page. commit - a08809ec69ae6dd0ca37a31535b8a0a3405883e5 commit + f5a66e22aad9ed70c7ab678ffce9d461de4c5ef2 blob - /dev/null blob + b8f255dd8f977ad1b4601febec24e7bf8907145e (mode 644) --- /dev/null +++ LICENSE.md @@ -0,0 +1,20 @@ +# LICENSE + +[ISC License](https://opensource.org/licenses/ISC) + +Copyright (c) 2026 Brett Fisher + +Permission to use, copy, modify, and/or distribute this software for +any purpose with or without fee is hereby granted, provided that the +above copyright notice and this permission notice appear in all +copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL +WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE +AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA +OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. + blob - /dev/null blob + 5cc5c3bf3826bb736024de6164f49ec6f8094ecb (mode 644) --- /dev/null +++ README.md @@ -0,0 +1,102 @@ +# bxnotify + +A very basic X notification tool. + +## Just a Heads-Up + +I needed a way to display a short message on screen from a shell +script or a Lua program. I did not need a notification daemon, a +dbus service, or a background process. I just needed a small +program that reads text from stdin and shows it. + +bxnotify is the result: a one-shot notification renderer. Each +invocation displays a single notification, then exits. Concurrent +invocations stack vertically, so multiple notifications can be +visible at once. + +## Dependencies + +- Xlib +- Xft +- A C compiler compliant with the C11 standard. + +## Build + +Compile __bxnotify__ from source. + +``` +make +``` + + +## Install + +Install the binary and man page. Note that root privileges are not +required as the default destination is `~/.local/`. + +``` +make install +``` + + +## Uninstall + +Remove the binary and man page. + +``` +make uninstall +``` + + +## Configuration + +__bxnotify__ is configured at compile-time by editing config.def.h. +After making changes, the program must be recompiled and +reinstalled. See bxnotify(1) for details. + +Command line flags override configuration defaults for font, +colors, alignment, and duration. + +## Design & Functionality + +__bxnotify__ is built around a set of opinionated primitives: + +- One-shot renderer: reads from stdin, shows a notification, exits +- Concurrent notifications stack vertically +- Auto-sized height based on the number of input lines +- Word wraps long lines to fit the configured width +- Dismissed with Mod4+q (sends SIGUSR1 to the owning process) +- Configurable duration in seconds (0 = persist until dismissed) +- Runtime registry at `~/.local/tmp/bxnotify.reg` for stacking, + coordinated with flock(2) and pruned with kill(2) + +## Usage + +Send a notification from the shell. + +``` +echo “Notify me about this” | bxnotify +``` + +Send a multi-line notification. + +``` +printf “Notify me about this\nNotify me about that” | bxnotify +``` + +Send a notification with a custom duration. + +``` +echo “Notify me for a long time” | bxnotify -d 30 +``` + +Send a notification from a Lua script. + +``` +os.execute("echo 'Notify me about this' | bxnotify") +``` + +When used with bxwm(1) and bxbar(1), bxnotify complements the +suite by providing visual feedback for system events and scripts +without requiring dbus or a notification daemon. + blob - /dev/null blob + a0711aa0b60a286a5659e9a8fd75c182e05ecd50 (mode 644) --- /dev/null +++ bxnotify.1 @@ -0,0 +1,109 @@ +.Dd June 18, 2026 +.Dt BXNOTIFY 1 +.Os +.Sh NAME +.Nm bxnotify +.Nd basic X notification tool +.Sh SYNOPSIS +.Nm +.Op Fl d Ar duration +.Op Fl f Ar font +.Op Fl F Ar foreground +.Op Fl B Ar background +.Op Fl C Ar border +.Op Fl a Ar alignment +.Sh DESCRIPTION +.Nm +is a notification tool for the X11 window system that reads text +from standard input and displays it as a transient pop-up window +at the top right of the screen. +.Nm +is a one-shot renderer: each invocation displays a single +notification, then exits after the configured duration or when +dismissed by the user. Concurrent invocations of +.Nm +stack vertically on screen, with new notifications appearing +below existing ones. +.Sh OPERATION +.Nm +manages notifications in the following manner: +.Bl -tag -width indent +.It Sy Input Processing +.Nm +reads lines from standard input using +.Xr getline 3 . +Lines longer than the configured width are word-wrapped. If no +input is received, the program exits with an error. +.It Sy Window Placement +The notification window is created as an override-redirect +window positioned at the top right of the screen, offset from the +right edge by +.Dv WIN_X +pixels. +.It Sy Stacking +Concurrent notifications are stacked vertically. +.Nm +maintains a registry of active instances at +.Pa ~/.local/tmp/bxnotify.reg , +using +.Xr flock 2 +to coordinate concurrent access. Each instance records its PID, +Y position, and height. Dead processes are detected and pruned +with +.Xr kill 2 . +.It Sy Duration +Notifications persist for +.Dv DURATION +seconds. A duration of 0 causes the notification to persist until +dismissed. +.It Sy Dismissal +The oldest visible notification can be dismissed by pressing +Mod4+q. If the press is received by a different instance of +.Nm , +that instance sends +.Dv SIGUSR1 +to the owning process, which exits gracefully. +.El +.Sh OPTIONS +.Bl -tag -width indent +.It Fl d Ar duration +Set the duration in seconds before the notification expires. A +value of 0 means the notification persists until dismissed. +.It Fl f Ar font +Set the Xft font description string. +.It Fl F Ar foreground +Set the foreground (text) color, as an X color name or hex string. +.It Fl B Ar background +Set the background color, as an X color name or hex string. +.It Fl C Ar border +Set the border color, as an X color name or hex string. +.It Fl a Ar alignment +Set text alignment: 0 = left, 1 = center, 2 = right. +.El +.Sh CONFIGURATION +.Nm +is configured at compile-time by modifying the +.Pa config.def.h +header file. +After modifying this file, +.Nm +must be recompiled and reinstalled to apply changes. +The configuration file defines the default window width, screen +offset, padding, border width, colors, font, alignment, and +duration. +.Sh FILES +.Bl -tag -width ".Pa ~/.local/tmp/bxnotify.reg" -compact +.It Pa config.def.h +The default configuration file (see CONFIGURATION). +.It Pa ~/.local/tmp/bxnotify.reg +The runtime registry used to coordinate stacking of concurrent +notifications. +.El +.Sh SEE ALSO +.Xr bxwm 1 , +.Xr bxhkd 1 , +.Xr bxbar 1 , +.Xr X 7 +.Sh AUTHOR +.An "Brett Fisher ." +