NotificationIcon

Using the Notification API

Yad has a significantly more powerful notification API than it's predecessor Zenity. As well as creating notifications to display in the system tray using GTK, it is also possible to modify the tray icon and it's tray menu.

NOTE: To make use of these features, it is necessary to use version 0.12.2 of the library or greater.

Introduction

Yad is a program designed to be run from a shell environment or as an external process called by an application. As with all of Yad's APIs, the option flags can be looked up through the "--help-all" option or more specifically with the "--help-<api>" option. In the case of the Notification API this is "--help-notification".

For the purpose of these examples #> displays running a command from the terminal.

e.g.

#> yad --help-notification
Usage:
  yad [OPTION...] Yet another dialoging program

Notification icon options
  --notification                                 Display notification
  --command=CMD                                  Set left-click action
  --listen                                       Listen for commands on stdin
  --separator=SEPARATOR                          Set separator character for menu values
  --item-separator=SEPARATOR                     Set separator character for menu items

Creating a Notification

Creating a notification is as simple as:

#> yad --notification &

This will display Yad's default tray notification, executed as a separate process. By default the notification looks like a small science beaker (seen on the Google Code page top left as the logo). The default event handler for the left click (and middle click) from the mouse is to quit (stop yad). The right click handler does nothing.

To add a left click action:

#> yad --notification --command="echo 'Hello World'"

NOTE: This example does not execute yad as a separate process.

To create Yad with a specific tray icon use:

#> yad --notification --image="gtk-help"

Unlike Zenity, the icon naming convention does not look for stock icon names but the names used by the current gtk+ icon theme. To see a list of the icon names currently available in your icon theme, use yad-icon-browser (if built) or see Icon Themes.

A (mildly) more complex example combining a few more option flags is:

#> yad --notification --image="gtk-help" --command="echo 'Hello World'" --text="The notification's tooltip"

Updating a Notification

A powerful feature of Yad is the ability to reconfigure a notification, that's already being displayed. This can be done using the "listen" option flag. Once done, commands are listened for on stdin.

To change the notification icon use:

#> yad --notification --image="gtk-help" --listen
#> icon:gnome-media-play-ltr
#> quit

A full list of the commands can be found on the manpage. Possible commands are icon, tooltip, visible, action, menu and quit.

It's great to be able to control the notification settings from stdin but more useful if the process can manage them and modify them itself. This is possible by redirecting the I/O stream in a shell script.

An example shell script:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

#!/usr/bin/env bash # create a FIFO file, used to manage the I/O redirection from shell PIPE=$(mktemp -u --tmpdir ${0##*/}.XXXXXXXX) mkfifo $PIPE # attach a file descriptor to the file exec 3<> $PIPE # add handler to manage process shutdown function on_exit() { echo "quit" >&3 rm -f $PIPE } trap on_exit EXIT # add handler for tray icon left click function on_click() { echo "clicked" } export -f on_click # create the notification icon yad --notification \ --listen \ --image="gtk-help" \ --text="Notification tooltip" \ --command="bash -c on_click" <&3

Bigger Example

For a bigger example of the notification API, see the USBFlash wiki

[Anonymous]

Originally posted by: de067018@googlemail.com

Hi Ananasik, could you add some useful code to understand better how notification works?

function on_click() {

exec 3<>$0 echo "tooltip:clicked" >&3

} export -f on_click

create the notification icon yad --notification \

--listen \ --image="gtk-help" \ --text="Notification tooltip" \ --command="sh -c on_click $PIPE" <&3 &

[Anonymous]

Originally posted by: tri...@gmail.com

I copy your script above and add a new line 'echo "icon:gtk-about" >&3' to the on_click function. When I click on the notification icon, it outputs "clicked" and "sh: line 1: 3: Bad file descriptor" (the notification icon doesn't change). It looks like I'm having trouble attaching the file descriptor to a file (the 'exec 3<> $PIPE' step). I try to google this but couldn't find much useful info, can you please help? Thanks.

[Anonymous]

Originally posted by: ananasik

bash file descriptors are not exported with function, so if you want to change state of notification icon from exported function, you must reopen $PIPE in functions body. and don't forget to export PIPE too

[Anonymous]

Originally posted by: franco.massimiliano

Using sh i receceived the following error: Syntax error: "(" unexpected This because in ubuntu sh is a simlink to dash.

So to make this script working under ubuntu 11.10 i had to change the shell to bash.

Then I changed this row:

--command="sh -c on_click" <&3 &

to

--command="bash -c 'on_click $PIPE'" <&3

In this way the pipe is directly accessible for the on_click function using the $1 shell variable.

Furthermore i had to add a final 'wait' command, otherwise the script terminates sending the EXIT status that is trapped, activating the on_exit function.

[Anonymous]

Originally posted by: ananasik

thanks, i've fixed this mistakes. instead of final wait i just removed '&' from yad call

[Anonymous]

Originally posted by: franco.massimiliano

it's a pleasure for me give my little help to your great work :)

just a consideration: only deleting the final ampersand inhibits to pass other commands to yad through the pipe. using the ampersand could be possible to do something like this:

echo "menu:Leafpad!leafpad|Catfish!catfish|Exit!quit" >&3

wait

[Anonymous]

Originally posted by: macke...@gmail.com

Hi Victor:

I'm using the yad --notification in a script and see that the above pipe usage will be very helpful. I have a requirement to update the tooltip where I'm display the state of the active node in a cluster when they hover on the tray icon. Can I pass a command to yad via the pipe to do this?

thx a bunch! W. MacKenzie?

[Anonymous]

Originally posted by: macke...@gmail.com

ah ha! I see there is a command using --listen to send tooltip updates...beauty!

[Juanmafont]

All ok with option --notification, but if I try to use a theme with SVG icons, the icons are not show it correctly, they are show as a repetitive pattern.