Re: status icon API

[Owen Taylor <otaylor redhat com>]

On Tue, 2003-04-08 at 21:22, Mark McLoughlin wrote:

> 	Okay, so I've done some work on a simple API for adding icons to the
> Notification Area. Its in libegg. But it sucks in its current form:
> 
> 	* Its currently geared towards "status icons" - that is, an icon that
> remains in the notification area while the app is running and the app
> switches the icon around as some status changes. It needs an API for an
> icon that is added and removed as a certain event occurs ...
> 
> 	* The API for setting an array of icons and then using a status
> identifier to index into the array sucks. Couldn't think of a nicer way
> to do it.
> 
> 	But anyway, its a start - I've appended it below.
> 
> 	I've only ever had a quick look at the Win32 API for this, but my
> interpretation was similar to what Havoc says in #105101. I think the
> API below could be implemented in Win32, but I'd be very interested to
> hear from someone who actually knows what they're talking about :-)

MSDN references:

 Win32 API:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/functions/shell_notifyicon.asp

 WinForms API:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemWindowsFormsNotifyIconClassTopic.asp

> 	As regards this API limiting people on X11, maybe gtk+ on X11 could
> also ship something similar to EggTrayIcon (effectively only an
> implementation of the protocol). That way people can do their fancy
> embedding if they want, but they know they are limiting themselves to
> X11 only - in a similar way to GtkPlug/Socket. Hmm, its just occurred to
> me that that would mean the widget would sub-class different widgets on
> Win32 and X11. Ouch.

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.

As for shipping something like EggTrayIcon as part of GTK+ ... I think
that only makes sense if there things that many application will 
want to do which we can't make part of the portable API. 

Of course, we'll have something like EggTrayIcon inside GTK+, so the
question would be whether to install the headers / export the
functions or not; my instinct would be "no, and if people complain, we
can reconsider for the next release"

> struct _EggStatusIcon
> {
>   EggTrayIcon           tray_icon;
> 
>   EggStatusIconPrivate *priv;
> };
> 
> struct _EggStatusIconClass
> {
>   EggTrayIconClass parent_class;
> 
>   void (* activate)   (EggStatusIcon *icon);
>   void (* popup_menu) (EggStatusIcon *icon);
> };
> 
> GType               egg_status_icon_get_type        (void);
> 
> /* Pass in a list of icon names (looked up according to the
>  * icon theme) or icon paths.
>  */
> GtkWidget           *egg_status_icon_new             (gchar         **icons,
> 						      guint           n_icons);
> 
> /* Set the currently displayed icon using an index into the array
>  * of status icons. Most applications would probably use a status
>  * enum as an indexer.
>  */
> void                 egg_status_icon_set_status      (EggStatusIcon  *status_icon,
> 						      guint           status);
> /* Gets the current status */
> guint                egg_status_icon_get_status      (EggStatusIcon  *status_icon);
> 
> /* Set the list of status icons */
> void                 egg_status_icon_set_icons       (EggStatusIcon  *status_icon,
> 						      gchar         **icons,
> 						      guint           n_icons);
> /* Retrieve the list of status icons */
> gchar              **egg_status_icon_get_icons       (EggStatusIcon  *status_icon,
> 						      guint          *n_icons);
> 
> /* Set an individual icon */
> void                  egg_status_icon_set_icon        (EggStatusIcon  *status_icon,
> 						       guint           status,
> 						       const gchar    *icon);
> /* Retrieve an individual icon */
> G_CONST_RETURN gchar *egg_status_icon_get_icon        (EggStatusIcon  *status_icon,
> 						       guint           status);
> 
> /* Blink the icon for a set period of time */
> void                  egg_status_icon_begin_blinking  (EggStatusIcon  *status_icon);
> /* Blink the icon indefinetly */
> void                  egg_status_icon_set_is_blinking (EggStatusIcon  *status_icon,
> 						       gboolean        is_blinking);
> /* Determine if the icon is currently blinking */
> gboolean              egg_status_icon_get_is_blinking (EggStatusIcon  *status_icon);

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

- It seems to restrict lots of things that you *can* do on Win32,
   like, say, a battery monitor icon filled to a certain percentage.

I'd guess that the right API has:

 - A way of setting the icon from a pixbuf (and in the future,
   once we have named themed icon support from an named
   theme icon)

 - Some basic set of events for mouse/key events.

 - Support for tooltips and context menus of some type.

Regards,
                                               Owen