XNOTIFY(1)

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 &

SEE ALSO
tiramisu(1), herbe(1)