Re: status icon API

[Mark McLoughlin <mark skynet ie>]

Hi,
	So I've spent some more time thinking about the API. Hopefully, the
proposed API below is much closer to the mark than the last (lame) one.

  Some comments:

    * The status icons size is dictated by its container, so
GtkStatusIcon will look after scaling the icons itself.

    * The use case I'm imaging for get_size() and "size_changed" is for
using icon themeing. You'll more than likely want to lookup the icon
which is best suited to the size. The icon themeing spec seems to assume
that icons are square (there's only a single dimension to icon sizes).
I'm matching that here, but is this wise?

    * Perhaps we should just use "notify::size" instead of a
size_changed signal.

    * On windows we have "click", "double-click", "mouse-down",
"mouse-up" and "mouse-move". Also, it seems that in earlier versions
activating an icon with the keyboard caused the shell to synthesis
button press and release events. In more recent version, special
keyboard activation messages are sent.

    * We could allow all of these events and provide
"button-press-event", "button-release-event", "motion-notify-event",
"enter-notify-event" and "leave-notify-event". We would probably also
provide an "activate" signal for keyboard activation.

    * Alternatively, we could just define the desired behaviour and
tailor the API around that. E.g. just provide an "activate" signal which
is invoked on single-click or double-click and keyboard activation and
some sort of "popup-menu" signal. We could also possibly provide
"enter-notify", "leave-notify" and "motion-notify" for people who want
to do fancy things on mouse-over.

    * I prefer the later approach because it at least ensures we have
consistent behaviour. We also have the option to vary that behaviour
between X and Win32 so that we get it right on both platforms.  

    * We can't use GtkTooptips here. I think set/get_tooltip() should be
sufficient.

    * I've just added the standard (as used for gtk_menu_popup()) button
and activate_time parameters to the "popup_menu" signal. Is that
sufficient?  Owen mentions that the x,y co-ordinates of the event might
be useful for positioning, but I'm unclear as to why.

    * I've added API for balloon messages. Perhaps we should just forget
about handling these in the protocol and just do it toolkit-side
instead.  Should we allow the timeout for balloon messages to be
configured or just enforce that policy.

    * I've kept the "blinking" API for now. I think its useful for
alerts.


Good Luck,
Mark.

#define GTK_TYPE_STATUS_ICON         (egg_status_icon_get_type ())
#define GTK_STATUS_ICON(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GTK_TYPE_STATUS_ICON, EggStatusIcon))
#define GTK_STATUS_ICON_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST ((k), GTK_TYPE_STATUS_ICON, EggStatusIconClass))
#define GTK_IS_STATUS_ICON(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GTK_TYPE_STATUS_ICON))
#define GTK_IS_STATUS_ICON_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_STATUS_ICON))
#define GTK_STATUS_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_STATUS_ICON, EggStatusIconClass))

typedef struct _GtkStatusIcon      GtkStatusIcon;
typedef struct _GtkStatusIconClass GtkStatusIconClass;

struct _GtkStatusIcon
{
  GObject parent_instance;
};

struct _GtkStatusIconClass
{
  GObjectClass parent_class;

  void (*activate)     (GtkStatusIcon *status_icon);
  void (*popup_menu    (GtkStatusIcon *status_icon,
			guint          buttton,
			guint32        activate_time);
  void (*size_changed) (GtkStatusIcon *status_icon,
			gint           size);
};

GtkStatusIcon        *gtk_status_icon_new                 (void);
GtkStatusIcon        *gtk_status_icon_new_from_pixbuf     (GdkPixbuf          *pixbuf);
GtkStatusIcon        *gtk_status_icon_new_from_file       (const gchar        *filename);
GtkStatusIcon        *gtk_status_icon_new_from_stock      (const gchar        *stock_id);
GtkStatusIcon        *gtk_status_icon_new_from_animation  (GdkPixbufAnimation *animation);

void                  gtk_status_icon_set_from_pixbuf     (GtkStatusIcon      *status_icon,
							   GdkPixbuf          *pixbuf);
void                  gtk_status_icon_set_from_file       (GtkStatusIcon      *status_icon,
							   const gchar        *filename);
void                  gtk_status_icon_set_from_stock      (GtkStatusIcon      *status_icon,
							   const gchar        *stock_id);
void                  gtk_status_icon_set_from_animation  (GtkStatusIcon      *status_icon,
							   GdkPixbufAnimation *animation);

GtkImageType          gtk_status_icon_get_image_type      (GtkStatusIcon      *status_icon);

GdkPixbuf            *gtk_status_icon_get_pixbuf          (GtkStatusIcon      *status_icon);
G_CONST_RETURN gchar *gtk_status_icon_get_stock           (GtkStatusIcon      *status_icon);
GdkPixbufAnimation   *gtk_status_icon_get_animation       (GtkStatusIcon      *status_icon);

gint                  gtk_status_icon_get_size            (GtkStatusIcon      *status_icon);

void                  gtk_status_icon_set_tooltip         (GtkStatusIcon      *status_icon,
							   const gchar         *tooltip);
G_CONST_RETURN gchar *gtk_status_icon_get_tooltip         (GtkStatusIcon      *status_icon);

void                  gtk_status_icon_set_balloon_text    (GtkStatusIcon      *status_icon,
							   const gchar        *text);
G_CONST_RETURN gchar *gtk_status_icon_get_balloon_text    (GtkStatusIcon      *status_icon);

void                  gtk_status_icon_set_enable_blinking (GtkStatusIcon      *status_icon,
							   gboolean            enable_blinking);
gboolean              gtk_status_icon_get_enable_blinking (GtkStatusIcon      *status_icon);