Tiré de GTK+ Reference Manual

GtkStatusIcon

GtkStatusIcon — Affiche une icône dans la  zone du système tray 

Synopsis

#include <gtk/gtk.h>


GtkStatusIcon;
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_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_icon_name (GtkStatusIcon *status_icon,
const gchar *icon_name);
GtkImageType gtk_status_icon_get_storage_type (GtkStatusIcon *status_icon);
GdkPixbuf* gtk_status_icon_get_pixbuf (GtkStatusIcon *status_icon);
const gchar* gtk_status_icon_get_stock (GtkStatusIcon *status_icon);
const gchar* gtk_status_icon_get_icon_name (GtkStatusIcon *status_icon);
gint gtk_status_icon_get_size (GtkStatusIcon *status_icon);
void gtk_status_icon_set_screen (GtkStatusIcon *status_icon,
GdkScreen *screen);
GdkScreen* gtk_status_icon_get_screen (GtkStatusIcon *status_icon);
void gtk_status_icon_set_tooltip (GtkStatusIcon *status_icon,
const gchar *tooltip_text);
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_blinking (GtkStatusIcon *status_icon,
gboolean blinking);
gboolean gtk_status_icon_get_blinking (GtkStatusIcon *status_icon);
gboolean gtk_status_icon_is_embedded (GtkStatusIcon *status_icon);
void gtk_status_icon_position_menu (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data);
gboolean gtk_status_icon_get_geometry (GtkStatusIcon *status_icon,
GdkScreen **screen,
GdkRectangle *area,
GtkOrientation *orientation);

Hiérarchie de l'Objet

  GObject
+----GtkStatusIcon

Propriétés

  "blinking"                 gboolean              : Lire / Ecrire 
"embedded" gboolean : Lire
"file" gchararray : Ecrire
"icon-name" gchararray : Lire / Ecrire
"orientation" GtkOrientation : Lire
"pixbuf" GdkPixbuf : Lire / Ecrire
"screen" GdkScreen : Lire / Ecrire
"size" gint : Lire
"stock" gchararray : Lire / Ecrire
"storage-type" GtkImageType : Lire
"visible" gboolean : Lire / Ecrire

Signaux

  "activate"                                       : Exécuter Premier / Action
"popup-menu" : Exécuter Premier / Action
"size-changed" : Exécuter Dernier

Description

Le "system tray" ou l'aire de notification est normalement utilisé pour afficher des icônes transitoires qui indiquent certains états spéciaux. Par exemple, une icône du système tray peut apparaître pour dire à l'utilisateur qu'il a reçu un nouveau message électronique, ou un message instantané entrant, ou quelque chose de ce genre. L'idée de base est que la création d'une icône dans l'aire de notification est moins génante qu'un message déroulant.

Un objet  GtkStatusIcon peut être utilisé pour afficher une icône dans le "system tray". L'icône peut être associée à une bulle d'aide, et l'utilisateur peut interagier avec elle en l'activant ou en déroulant un m enu de contexte. The icon can have a tooltip, and the user can interact with it by activating it or popping up a context menu. Les information importante ne devraient pas être affichée dans un GtkStatusIcon, puisqu'il peut ne pas être visible ( par exemple si l'utilisateur n'a pas affiché l'aire de notification sur son bureau ). Cela peut être contrôlé avec gtk_status_icon_is_embedded().

Sur X11, l'implémentation suit la caractéristique  du  "System Tray" freedesktop.org. Les implémentations côté "tray" de ces caractéristiques peuvent être trouvées par exemple dans les applications du panel de  GNOME et de  KDE. 

Notez qu'un  GtkStatusIcon n'est pas  un  widget, mais seulement un  GObject. En faire un widget est impossible puisque le système tray sur Win 32 ne permet pas d'inclure des widgets.

Détails

GtkStatusIcon


typedef struct _GtkStatusIcon GtkStatusIcon;

gtk_status_icon_new ()


GtkStatusIcon*      gtk_status_icon_new                 (void);

Crée un objet d'icône de statut vide.

Retourne : un nouveau GtkStatusIcon

Depuis 2.10


gtk_status_icon_new_from_pixbuf ()


GtkStatusIcon*      gtk_status_icon_new_from_pixbuf     (GdkPixbuf *pixbuf);

Crée une icône de statut affichant un pixbuf.

L'image sera réduite si nécessaire pour entrer dans l'espace disponible dans l'aire de notification.

pixbuf : un GdkPixbuf
Retourne : un nouveau GtkStatusIcon

Depuis 2.10


gtk_status_icon_new_from_file ()


GtkStatusIcon*      gtk_status_icon_new_from_file       (const gchar *filename);

Crée une icône de statut affichant un fichier  filename.

L'image sera réduite si nécessaire pour entrer dans l'espace disponible dans l'aire de notification.

filename : un nom de fichier
Retourne : un nouveau GtkStatusIcon

Depuis 2.10


gtk_status_icon_new_from_stock ()


GtkStatusIcon*      gtk_status_icon_new_from_stock      (const gchar *stock_id);

Crée une icône de statut affichant un icône de stock. Les échantillons de noms d'icône sont  GTK_STOCK_OPEN, GTK_STOCK_QUIT. Vous pouvez enregistrer vos propres noms d'icône de stock, voir gtk_icon_factory_add_default() et gtk_icon_factory_add().

stock_id : un id d'icône de stock
Retourne : un nouveau GtkStatusIcon

Depuis 2.10


gtk_status_icon_new_from_icon_name ()


GtkStatusIcon*      gtk_status_icon_new_from_icon_name  (const gchar *icon_name);

Crée une icône de statut affichant une icône du thème d'icône courant. Si le thème d'icône courant est changé, l'icône sera mise à jour de façon approprié.

icon_name : un nom d'icône
Retourne : un nouveau  GtkStatusIcon

Depuis 2.10


gtk_status_icon_set_from_pixbuf ()


void                gtk_status_icon_set_from_pixbuf     (GtkStatusIcon *status_icon,
GdkPixbuf *pixbuf);

Fait en sorte que  status_icon affiche un pixbuf. Voir gtk_status_icon_new_from_pixbuf() pour plus de détails.

status_icon : un GtkStatusIcon
pixbuf : un GdkPixbuf ou NULL

Depuis 2.10


gtk_status_icon_set_from_file ()


void                gtk_status_icon_set_from_file       (GtkStatusIcon *status_icon,
const gchar *filename);

Fait en sorte que status_icon affiche un fichier  filename. Voir gtk_status_icon_new_from_file() pour plus de détails.

status_icon : un GtkStatusIcon
filename : nom de fichier

Depuis 2.10


gtk_status_icon_set_from_stock ()


void                gtk_status_icon_set_from_stock      (GtkStatusIcon *status_icon,
const gchar *stock_id);

Fait en sorte que status_icon affiche une icône de stock avec un identifiant stock_id. Voir gtk_status_icon_new_from_stock() pour plus de datails.

status_icon : un GtkStatusIcon
stock_id : identifiant de l'icône de stock

Depuis 2.10


gtk_status_icon_set_from_icon_name ()


void                gtk_status_icon_set_from_icon_name  (GtkStatusIcon *status_icon,
const gchar *icon_name);

Fait en sorte que status_icon affiche l'icône nommée icon_name du thème d'icône courant. Voir gtk_status_icon_new_from_icon_name() pour plus de détails. 

status_icon : un GtkStatusIcon
icon_name : un nom d'icône

Depuis 2.10


gtk_status_icon_get_storage_type ()


GtkImageType        gtk_status_icon_get_storage_type    (GtkStatusIcon *status_icon);

Renvoie le type de représentation utilisée par le  GtkStatusIcon pour stocker les données de l'image.Si le  GtkStatusIcon ne posséde pas de données image, la valeur retournée sera  GTK_IMAGE_EMPTY.

status_icon : un GtkStatusIcon
Retourne : représentation de l'image qui est utilisée

Depuis 2.10


gtk_status_icon_get_pixbuf ()


GdkPixbuf*          gtk_status_icon_get_pixbuf          (GtkStatusIcon *status_icon);

Renvoie le  GdkPixbuf affiché par le  GtkStatusIcon. Le type de stockage de l'icône de statut doit être  GTK_IMAGE_EMPTY ou GTK_IMAGE_PIXBUF (voir gtk_status_icon_get_storage_type()). L'appelant de cette fonction ne possède pas de référence pour le pixbuf retourné. 

status_icon : un GtkStatusIcon
Retourne : pixbuf affiché, ou  NULL si l'image est vide.

Depuis 2.10


gtk_status_icon_get_stock ()


const gchar*        gtk_status_icon_get_stock           (GtkStatusIcon *status_icon);

Renvoie l'identifinat de l'icône de stock affichée par le GtkStatusIcon. Le type de stockage de l'icône doit être  GTK_IMAGE_EMPTY ou GTK_IMAGE_STOCK (voir gtk_status_icon_get_storage_type()). La chaîne retournée appartient au  GtkStatusIcon et ne doit pas être libérée ni modifiée.

status_icon : un GtkStatusIcon
Retourne : identifiant de l'icône de stock affichée, ou NULL si l'image est vide.

Depuis 2.10


gtk_status_icon_get_icon_name ()


const gchar*        gtk_status_icon_get_icon_name       (GtkStatusIcon *status_icon);

Renvoie le nom de l'icône affichée par  GtkStatusIcon. Le type de stockage de l'icône de statut doit être  GTK_IMAGE_EMPTY ou GTK_IMAGE_ICON_NAME (voir gtk_status_icon_get_storage_type()). La chaîne retournée appartient au  GtkStatusIcon et ne doit pas être libérée ni modifiée.

status_icon : un GtkStatusIcon
Retourne : identifiant de l'icône  affichée, ou NULL si l'image est vide.

Depuis 2.10


gtk_status_icon_get_size ()


gint                gtk_status_icon_get_size            (GtkStatusIcon *status_icon);

Renvoie la taille valide en pixels pour l'image. Les icône de stock et les icônes nommées adaptent leur taille automatiquement si la taille de l'air de notification change. Pour les autres types de stckage, le signal size-changed peut être utilisé pour réagir au changement de taille.

status_icon : un GtkStatusIcon
Retourne : taille valide pour une image.

Depuis 2.10


gtk_status_icon_set_screen ()


void                gtk_status_icon_set_screen          (GtkStatusIcon *status_icon,
GdkScreen *screen);

Définit le  GdkScreen où status_icon est affichée ; si l'icône est déjà mappée, elle sera  (unmapped),et remappée sur le nouvel écran.

status_icon : un GtkStatusIcon
screen : un GdkScreen

Depuis 2.12


gtk_status_icon_get_screen ()


GdkScreen*          gtk_status_icon_get_screen          (GtkStatusIcon *status_icon);

Retourne le GdkScreen associé avec  status_icon.

status_icon :
Retourne : un GdkScreen.

Depuis 2.12


gtk_status_icon_set_tooltip ()


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

Définit la bulle d'aide de l'icône de statut.

status_icon : un GtkStatusIcon
tooltip_text : teste de la bulle d'aide,ou  NULL

Depuis 2.10


gtk_status_icon_set_visible ()


void                gtk_status_icon_set_visible         (GtkStatusIcon *status_icon,
gboolean visible);

Montre ou cache l'icône de statut.

status_icon : un GtkStatusIcon
visible : TRUE pour montrer l'icône de statut, FALSE pour la cacher

Depuis 2.10


gtk_status_icon_get_visible ()


gboolean            gtk_status_icon_get_visible         (GtkStatusIcon *status_icon);

Retourne si l'icône de statut est vible ou non. Noter que le fait qu'elle soit visible ne garantit pas que l'utilisateur la voit, voir aussi  gtk_status_icon_is_embedded().

status_icon : un GtkStatusIcon
Retourne : TRUE si l'icône de statut est visible

Depuis 2.10


gtk_status_icon_set_blinking ()


void                gtk_status_icon_set_blinking        (GtkStatusIcon *status_icon,
gboolean blinking);

Fait en sorte que l'icône de statut commence ou arrête de clignoter. Notez que le cloignotement d'éléments sur l'interface   peut géner certains utilisateurs et peut être éteint ainsi; dans certains cas cette configuration n'a pas d'effet.

status_icon : un GtkStatusIcon
blinking : TRUE pour permettre le clignotement, FALSE pour l'éteindre

Depuis 2.10


gtk_status_icon_get_blinking ()

gboolean            gtk_status_icon_get_blinking        (GtkStatusIcon *status_icon);

Retourne si l'icône clignote, voir gtk_status_icon_set_blinking().

status_icon : a GtkStatusIcon
Retourne : TRUE if the icon is blinking

Depuis 2.10


gtk_status_icon_is_embedded ()


gboolean            gtk_status_icon_is_embedded         (GtkStatusIcon *status_icon);

Retourne si l'icône de statut est incluse dans l'aire de notification.

status_icon : un GtkStatusIcon
Retourne : TRUE si l'icône de statut est incluse dans l'aire de notification

Depuis 2.10


gtk_status_icon_position_menu ()


void                gtk_status_icon_position_menu       (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data);

Fonction de positionnement de menu à employer avec gtk_menu_popup() pour mettre en place  menu aligné sur user_data de l'icône de statut.

menu : le GtkMenu
x : localisation retourné pour la position x
y : localisation retourné pour la position y
push_in : localisation retournée si le menu doit être pushed in to be completely inside the screen instead of just clamped to the size to the screen.
user_data : icône de statut dans laquelle le menu sera placé

Depuis 2.10


gtk_status_icon_get_geometry ()


gboolean            gtk_status_icon_get_geometry        (GtkStatusIcon *status_icon,
GdkScreen **screen,
GdkRectangle *area,
GtkOrientation *orientation);

Obtient des informations au sujet de la localisation de l'icône de statut dans l'écran. Ces informations peuvent être utilisées par exemple pour positionner un popup,  comme des bulles de notification.

Voir gtk_status_icon_position_menu() pour avoir plus d'informations pratiques sur le positionnement des menus.

Notes que certaines plateformes ne permettent pas à GTK+ de fournir ces information, et même sur les plateformes qui le permettent, les informations ne sont pas fiables à moins que l'icône de statut soit incluse dans l'aire de notification, voir gtk_status_icon_is_embedded().

status_icon : un GtkStatusIcon
screen : localisation retournée pour l'écran, ou  NULL si l'information n'est pas nécessaire.
area : localisation retournée pour l'aire occupée par l'icône de statut, ou NULL
orientation : localisation retournée pour l'orientation du tableau qui contient l'icône de statut , ou  NULL. Un tableau en haut ou en bas de l'écran est horizontal, un panneau à gauche ou à droite est vertical.
Retourne : TRUE si l'information de  localisation a été complétée.

Depuis 2.10

Détails des Propriétés

La propriété  "blinking


"blinking"                 gboolean              : Lire / Ecrire 

Si l'icône clignote ou non.

Valeur par défaut: FALSE


La propriété  "embedded


  "embedded"                 gboolean              : Lire

TRUE si l'icône de statut est contenue dans l'air de notification.

Valeur par défaut: FALSE

Depuis 2.12


La propriété  "file


  "file"                     gchararray            : Ecrire

Nom de fichier à charger et à afficher.

Valeur par défaut: NULL


La propriété  "icon-name


  "icon-name"                gchararray            : Lire / Ecrire 

nom de l'icône du thème d'icônes.

Valeur par défaut: NULL


La propriété  "orientation


  "orientation"              GtkOrientation        : Lire

Orientation de l'aire de notification dans laquelle l'icône de statue est contenue.

Valeur par défaut: GTK_ORIENTATION_HORIZONTAL

Depuis 2.12


La propriété  "pixbuf


  "pixbuf"                   GdkPixbuf             : Lire / Ecrire 

 GdkPixbuf a afficher.


La propriété  "screen


  "screen"                   GdkScreen             : Lire / Ecrire 

Ecran où l'icône de statut sera affichée.


La propriété  "size


  "size"                     gint                  : Lire

Taille de l'icône.

Valeurs possibles : >= 0

Valeur par défaut: 0


La propriété  "stock


  "stock"                    gchararray            : Lire / Ecrire 

ID pour l'image de stock à afficher.

Valeur par défaut: NULL


La propriété  "storage-type


  "storage-type"             GtkImageType          : Lire

Représentation utilisée pour les données de l'image.

Valeur par défaut: GTK_IMAGE_EMPTY


La propriété  "visible


  "visible"                  gboolean              : Lire / Ecrire 

Si l'icône de statut est visible ou non.

Valeur par défaut: TRUE

Détails des Signaux

Le signal  "activate" 


void                user_function                      (GtkStatusIcon *status_icon,
gpointer user_data) : Exécuter Premier / Action

Emis quand l'utilisateur active l'icône de statut. If and how status icons can activated is platform-dependent.

status_icon : objet qui reçoit le signal
user_data : données utilisateur définies quand le gestionnaire de signal est connecté.

Depuis 2.10


Le signal  "popup-menu" 


void                user_function                      (GtkStatusIcon *status_icon,
guint button,
guint activate_time,
gpointer user_data) : Exécuter Premier / Action

Est émis quand l'utilisateur ouvre le menu de contexte de l'icône de statut. Si les icônes de statut peuvent posséder des menus de contexte et comment ils dépendent de la plateforme s'ils sont activés.

Les paramètres  button et activate_timeout doivent être passés au final en argument à  gtk_menu_popup().

status_icon : objet qui reçoit le signal
button : bouton pressé, ou 0 si le signal n'est pas émis en réponse à un événement de bouton pressé.
activate_time :  timestamp de l'événement qui déclenche l'émission du signal
user_data : données utilisateur définies quand le gestionnaire de signal est connecté.

Depuis 2.10


Le signal  "size-changed" 


gboolean            user_function                      (GtkStatusIcon *status_icon,
gint size,
gpointer user_data) : Exécuter Dernier

Est émis quand la taille valide de l'image change, par exemple quand l'aire de notification a été redimensionnée.

status_icon : objet qui reçoit le signal
size : nouvelle taille
user_data : données utilisateur définies quand le gestionnaire de signal est connecté.
Retourne : TRUE si l'icône a été mise à jour pour la nouvelle taille. AUtrement, GTK+ redimensionne l'icône comme nécessaire.

Depuis 2.10