xnotify.1

.Dd August 24, 2023
.Dt XNOTIFY 1
.Os
.Sh NAME
.Nm xnotify
.Nd popup a notification on the screen
.Sh SYNOPSIS
.Nm xnotify
.Op Fl orw
.Op Fl b Ar button
.Op Fl G Ar gravity
.Op Fl g Ar geometry
.Op Fl h Ar height
.Op Fl m Ar monitor
.Op Fl s Ar seconds
.Sh DESCRIPTION
.Nm
is a notification launcher for X,
it receives a notification specification from standard input
and shows a notification on the screen.
The notification disappears automatically after a given number of seconds
or after a mouse click is operated on it.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar button
Specify a number between 1 and 3 to be the mouse action button.
When clicking over a notification with the action button,
the notification will close, and
.Nm
will write into its standard output the value of the notification's
.Ic "CMD:"
option.
.It Fl G Ar gravity
Specify the gravity, that is, where in the screen to display
.Nm .
The argument
.Ar gravity
can be
.Cm NE
for northeast gravity (display on the top right corner of the screen);
.Cm SW
for southwest gravity (display on the bottom left corner of the screen);
.Cm "C"
for center gravity (display on the center of the screen);
etc.
.It Fl g Ar geometry
Specify the geometry in a format read by
.Xr XParseGeometry 3 .
The height is the minimum height of a notification;
a notification that contains more than one line or an image can get larger than the minimum height.
A value of 0 sets a field to the default value.
.It Fl h Ar height
Maximum height (in pixels) of a notification window.
.It Fl m Ar monitor
Display notification windows on the specified
.Ar monitor
number.
Monitors are counted from 0 (the default).
.It Fl o
Makes only one notification to exist at a time;
so, when a new notification appears, the other ones are removed.
.It Fl r
Watch for notifications in the name of the root window.
This works like how statusbar is set in the
.Xr dwm 1
window manager.
.It Fl s Ar seconds
Specify the time, in seconds, for a notification to be displayed before it is removed from screen.
Without this option, the default of 10 seconds is used.
If this option is set to 0 (zero),
notifications are displayed indefinitely until manually closed.
.It Fl w
Let the window manager control notification windows.
If this flag is set, the options
.Fl G
and
.Fl g
are ignored.
.El
.Pp
Each line read from standard input specify a notification and has the following format:
.Bd -literal -offset indent
[NAME:VALUE TABS] TEXT NEWLINE
.Ed
That means that each line is composed by an optional set of name-value pairs separated by colon
.Pq Ic ":\&"
followed by tabs, then the text of the notification terminated by a newline.
Brackets group optional elements.
Empty lines are ignored.
The text of a notification specification can contain tabs.
Each tab is converted to a line break on the notification.
.Pp
The following names are currently accepted for the
.Ic NAME:VALUE
pairs:
.Bl -tag -width Ds
.It Ic "IMG:"
Specify the path of an image to be displayed on the notification.
.It Ic "TAG:"
Specify a string to be the notification's tag.
When a notification with a given tag spawns,
all other notifications with the same tag disappear.
.It Ic "BG:"
Specify the color of the notification background.
.It Ic "FG:"
Specify the color of the notification text (ie', its foreground).
.It Ic "BAR:"
Specify a percentage for a progress bar to be drawn below the text.
.It Ic "BRD:"
Specify the color of the notification border.
.It Ic "SEC:"
Specify the time, in seconds, that the notification should stay visible.
If set to zero, the notification will stay visible until being clicked.
.El
.Pp
Clicking on a notification removes it from the screen.
.Sh RESOURCES
.Nm
understands the following X resources.
They must be prefixed with either the
.Qq XNotify
class, or the
.Qq xnotify
name, followed by a period.
.Bl -tag -width Ds
.It Ic alignment
If set to
.Qq Ic left
(default),
.Qq Ic center ,
or
.Qq Ic right ,
text is aligned to the left, center or right of the popup window, respectively.
.It Ic alignTop
If set to
.Qq Ic true ,
text is vertically aligned to the top of the notification window.
.It Ic background
The default background color.
.It Ic borderColor
The color of the border around a notification.
.It Ic borderWidth
The size in pixels of the border around a notification.
.It Ic faceName
The font to draw the notification text.
.It Ic foreground
The default text color.
.It Ic gap
The size in pixels of the gap between notifications.
.It Ic geometry
The geometry as specified by the
.Fl g
option.
.It Ic gravity
The gravity as specified by the
.Fl G
option.
.It Ic leading
The size in pixels of the space between lines.
.It Ic maxHeight
The maximum height of a notification in pixels.
.It Ic opacity
Background opacity as a floating point number from 0.0 to 1.0.
.It Ic shrink
If set to
.Qq Ic true ,
the notification width will shrink to its content size.
If set to
.Qq Ic false ,
notification width will be constant.
.It Ic padding
The size in pixels of the space around the content inside the notification popup windows.
.It Ic wrap
If set to
.Qq Ic true,
lines longer than the notification width will wrap rather than being truncated.
.El
.Sh SIGNALS
.Nm
responds to signals sent to it.
.Bl -tag -width Ds
.It Dv SIGHUP
Close all notifications.
.It Dv SIGUSR1
Close the first notification.
.It Dv SIGUSR2
Print the CMD of the first notification, then close it.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
.Bl -tag -width Ds
.It Ev DISPLAY
The display to start
.Nm
on.
.El
.Sh EXAMPLES
The following is an example of how to run XNotify.
.Bd -literal -offset indent
$ xnotify \-m 10 \-G NE \-g \-10+10 \-s 15
.Ed
This line means: read notifications from stdin,
display the notifications on the north east
.Po
.Fl G Cm NE
.Pc
of the monitor 0
.Po
.Fl m Cm 0
.Pc ,
that is, on the upper right corner of the first monitor.
The notifications should be placed -10 pixels to the left and +10 pixels down
(thus creating a 10 pixel gap with the upper right corner).
Each notification stay alive for 15 seconds.
.Pp
To create a named pipe for
Nm ,
the following lines can be placed on
.Pa ~/.xinitrc .
This will create a named pipe unique to the current X display in the home directory at
.Pa ~/.cache .
Then, it will open
.Nm
in the background, reading from this named pipe.
.Bd -literal -offset indent
XNOTIFY_FIFO="$HOME/.cache/xnotify$DISPLAY.fifo"
export XNOTIFY_FIFO
rm \-f $XNOTIFY_FIFO
mkfifo $XNOTIFY_FIFO
xnotify 0<>$XNOTIFY_FIFO &
.Ed
.Pp
Then a notification can be created by echoing into the named pipe:
.Bd -literal -offset indent
$ echo Hello World > $XNOTIFY_FIFO
.Ed
.Pp
To create a notification with a image,
input to
.Nm
a line beginning with
.Ic IMG:/path/to/file.png
followed by a tab.
For example:
.Bd -literal -offset indent
$ printf 'IMG:/path/to/file.png\etHello World!\en' > $XNOTIFY_FIFO
.Ed
.Pp
.Nm
does not read notifications from dbus.
For
.Nm
to read dbus notifications,
its stdin (or the root window's name, if
.Fl r
is used) must be fed with the output of
.Xr tiramisu 1 .
The following line makes
.Xr tiramisu 1
send dbus notifications to
.Nm .
This line can be added to
.Pa ~/.xinitrc
after the line calling
.Nm .
.Bd -literal -offset indent
tiramisu -o "$(printf '#summary\et#body\en')" > $XNOTIFY_FIFO &
.Ed
.Sh SEE ALSO
.Xr tiramisu 1