RE: status icon API

[martyn 2 russell bt com]

> I assume there is no widget involved in the Win32 compatible API aat 
> all... unless you want to make the icon appear as a separate toplevel
> on Windows, which seems very dubious to me.

This is true.  Using a window would not work.  As far as I remember, you can
set the ICON, tooltips and capture mouse clicks.  

The only major downfall (I thought when doing it) was the image size is
quite small (up to something like 24x24 I think).  

The major problem with trying to work the eggsystray code into Windows would
be that Windows does not allow you to put ANY control/widget in the tray -
which the eggsystray code does.  

First thoughts are that the API would be more extensive on Linux and quite
cut down on Windows. Something along the lines of:


	gtk_system_tray_add(GdkPixbuf icon,
				  gchar *tooltip);
	gtk_system_tray_remove();

	gtk_system_tray_set_icon(GdkPixbuf pb); 	/* using NULL for a
transparant icon */				  
	gtk_system_tray_set_icon_from_stock(gchar *stock);
	gtk_system_tray_get_icon(); 

 	gtk_system_tray_set_tooltip(gchar *tooltip); /* max of 64char /
126char(v5) on Windows */
 	gtk_system_tray_set_tooltip_timeout(guint milliseconds);
	gtk_system_tray_get_tooltip();
	gtk_system_tray_get_tooltip_timeout();

 	gtk_system_tray_set_info(gchar *info); /* v5 only, max of 255 char
on Windows */
 	gtk_system_tray_get_info();

	gtk_system_tray_set_created_func(G_CALLBACK(), gpointer user_data);
	gtk_system_tray_set_destroy_func(G_CALLBACK(), gpointer user_data);
	gtk_system_tray_set_button_press_event_func(G_CALLBACK(), gpointer
user_data);


The gtk_system_tray_set_info() is the bubble which popsup to tell the user
what the icon means (I think).  The best example of this I think is when new
hardware is added to you machine on Windows XP or 2k, and it says above the
icon when it is added to the system tray - "New hardware found!".

This API is very limited (i.e. you would only have ONE icon in the system
tray per application).  In most cases, this should be enough.  Do we need to
consider more than one?

> > /* Blink the icon for a set period of time */
> > void                  egg_status_icon_begin_blinking  

I think the idea of an API to set the icon to flash it a little over the
top.  This should be up to the user.  It shouldn't be hard to setup a timer
that simply calls gtk_system_tray_set_icon(NULL) and then
gtk_system_tray_set_icon(myicon) every 750ms or so.

> Hmm, I have to admit that this API doesn't do a whole lot for me. 
> 
> - It's a lot of complexity to accomplish something that might be
>    *easier* for apps to do with a simpler API:
> 
>    egg_status_icon_set_icon (state == CONNECTED ?
>                              connected_icon, disconnected_icon);

Yes this is what I had in mind.

Calling the API above which I briefly covered would look something like
this:

	void load()
	{
		GdkPixbuf *pb = NULL;
		gchar *tooltip = NULL;

		/* get pb and set tooltip */

		gtk_system_tray_add(pb, tooltip);
		gtk_system_tray_set_created_func(G_CALLBACK(created), NULL);
		gtk_system_tray_set_destroy_func(G_CALLBACK(destroyed),
NULL);
	
gtk_system_tray_set_button_press_event_func(G_CALLBACK(button_press_event),
NULL);
	}

	void created(gboolean success, gpointer user_data)
	{
		g_message("system tray %s", success?"created","could not be
created");
	}

	void destroyed(gboolean cleanly, gpointer user_data)
	{
		g_message("system tray %s", cleanly?"destroyed
cleanly","destroyed unexpectedly");
	} 

	void button_press_event(GdkEventButton event, g_pointer user_data)
	{
		g_message("button %d pressed", event->button);
	} 

While on the subject of system trays and that area of the screen.  Should we
consider adding "toasting" into this API? Similar to the ways of MSN
Messenger's notifications.

Thoughts? 

Regards,
Martyn