<< Les menus

PyGtk

La barre d'état >>

---

La barre d'outils

ATTENTION : beaucoup de fonctions utilisées dans ce tutorial ne doivent plus être utilisées avec les versions récentes de GTK+. Un nouveau tutorial est en cours d'élaboration

1. Présentation

La barre d'outils est très utile pour placer en dessous du menu les commandes les plus utilisées comme faire/défaire, nouveau, ouvrir, sauvegarde, etc. Un widget, GtkToolbar, indispensable pour une bonne application.

1.1 Hiérarchie

GObject -> GtkObject -> GtkWidget -> GtkContainer -> GtkToolbar

2. Utiliser une GtkToolbar

2.1 Création

Comme pour tous les autres widget, c'est très simple :

GtkWidget* gtk_toolbar_new(void);

2.2 Insertion d'éléments

GtkToolbar étant un container, après l'avoir créée, il va falloir ajouter des widget dedans. Cela se divise en 2 catégories.

• les widgets habituels comme les GtkButton, GtkToggleButton, GtkRadioButton pour lesquels GtkToolbar fourni des fonctions qui s'occupent de la création de ces derniers ;
• les autres widgets que nous pouvons ajouter mais c'est à nous de fournir les widget donc il faudra les créer auparavant.

Voici les premières fonctions qui permettent d'ajouter un bouton avec du texte et (ou) un icône :

GtkWidget* gtk_toolbar_append_item (GtkToolbar *toolbar, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data);
GtkWidget* gtk_toolbar_prepend_item (GtkToolbar *toolbar, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data);
GtkWidget* gtk_toolbar_insert_item (GtkToolbar *toolbar, const char *text, const char *tooltip_text,const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data, gint position);

La première fonction ajoute un bouton à la suite des autres boutons, la seconde l'ajoute en première position et la dernière à une position spécifique.
Pour chaque fonction, le premier paramètre est la barre d'outil dans laquelle on veut ajouter un élément. Il faut comme d'habitude utiliser une macro de conversion qui cette fois est GTK_TOOLBAR().
Ensuite, le paramètre text n'est autre que le label du bouton. Le troisième paramètre, tooltip_text, est une aide qui s'affichera lorsque l'utilisateur laisse le pointeur de sa souris quelques secondes sur le bouton. Le paramètre suivant, tooltip_private_text, n'est plus utilisé car la partie qui gère ce paramètre est obsolète. Il faut donc mettre ce paramètre à NULL.
Le paramètre icon est là pour définir l'image qui sera associée au bouton.
Les deux paramètres servent à connecter une fonction callback au clic sur le bouton. Le paramètre callback est en fait le nom de la fonction callback et user_data est la donnée supplémentaire à passer à la fonction callback.
Et pour terminer, la fonction gtk_toolbar_insert_item possède un paramètre supplémentaire position qui détermine à quelle position le bouton doit être ajouté. Si cette valeur est soit tros grande, soit négative, cette fonction aura le même effet que gtk_toolbar_append_item.

Ensuite il est possible de créer des éléments selon un type de widget prédéfini, comme GtkRadioButton, GtkToggleButton, GtkButton :

GtkWidget* gtk_toolbar_append_element (GtkToolbar *toolbar, GtkToolbarChildType? type, GtkWidget *widget, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data);
GtkWidget* gtk_toolbar_prepend_element (GtkToolbar *toolbar, GtkToolbarChildType? type, GtkWidget *widget, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data);
GtkWidget* gtk_toolbar_insert_element (GtkToolbar *toolbar, GtkToolbarChildType? type, GtkWidget *widget, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc? callback, gpointer user_data, gint position);

La majorité des paramètres de ces fonctions ont été détaillés précédemment, nous n'allons donc étudier que les nouveaux.
Tout d'abord, le paramètre type permet de définir le type de widget que nous allons ajouter, et peut prendre une de ces valeurs :

• GTK_TOOLBAR_CHILD_SPACE pour ajouter un espace ;
• GTK_TOOLBAR_CHILD_BUTTON pour ajouter un GtkButton ;
• GTK_TOOLBAR_CHILD_TOGGLEBUTTON pour ajouter un GtkToggleButton ;
• GTK_TOOLBAR_CHILD_RADIOBUTTON pour ajouter un GtkRadioButton ;
• GTK_TOOLBAR_CHILD_WIDGET pour ajouter un widget quelconque.

Il y a ensuite le paramètre widget qui doit être utiliser dans deux cas. Le premier cas est bien entendu, si nous ajoutons un élément de type GTK_TOOLBAR_CHILD_WIDGET. Alors widget sera en fait le widget que nous voulons ajouter.
Le deuxième cas est si nous ajoutons un élément de type GTK_TOOLBAR_CHILD_RADIOBUTTON. Nous avons vu que les GtkRadioButton fonctionnés par groupe, alors dans ce cas, pour grouper les boutons radios le paramètre widget doit être un GtkRadioButton ajouté précédemment pour que GTK+ puisse les grouper. Bien sûr, s'il s'agit du premier GtkRadioButton, il faut mettre widget à NULL.
Dans tous les autres cas, le paramètre widget doit obligatoirement être à NULL.

Et maintenant, voila les fonctions pour ajouter n'importe quel type de widget :

void gtk_toolbar_append_widget (GtkToolbar *toolbar, GtkWidget *widget, const char *tooltip_text, const char *tooltip_private_text);
void gtk_toolbar_prepend_widget (GtkToolbar *toolbar, GtkWidget *widget, const char *tooltip_text, const char *tooltip_private_text);
void gtk_toolbar_insert_widget (GtkToolbar *toolbar, GtkWidget *widget, const char *tooltip_text, const char *tooltip_private_text, gint position);

Cette fois, tout est simple, le paramètre widget est le widget que nous voulons ajouter. Il faudra tout de même connecter manuellement les signaux du widget ajouté.

Pour finir, il est possible d'utiliser les GtkStockItem? pour créer un bouton. Voici la fonction qui permet cela :

GtkWidget* gtk_toolbar_insert_stock (GtkToolbar *toolbar, const gchar *stock_id, const char *tooltip_text, const char *tooltip_private_text, GtkSignalFunc? callback, gpointer user_data, gint position);

Le paramètre stock_id est tout simplement l'identifiant du GtkStockItem? qui figurera sur le bouton.

2.3 Les espaces

Nous avons déjà vu que les fonctions de type gtk_toolbar_*_element permettaient d'ajouter un espace pour rendre plus claire la barre d'outils. Il existe en plus de cela trois autres fonctions :

void gtk_toolbar_append_space(GtkToolbar *toolbar );
void gtk_toolbar_prepend_space(GtkToolbar *toolbar );
void gtk_toolbar_insert_space(GtkToolbar *toolbar, guint pos );

Comme d'habitude la première fonction ajoute un espace à la suite des autres éléments, la deuxième au tout début de la barre d'outils et la troisième à une position particulière.

Pour supprimer un espace de la barre d'outils, il existe cette fonction :

void gtk_toolbar_remove_space(GtkToolbar *toolbar, guint pos);

2.4 Orientation de la barre d'outils

La barre d'outil peut être orienter verticalement ou horizontalement et cela à n'importe quel moment a l'aide de cette fonction :

void gtk_toolbar_set_orientation(GtkToolbar *toolbar, GtkOrientation? orientation) ;

Le paramètre orientation peut prendre deux valeurs :

• GTK_ORIENTATION_HORIZONTAL ;
• GTK_ORIENTATION_VERTICAL.

Et, cette fonction permet de connaître l'orientation de la barre d'outil :

GtkOrientation? gtk_toolbar_get_oritentation(GtkToolbar *toolbar);

2.5 Les styles

Il est possible de changer la façon d'afficher certains éléments de la barre d'outils : afficher que le texte, seulement les icônes ou les deux. Voila la fonction qui permet de contrôler cela :

void gtk_toolbar_set_style(GtkToolbar *toolbar, GtkToolbarStyle? style) ;

Le paramètre style peut prendre 4 valeurs différentes :

• GTK_TOOLBAR_ICONS pour n'afficher que l'icône ;
• GTK_TOOLBAR_TEXT pour n'afficher que le texte ;
• GTK_TOOLBAR_BOTH pour afficher le texte en dessous de l'icône (valeur par défaut) ;
• GTK_TOOLBAR_BOTH_HORIZ pour afficher le texte à côté de l'icône.

Et pour finir, cette fonction permet de connaître le style de la barre d'outil :

GtkToolbarStyle? gtk_toolbar_get_style(GtkToolbar *toolbar);

2.6 La taille des icônes

Enfin pour terminer, GTK+ nous offre la possibilité de modifier la taille des icônes de la barre d'outils avec cette fonction :

void gtk_toolbar_set_icon_size(GtkToolbar *toolbar, GtkIconSize icon_size);

Le paramètre icon_size est du type GtkIconSize que nous avons déjà rencontré dans le chapitre sur les images. Nous allons tout de même rappeler les différentes valeurs possibles qui sont les suivantes :

• GTK_ICON_SIZE_MENU ;
• GTK_ICON_SIZE_SMALL_TOOLBAR ;
• GTK_ICON_SIZE_LARGE_TOOLBAR (valeur par défaut) ;
• GTK_ICON_SIZE_BUTTON ;
• GTK_ICON_SIZE_DND ;
• GTK_ICON_SIZE_DIALOG.

Et bien sûr, pour connaître la taille des icônes, nous avons la fonction :

GtkIconSize gtk_toolbar_get_icon_size(GtkToolbar *toolbar);

2.7 Programme exemple

Dans cet exemple, nous allons juste créer une barre d'outils dans laquelle nous allons ajouter quelques boutons dont deux d'entre eux permettront de changer l'orientation de la barre d'outil.

#include <stdlib.h>
#include <gtk/gtk.h>

void OnChangeOrientation(GtkWidget *widget, gpointer data);

static GtkWidget *pToolbar = NULL;

int main(int argc, char **argv)
{
   GtkWidget *pWindow;
   GtkWidget *pVBox;

   gtk_init(&argc, &argv);

   /* Creation de la fenetre */
   pWindow = gtk_window_new(GTK_WINDOW_TOPLEVEL);
   gtk_window_set_title(GTK_WINDOW(pWindow), "GtkToolbar");
   gtk_window_set_default_size(GTK_WINDOW(pWindow), 320, 200);
   g_signal_connect(G_OBJECT(pWindow), "destroy", G_CALLBACK(gtk_main_quit), NULL);

   pVBox = gtk_vbox_new(FALSE, 0);
   gtk_container_add(GTK_CONTAINER(pWindow), pVBox);

   /* Creation de la barre d'outils */
   pToolbar = gtk_toolbar_new();
   gtk_box_pack_start(GTK_BOX(pVBox), pToolbar, FALSE, FALSE, 0);

   /* Creation a partir de stock */
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_NEW,
      "Nouveau",
      NULL,
      NULL,
      NULL,
      -1);
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_OPEN,
      "Ouvrir",
      NULL,
      NULL,
      NULL,
      -1);
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_SAVE,
      "Enregistrer",
      NULL,
      NULL,
      NULL,
      -1);
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_QUIT,
      "Fermer",
      NULL,
      G_CALLBACK(gtk_main_quit),
      NULL,
      -1);

   /* Insertion d'un espace */
   gtk_toolbar_append_space(GTK_TOOLBAR(pToolbar));

   /* Creation a partir de stock */
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_GO_FORWARD,
      "Horizontale",
      NULL,
      G_CALLBACK(OnChangeOrientation),
      GINT_TO_POINTER(GTK_ORIENTATION_HORIZONTAL),
      -1);
   gtk_toolbar_insert_stock(GTK_TOOLBAR(pToolbar),
      GTK_STOCK_GO_DOWN,
      "Verticale",
      NULL,
      G_CALLBACK(OnChangeOrientation),
      GINT_TO_POINTER(GTK_ORIENTATION_VERTICAL),
      -1);

   /* Modification de la taille des icones */
   gtk_toolbar_set_icon_size(GTK_TOOLBAR(pToolbar),
      GTK_ICON_SIZE_BUTTON);
   /* Affichage uniquement des icones */
   gtk_toolbar_set_style(GTK_TOOLBAR(pToolbar),
      GTK_TOOLBAR_ICONS);

   gtk_widget_show_all(pWindow);

   gtk_main();

   return EXIT_SUCCESS;
}

void OnChangeOrientation(GtkWidget *widget, gpointer data)
{
   /* Modification de l'orientation */
   gtk_toolbar_set_orientation(GTK_TOOLBAR(pToolbar),
      GPOINTER_TO_INT(data));
}