Tiré de GTK+ Reference Manual
acryline 2007 Boosteur de petits projets

GtkAssistant

GtkAssistant — Widegt utilisé pour guider les utilisateurs  dans  des opérations multi-tâches. 

Synopsis

#include <gtk/gtk.h>


                    GtkAssistant;
GtkWidget*          gtk_assistant_new                   (void);
gint                gtk_assistant_get_current_page      (GtkAssistant *assistant);
void                gtk_assistant_set_current_page      (GtkAssistant *assistant,
                                                         gint page_num);
gint                gtk_assistant_get_n_pages           (GtkAssistant *assistant);
GtkWidget*          gtk_assistant_get_nth_page          (GtkAssistant *assistant,
                                                         gint page_num);
gint                gtk_assistant_prepend_page          (GtkAssistant *assistant,
                                                         GtkWidget *page);
gint                gtk_assistant_append_page           (GtkAssistant *assistant,
                                                         GtkWidget *page);
gint                gtk_assistant_insert_page           (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         gint position);
gint                (*GtkAssistantPageFunc)             (gint current_page,
                                                         gpointer data);
void                gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
                                                         GtkAssistantPageFunc page_func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);
enum                GtkAssistantPageType;
void                gtk_assistant_set_page_type         (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GtkAssistantPageType type);
GtkAssistantPageType gtk_assistant_get_page_type        (GtkAssistant *assistant,
                                                         GtkWidget *page);
void                gtk_assistant_set_page_title        (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         const gchar *title);
const gchar*        gtk_assistant_get_page_title        (GtkAssistant *assistant,
                                                         GtkWidget *page);
void                gtk_assistant_set_page_header_image (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GdkPixbuf *pixbuf);
GdkPixbuf*          gtk_assistant_get_page_header_image (GtkAssistant *assistant,
                                                         GtkWidget *page);
void                gtk_assistant_set_page_side_image   (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GdkPixbuf *pixbuf);
GdkPixbuf*          gtk_assistant_get_page_side_image   (GtkAssistant *assistant,
                                                         GtkWidget *page);
void                gtk_assistant_set_page_complete     (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         gboolean complete);
gboolean            gtk_assistant_get_page_complete     (GtkAssistant *assistant,
                                                         GtkWidget *page);
void                gtk_assistant_add_action_widget     (GtkAssistant *assistant,
                                                         GtkWidget *child);
void                gtk_assistant_remove_action_widget  (GtkAssistant *assistant,
                                                         GtkWidget *child);
void                gtk_assistant_update_buttons_state  (GtkAssistant *assistant);

Hiérarchie de l'Objet 

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----GtkAssistant

Interfaces Implémentés 

GtkAssistant implémente AtkImplementorIface.

Propriétés Enfants

  "complete"                 gboolean              : Lire /Ecrire
  "header-image"             GdkPixbuf             : Lire /Ecrire
  "page-type"                GtkAssistantPageType  : Lire /Ecrire
  "sidebar-image"            GdkPixbuf             : Lire /Ecrire
  "title"                    gchararray            : Lire /Ecrire

Propriétés de Style

  "content-padding"          gint                  : Lire
  "header-padding"           gint                  : Lire

Signaux

  "apply"                                          : Exécuter Dernier
  "cancel"                                         : Exécuter Dernier
  "close"                                          : Exécuter Dernier
  "prepare"                                        : Exécuter Dernier

Description

Un GtkAssistant est un widget utilisé pour présenter une opération généralement complexe décomposée en plusieurs étapes. Ce widget guide l'utilisateur à travers ses pages en contrôlant la progression dans les pages pour collecter les informations nécessaires.

Détails

GtkAssistant


typedef struct _GtkAssistant GtkAssistant;

gtk_assistant_new ()


GtkWidget*          gtk_assistant_new                   (void);

Crée une nouvelle fenêtre GtkAssistant.

Retourne : une GtkAssistant nouvellement créée

Depuis 2.10

gtk_assistant_get_current_page ()


gint                gtk_assistant_get_current_page      (GtkAssistant *assistant);

Retourne le numéro de la page courante.

assistant : une GtkAssistant
Retourne : index  (commençant par 0) de la page courante de l' assistant, si assistant n'a pas de page, -1 sera retourné.

Depuis 2.10

gtk_assistant_set_current_page ()


void                gtk_assistant_set_current_page      (GtkAssistant *assistant,
                                                         gint page_num);

Passe à la page page_num. Notez que cela sera nécessaire uniquement pour des boutons créés par le programmateur puisque la progression dans  assistant  peut être configurée avec  gtk_assistant_set_forward_page_func().

assistant : une GtkAssistant
page_num : index de la page de destination, commençant pas 0. S'il est négatif, la dernière page sera utilisée. Un numéro supérieur au nombre de pages de l'assistant n'aura aucun effet.

Depuis 2.10

gtk_assistant_get_n_pages ()


gint                gtk_assistant_get_n_pages           (GtkAssistant *assistant);

Retourne le nombre de pages de l' assistant

assistant : une GtkAssistant
Retourne : nombre de pages de l' assistant.

Depuis 2.10

gtk_assistant_get_nth_page ()


GtkWidget*          gtk_assistant_get_nth_page          (GtkAssistant *assistant,
                                                         gint page_num);

Retourne le widget enfant contenu dans la page numéro page_num.

assistant : une GtkAssistant
page_num :  index d'une page de l' assistant, ou -1 pour obetnir la dernière page
Retourne : widget enfant, ou NULL si page_num est hors des limites.

Depuis 2.10

gtk_assistant_prepend_page ()


gint                gtk_assistant_prepend_page          (GtkAssistant *assistant,
                                                         GtkWidget *page);

Ajoute une page au début de  l'assistant.

assistant : une GtkAssistant
page : un GtkWidget
Retourne :  index (commençant pas 0) de la page inserrée

Depuis 2.10

gtk_assistant_append_page ()


gint                gtk_assistant_append_page           (GtkAssistant *assistant,
                                                         GtkWidget *page);

Ajoute  une page à la fin de l' assistant.

assistant : une GtkAssistant
page : un GtkWidget
Retourne :  index (commençant pas 0) de la page inserrée

Depuis 2.10

gtk_assistant_insert_page ()


gint                gtk_assistant_insert_page           (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         gint position);

Inserre une page dans l' assistant à une position donnée.

assistant : une GtkAssistant
page : un GtkWidget
position :  index (commençant pas 0) ou inserrer la page , ou -1 pour placer la page à la fin de l'assistant
Retourne :  index (commençant pas 0) de la page inserrée

Depuis 2.10

GtkAssistantPageFunc ()


gint                (*GtkAssistantPageFunc)             (gint current_page,
                                                         gpointer data);

Fonction utilisée par  gtk_assistant_set_forward_page_func()pour connaître la page qui suit une page donnée courante. Elle est appelée pour calculer la page suivant quand l'utilisateur presse sur le bouton "page suivante" et pour contrôler le comportement du bouton "dernière page".

current_page : numéro de page utilisé pour calculer la page suivante.
data : données utilisateur.
Retourne : numéro de la page suivante

gtk_assistant_set_forward_page_func ()


void                gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
                                                         GtkAssistantPageFunc page_func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);

Définit la fonction de passage à la page suivante à  page_func, cette fonction sera utilisée pour déterminer quelle sera la page suivante quand l'utilisateur pressera sur le bouton "page suivante". Pour une définition de page_func à  NULL l'assistant utilisera la fonction de passage à la pgae suivante par défaut qui passe simplement à la page qui suit la page visible.

assistant : une GtkAssistant
page_func :  GtkAssistantPageFunc, ou NULL pour utiliser la fonction par défaut
data : données utilisateur pour  page_func
destroy : notification de destruction pour  data

Depuis 2.10

enum GtkAssistantPageType


typedef enum
{
  GTK_ASSISTANT_PAGE_CONTENT,
  GTK_ASSISTANT_PAGE_INTRO,
  GTK_ASSISTANT_PAGE_CONFIRM,
  GTK_ASSISTANT_PAGE_SUMMARY,
  GTK_ASSISTANT_PAGE_PROGRESS
} GtkAssistantPageType;

Une énumération pour déterminer le groupe de la page dans la GtkAssistant. Elle est utilisée pour contrôler la sensibilité et visibilité des boutons.

Notez qu'un assistant a besoin pour être correcte,  de terminer sa série de page avec le type de page GTK_ASSISTANT_PAGE_CONFIRM ou GTK_ASSISTANT_PAGE_SUMMARY.

GTK_ASSISTANT_PAGE_CONTENT
la page a un contenu régulier.
GTK_ASSISTANT_PAGE_INTRO la page contient une introduction aux tâches de l'assistant.
GTK_ASSISTANT_PAGE_CONFIRM la page permet à l'utilisateur de confirmer ou d'infirmer les modifications.
GTK_ASSISTANT_PAGE_SUMMARY la page informe l'utilisateur des modifications réalisée.
GTK_ASSISTANT_PAGE_PROGRESS utilisé pour des tâches qui prennent beaucoup de temps, bloque l'assistant jusqu'à ce que la page soit marquée complète.

gtk_assistant_set_page_type ()


void                gtk_assistant_set_page_type         (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GtkAssistantPageType type);

Définit le type de page pour  page. Le type de page détermine son comportement dans l' assistant.

assistant : une GtkAssistant
page : une page de l' assistant
type : le nouveau type pour  page

Depuis 2.10

gtk_assistant_get_page_type ()


GtkAssistantPageType gtk_assistant_get_page_type        (GtkAssistant *assistant,
                                                         GtkWidget *page);

Donne le type de page de  page.

assistant : une GtkAssistant
page : une page de assistant
Retourne : le type de page de  page.

Depuis 2.10

gtk_assistant_set_page_title ()


void                gtk_assistant_set_page_title        (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         const gchar *title);

Défini un titre pour  page. Le titre est affiché dans l'entête de l'assistant quand  page est la page courante.

assistant : une GtkAssistant
page : une page de  assistant
title : le nouveau titre de  page

Depuis 2.10

gtk_assistant_get_page_title ()


const gchar*        gtk_assistant_get_page_title        (GtkAssistant *assistant,
                                                         GtkWidget *page);

Donne le titre de  page.

assistant : une GtkAssistant
page : une page de assistant
Retourne : le titre de page.

Depuis 2.10

gtk_assistant_set_page_header_image ()


void                gtk_assistant_set_page_header_image (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GdkPixbuf *pixbuf);

Définit une image d'entête pour  page. Cette image est affichée dans l'entête de l'assistant quand  page est la page courante.

assistant : une GtkAssistant
page : une page de  assistant
pixbuf : la nouvelle image d'entête de  page

Depuis 2.10

gtk_assistant_get_page_header_image ()


GdkPixbuf*          gtk_assistant_get_page_header_image (GtkAssistant *assistant,
                                                         GtkWidget *page);

Donne l'image d'entête de  page.

assistant : une GtkAssistant
page : une page de  assistant
Retourne : l'image d'entête pour , ou NULL s'il n'y a pas d'image d'entête pour la page.

Depuis 2.10

gtk_assistant_set_page_side_image ()


void                gtk_assistant_set_page_side_image   (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         GdkPixbuf *pixbuf);

Définit l'image d'entête pour  page. Cette image est affichées dans l'aire latérale de l'assistant quand  page est la page courante.

assistant : une GtkAssistant
page : une page de assistant
pixbuf : la nouvelle image d'entête de page

Depuis 2.10

gtk_assistant_get_page_side_image ()


GdkPixbuf*          gtk_assistant_get_page_side_image   (GtkAssistant *assistant,
                                                         GtkWidget *page);

Donne l'image d'entête de  page.

assistant : une GtkAssistant
page : une page de assistant
Retourne : l'image latérale pour page, ou NULL s'il n'y a pas d'image latérale pour cette page.

Depuis 2.10

gtk_assistant_set_page_complete ()


void                gtk_assistant_set_page_complete     (GtkAssistant *assistant,
                                                         GtkWidget *page,
                                                         gboolean complete);

Détermine si le contenu de  page est complet. L' assistant mettra à jour l'état des boutons pour que la tâche puisse continuer.

assistant : une GtkAssistant
page : une page de assistant
complete : les status d'achèvement de la page

Depuis 2.10

gtk_assistant_get_page_complete ()


gboolean            gtk_assistant_get_page_complete     (GtkAssistant *assistant,
                                                         GtkWidget *page);

Dit si  page est complète.

assistant : une GtkAssistant
page : une page de assistant
Retourne : TRUE si  page est complète

Depuis 2.10

gtk_assistant_add_action_widget ()


void                gtk_assistant_add_action_widget     (GtkAssistant *assistant,
                                                         GtkWidget *child);

Ajoute un widget dans l'aire d'action d'une  GtkAssistant.

assistant : une GtkAssistant
child : un GtkWidget

Depuis 2.10

gtk_assistant_remove_action_widget ()


void                gtk_assistant_remove_action_widget  (GtkAssistant *assistant,
                                                         GtkWidget *child);

Retire un widget de l'aire d'action d'une GtkAssistant.

assistant : une GtkAssistant
child : un GtkWidget

Depuis 2.10

gtk_assistant_update_buttons_state ()


void                gtk_assistant_update_buttons_state  (GtkAssistant *assistant);

Force l' assistant de recalculer l'état des boutons.

GTK+ automatiquement fait attention à cela dans beaucoup de situations, par exemple quand l'utilisateur  passe  autre  page ou quand la visibilité ou l'achèvement de la page change.

Il est nécessaire d'appeler cette fonction quand une valeur a été changée pour la page courante et qu'elle affecte lea future progression dans l'assistant.

assistant : une GtkAssistant

Depuis 2.10

Détails de Propriétés Enfants

La propriété enfant  "complete" 


  "complete"                 gboolean              : Lire /Ecrire

La définition de la propriété enfant  "complete" à  TRUE marque la page pour dire qu'elle est achevée (c'est à dire que tous les champs de requête sont remplis). GTK+ utilise cette information pour contrôler le sensibilité des boutons de navigation.

Valeur par défaut: FALSE

Depuis 2.10

La propriété enfant  "header-image" 


  "header-image"             GdkPixbuf             : Lire /Ecrire

Image qui est affichée à côté de la page.

Définissez la à  NULL pour faire disparaître la barre de redimensionnement.

Depuis 2.10

La propriété enfant  "page-type" 


  "page-type"                GtkAssistantPageType  : Lire /Ecrire

Type de la page de l'assistant.

Valeur par défaut: GTK_ASSISTANT_PAGE_CONTENT

Depuis 2.10

La propriété enfant  "sidebar-image" 


  "sidebar-image"            GdkPixbuf             : Lire /Ecrire

Barre de redimensionnement pour la page de l'assistant.

La propriété enfant  "title" 


  "title"                    gchararray            : Lire /Ecrire

Titre qui est affiché dans l'entête de la page.

Si le titre et l'image d'entête sont les deux à  NULL l'entête ne sera pas affichée.


Valeur par défaut: NULL

Depuis 2.10

Détails des Propriétés de Style

La propriété de style  "content-padding" 


  "content-padding"          gint                  : Lire

Nombre de pixels autour du contenu des pages.

Valeurs possibles: >= 0

Valeur par défaut: 1

La propriété de style "header-padding" 


  "header-padding"           gint                  : Lire

Nombre de pixels autour de l'entête.

Valeurs possibles: >= 0

Valeur par défaut: 6

Détails de Signal

Le signal "apply" 


void                user_function                      (GtkAssistant *assistant,
                                                        gpointer      user_data)      : Exécuter Dernier

Le signal  ::apply est émis quand le bouton "appliqueré est cliqué. Le comportement par défaut de  GtkAssistant passe à la page qui suit la page courante, sauf si la page courante est la dernière page.

Un gestionnaire pour le signal ::apply doit effectuer les actions définies par les données collectées par l'assistant.  Si une action prend beaucoup de temps vous pouvez envisager mettre  une page de type  GTK_ASSISTANT_PAGE_PROGRESS après la page de confirmation et contrôler cette opération avec le signal  ::prepare de la page progress .

assistant : une GtkAssistant
user_data : données utilisateur définies quand le gestionnaire du signal a été connecté.

Depuis 2.10

Le signal "cancel" 


void                user_function                      (GtkAssistant *assistant,
                                                        gpointer      user_data)      : Exécuter Dernier

Le signal  ::cancel estémis quand le bouton "annuler" est cliqué.

assistant : une GtkAssistant
user_data : données utlisateur définies quand le gestionnaire du signal a été connecté.

Depuis 2.10

Le signal "close" 


void                user_function                      (GtkAssistant *assistant,
                                                        gpointer      user_data)      : Exécuter Dernier

Le signal  ::close signal est émis qoit quand le bouton "fermer" d'une page de sommaire est cliqué, soit quand le bouton "appliquer"  dans la dernière page de l'assistant est cliqué  (de type  GTK_ASSISTANT_PAGE_CONFIRM).

assistant : une GtkAssistant
user_data : données utlisateur définies quand le gestionnaire du signal a été connecté.

Depuis 2.10

Le signal "prepare" 


void                user_function                      (GtkAssistant *assistant,
                                                        GtkWidget    *page,
                                                        gpointer      user_data)      : Exécuter Dernier

le signal ::prepared est émis quand une nouvelle page est définie comme page courante de l'assistant avant de la rendre visible. Un gestionnaire pour ce signal peut faire toutes les préparations nécessaire avant d'afficher page.

assistant : une GtkAssistant
page : page courante
user_data : données utlisateur définies quand le gestionnaire du signal a été connecté.

Depuis 2.10