NAME

xnotify - popup a notification on the screen

SYNOPSIS

xnotify [-ow] [-G gravity] [-b button] [-g geometry] [-h height] [-m monitor] [-s seconds]

DESCRIPTION

xnotify 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.

The options are as follows:

-G gravity: Specify the gravity, that is, where in the screen to display xnotify. gravity can be "NE" for NorthEastGravity (display on the top right corner of the screen); "SE" for SouthEastGravity (display on the bottom right corner of the screen); "C" for CenterGravity (display on the center of the screen); etc.
-b button: Specifies a number between 1 and 5 to be the mouse action button. When clicking over a notification with the action button, the notification will close, and xnotify will output to its stdout the value of the notification's CMD: option.
-g geometry: Specifies the geometry in the form [<WIDTH>x<HEIGHT>][{-+}<XOFFSET>{-+}<YOFFSET>]. Replace <WIDTH> by the desired width, <HEIGHT> by the desired minimum height, and so on. The height is the minimum height of a notification; a notification that contains a more than one line or an image can get bigger than this minimum height. A value of 0 sets a field to the default value. So, for example, -g 0x80+0+0 set the minimum height to 80 pixels while maintaining other values to the default. <XOFFSET> and <YOFFSET> can be preceded by either a minus or a plus (meaning negative or positive values). Fields in square brackets are optional. So, for example, -g 0x80 is the same as -g 0x80+0+0; and -g -10+10 is the same as -g 0x0-10+10.
-h height: Maximum height (in pixels) of a notification window.
-m monitor: Makes xnotify be displayed on the specified monitor. Monitor numbers start from 0. Without this option, xnotify is displayed on the first monitor (that is, the monitor 0).
-o: With this option, only one notification should exist at a time. So, when a new notification appears, the other ones are removed.
-s 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), the notification is displayed indefinitely until manually closed.
-w: Let the window manager control notification windows.

Each line read from stdin specify a notification and has the following format:

ITEM := [NAME:VALUE TABS] TEXT NEWLINE

That means that each line is composed by an optional set of name-value pairs separated by colon (:) followed by tabs, then the text of the notification, then 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.

The following names are currently accepted for the NAME:VALUE pairs:

IMG:: Specify the path of a image to be displayed on the notification.
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 disappears.
CMD:: Specify a string to be output when clicking on the notification with the action mouse button.
BG:: Specify the color of the notification background.
FG:: Specify the color of the notification text (i.e., its foreground).
BAR:: Specify a percentage for a progress bar to be drawn below the text.
BRD:: Specify the color of the notification border.
SEC:: Specify the time, in seconds, that the notification should stay visible. If set to zero, the notification will stay visible until being clicked.

Clicking on a notification removes it from the screen.

ENVIRONMENT

The following environment variables affect the execution of xnotify

DISPLAY: The display to start xnotify on.

RESOURCES

xnotify understands the following X resources.

xnotify.title.faceName: The fonts to draw the notification title text. The title is the first line of the notification, if there is more than one. More than one font can be specified, separated by comma (,). If more than one font is specified, the first font with a given glyph is used to display that glyph on the screen.
xnotify.body.faceName: The fonts to draw the notification body text. The body text is any line after the first line.
xnotify.background: The color of the notification background.
xnotify.foreground: The color of the notification text.
xnotify.border: The color of the border around a notification.
xnotify.geometry: The geometry in the form [<WIDTH>x<HEIGHT>][{+-}<XOFFSET>{+-}<YOFFSET>]. See the description of the option -g for more information.
xnotify.gravity: Where in the screen to display notifications. See the description of the option -G for more information.
xnotify.borderWidth: The size in pixels of the border around a notification.
xnotify.maxHeight: The maximum height of a notification window in pixels.
xnotify.gap: The gap between notifications.
xnotify.imageWidth: The size of the image attached to the notification.
xnotify.leading: The space between lines.
xnotify.padding: The space around the content inside the notification popup window.
xnotify.shrink: If set to "true", the notification width will shrink to its content size. If set to "false", notification width will be constant.
xnotify.alignment: If set to "left", "center", or "right", text is aligned to the left, center, or right of the popup window, respectively. By default, notification text is aligned to the left of the notification popup window.
xnotify.alignTop: If set to "true", The text will be vertically aligned to the top of the notification window. If set to "false", text will be vertically centered.
xnotify.wrap: If set to "true", lines longer than the notification width will wrap rather than being truncated. If set to "false", lines will be truncated.

SIGNALS

xnotify respond to signals sent to it.

SIGHUP: Close all notifications.
SIGUSR1: Close the first notification.
SIGUSR2: Print the CMD of the first notification and then close it.
SIGSTOP: Stop xnotify. When this signal is sent, all new notifications are accumuled until xnotify receive a SIGCONT signal. This signal is useful to be sent when a window is fullscreen, so xnotify will not annoy with notifications on top of the fullscreen window. A SIGHUP signal must be sent before a SIGSTOP in order to close all notifications before stop.
SIGCONT: Display all accumulated notifications and continue xnotify after being stop with SIGSTOP.

EXAMPLES

The following is an example of how to run XNotify.

$ xnotify -m 10 -G NE -g -10+10 -s 15

This line means: read notifications from stdin, display the notifications on the north east (-G NE) of the monitor 0 (-m 0), 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.

To create a named pipe for XNotify, the following lines can be placed on ~/.xinitrc. This will create a named pipe unique to the current X display in the home directory at ~/.cache. Then, it will open xnotify in the background, reading from this named pipe.

XNOTIFY_FIFO="$HOME/.cache/xnotify$DISPLAY.fifo"
export XNOTIFY_FIFO
rm -f $XNOTIFY_FIFO
mkfifo $XNOTIFY_FIFO
xnotify 0<>$XNOTIFY_FIFO &

Then a notification can be created by echoing into the named pipe:

$ echo Hello World > $XNOTIFY_FIFO

To create a notification with a image, input to XNotify a line beginning with IMG:/path/to/file.png followed by a tab. For example:

$ printf 'IMG:/path/to/file.png\tThis is a notification\n' > $XNOTIFY_FIFO

xnotify does not read notifications from dbus. For xnotify to read dbus notifications, its stdin must be fed with the output of tiramisu(1). The following line makes tiramisu(1) send dbus notifications to xnotify. This line can be added to ~/.xinitrc after the line calling xnotify.

tiramisu -o "$(printf '#summary\t#body\n')" > $XNOTIFY_FIFO &