home | help 
XNOTIFY(1)		     General Commands Manual		      XNOTIFY(1)

NAME
     xnotify - popup a notification on the screen

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

DESCRIPTION
     xnotify is a notification launcher for X, it receives a notification speci-
     fication 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  xno-
	    tify.   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 (dis-
	    play 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 noti-
	    fication 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>][{-+}<XOFF-
	    SET>{-+}<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 num-
	    bers 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 be-
	    fore it is removed from screen.  Without this option, the default of
	    10 seconds is used.  If this option is set to 0 (zero), the  notifi-
	    cation 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 for-
     mat:

	    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 notifi-
     cation, 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 vis-
	    ible.   If set to zero, the notification will stay visible until be-
	    ing 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>{+-}<YOFF-
	    SET>].  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, no-
	    tification 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 trun-
	    cated.

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 notifica-
	    tions before stop.

     SIGCONT
	    Display all accumulated notifications and continue xnotify after be-
	    ing 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 back-
     ground, 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)

								      XNOTIFY(1)
home | help