A cross-platform status icon api

[Matthias Clasen <mclasen redhat com>]

As a first concrete step into Project Ridley, I have looked at the
EggTray API and implementation, and here is what I would like to propose
as a suitable API for GTK+:

The requirement to have an API that can be implemented on all platforms
supported by GTK+ rules out the EggTrayIcon API, since Win32 does not
allow to embed arbitrary windows into the system tray. The EggStatusIcon
API matches pretty well the functionality which can be implemented in
a cross-platform way. There are a few minor (and obvious) additions
which I believe would be worthwhile:

- Allow setting a named icon. We added this API to GtkImage in 2.8
- Implement the popup-menu signal. The implementation is commented out 
  in EggStatusIcon
- Allow showing/hiding status icons without setting an empty image

I have some doubts whether we want to include the following items in the
GtkStatusIcon API:

- Allow showing balloon messages. The EggStatusIcon code for sending 
  balloon messages is currently broken, and they are just thrown away 
  by the current tray implementation anyway. We may want to hold off
  on this until the dust settles after the libnotify discussions...
- Support for making the icon blink. While blinking icons can be 
  annoying and an a11y problem, it may be better to have an official
  API for this (and thus a way to turn off blinking), rather than
  let people do manual, inconsistent blinking...


I'll attach my current header, if you want to have a closer look.


Matthias

/* gtkstatusicon.h:
 *
 * Copyright (C) 2003 Sun Microsystems, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * Authors:
 *      Mark McLoughlin <mark skynet ie>
 */

#ifndef __GTK_STATUS_ICON_H__
#define __GTK_STATUS_ICON_H__

#include <gtk/gtkimage.h>

G_BEGIN_DECLS

#define GTK_TYPE_STATUS_ICON         (gtk_status_icon_get_type ())
#define GTK_STATUS_ICON(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GTK_TYPE_STATUS_ICON, GtkStatusIcon))
#define GTK_STATUS_ICON_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST ((k), GTK_TYPE_STATUS_ICON, GtkStatusIconClass))
#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, GtkStatusIconClass))

typedef struct _GtkStatusIcon	     GtkStatusIcon;
typedef struct _GtkStatusIconClass   GtkStatusIconClass;
typedef struct _GtkStatusIconPrivate GtkStatusIconPrivate;

struct _GtkStatusIcon
{
  GObject               parent_instance;

  GtkStatusIconPrivate *priv;
};

struct _GtkStatusIconClass
{
  GObjectClass parent_class;

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

GType                 gtk_status_icon_get_type           (void) G_GNUC_CONST;

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);
GtkStatusIcon        *gtk_status_icon_new_from_icon_name (const gchar        *icon_name);

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);
void                  gtk_status_icon_set_from_icon_name (GtkStatusIcon      *status_icon,
							  const gchar        *icon_name);

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);
G_CONST_RETURN gchar *gtk_status_icon_get_icon_name      (GtkStatusIcon      *status_icon);

gint                  gtk_status_icon_get_size           (GtkStatusIcon      *status_icon);

void                  gtk_status_icon_set_tooltip        (GtkStatusIcon      *status_icon,
							  const gchar        *tooltip_text,
							  const gchar        *tooltip_private);

void                  gtk_status_icon_set_visible        (GtkStatusIcon      *status_icon,
							  gboolean            visible);
gboolean              gtk_status_icon_get_visible        (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_is_blinking    (GtkStatusIcon      *status_icon,
							  gboolean            enable_blinking);
gboolean              gtk_status_icon_get_is_blinking    (GtkStatusIcon      *status_icon);

G_END_DECLS

#endif /* __GTK_STATUS_ICON_H__ */