RE: status icon API

[Owen Taylor <otaylor redhat com>]

On Thu, 2003-04-10 at 06:23, martyn 2 russell bt com wrote:
> > 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.  

Pretty much - see API reference links in my earlier mail.

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

I couldn't find anything in the Microsoft docs in a quick look that
indicated what the desired size was for the icon, or whether there
were restrictions, but that's one thing thing we should consider
adding ... a way of getting (and monitoring for changes) the
desired size.

The nice thing about a named icon form of the API is we can make it
automatically do the right thing, but I don't think that should
be the only API.

> 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);

If you make the icon an object (see below) you can use signals for these
and it's a whole lot more natural. As someone else mentioned (on the
bug report?) I think a "show context menu" signal is a good idea.
(The question about "show context menu" is how to deal with positioning
perhaps it should be a "create context menu" signal instead... perhaps
having x,y coordinates in the event is good enough)

> 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!".

I'd want to leave this out for now, since we don't have the capability
on X. (It was in the original spec, but the KDE people were unhappy with
it.) If we do decide to add it, there needs to be some way of finding
out if it is supported on the system, since if it isn't there, the app
needs to do something different.

> 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?

I think we should allow more than one:
 
 - The API is just a lot cleaner if you have an object with signals
   and properties for the icon; even if only one could be displayed
   at once, I think 

 - A single binary may want to conceptually appear as several
   applications

 - A single application might want to notify for various things 

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

Could you elaborate?

Regards,
                                                             Owen