GtkProgressBar

GtkProgressBar — Widget qui affiche un progression visuelle.

Synopsis

#include <gtk/gtk.h>


                    GtkProgressBar;
GtkWidget*          gtk_progress_bar_new                (void);
void                gtk_progress_bar_pulse              (GtkProgressBar *pbar);
void                gtk_progress_bar_set_text           (GtkProgressBar *pbar,
                                                         const gchar *text);
void                gtk_progress_bar_set_fraction       (GtkProgressBar *pbar,
                                                         gdouble fraction);
void                gtk_progress_bar_set_pulse_step     (GtkProgressBar *pbar,
                                                         gdouble fraction);
void                gtk_progress_bar_set_orientation    (GtkProgressBar *pbar,
                                                         GtkProgressBarOrientation orientation);
void                gtk_progress_bar_set_ellipsize      (GtkProgressBar *pbar,
                                                         PangoEllipsizeMode mode);
enum                GtkProgressBarOrientation;
const gchar*        gtk_progress_bar_get_text           (GtkProgressBar *pbar);
gdouble             gtk_progress_bar_get_fraction       (GtkProgressBar *pbar);
gdouble             gtk_progress_bar_get_pulse_step     (GtkProgressBar *pbar);
GtkProgressBarOrientation gtk_progress_bar_get_orientation
                                                        (GtkProgressBar *pbar);
PangoEllipsizeMode  gtk_progress_bar_get_ellipsize      (GtkProgressBar *pbar);
GtkWidget*          gtk_progress_bar_new_with_adjustment
                                                        (GtkAdjustment *adjustment);
void                gtk_progress_bar_set_bar_style      (GtkProgressBar *pbar,
                                                         GtkProgressBarStyle style);
enum                GtkProgressBarStyle;
void                gtk_progress_bar_set_discrete_blocks
                                                        (GtkProgressBar *pbar,
                                                         guint blocks);
void                gtk_progress_bar_set_activity_step  (GtkProgressBar *pbar,
                                                         guint step);
void                gtk_progress_bar_set_activity_blocks
                                                        (GtkProgressBar *pbar,
                                                         guint blocks);
void                gtk_progress_bar_update             (GtkProgressBar *pbar,
                                                         gdouble percentage);

Hiérarchie d'Objet

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkProgress
                           +----GtkProgressBar

Interfaces Implémentés

GtkProgressBarimplémente AtkImplementorIface.

Propriétés

  "activity-blocks"          guint                 : Read / Write
  "activity-step"            guint                 : Read / Write
  "adjustment"               GtkAdjustment         : Read / Write
  "bar-style"                GtkProgressBarStyle   : Read / Write
  "discrete-blocks"          guint                 : Read / Write
  "ellipsize"                PangoEllipsizeMode    : Read / Write
  "fraction"                 gdouble               : Read / Write
  "orientation"              GtkProgressBarOrientation  : Read / Write
  "pulse-step"               gdouble               : Read / Write
  "text"                     gchararray            : Read / Write

Propriétés de Style 

  "xspacing"                 gint                  : Read / Write
  "yspacing"                 gint                  : Read / Write

Description

La  GtkProgressBar est généralement utilisée pour afficher la progression d'un opération longue à exécuter. Elle fournit  une indication visuelle du processus en cours. La GtkProgressBar peut être utilisée selon deux modes : le mode du pourcentage et le mode d'activité.

Quand une application peut définir le travail  nécéssaire pour prendre  place ( par exmple lire un nombre fixé de bytes depuis un fichier) et peut gérer sa progression, elle peut utiliser la GtkProgressBar en mode pourcentage et l'utilisateur verra une barre de progression indiquant le pourcentage de travail déjà effectué. Pour ce mode l'application devra appeler  gtk_progress_bar_set_fraction() périodiquement pour mettre à jour la barre de progression.

Quand une application ne peut pas connaître le travail qu'il reste à faire, elle peut utiliser la  GtkProgressBar en mode activité qui montre l'activité par un  bloc  qui se déplace dans les deux sens à l'intérieur de l'aire de progression. Dans ce mode l'application devra appeler  gtk_progress_bar_pulse() prériodiquement pour mettre à jour la barre de progression.

Il y a une certaine flexibilité fournie pour contrôler l'apparence de la GtkProgressBar. Des fonctions sont disponibles pour contrôler l'orientation de la barre, un texte optionnel peut être affiché dans labarre, et la taille dun niveau utilisé en mode activité peut être défini.

Note

L'API GtkProgressBar/GtkProgress dans GTK 1.2 a été gonflé de façon inutilement complexe et difficile à utiliser correctement. Ainsi  GtkProgress a été dépréciée complétement et l'API  GtkProgressBar  a été réduit aux 10 fonctions suivantes : gtk_progress_bar_new(), gtk_progress_bar_pulse(), gtk_progress_bar_set_text(), gtk_progress_bar_set_fraction(), gtk_progress_bar_set_pulse_step(), gtk_progress_bar_set_orientation(), gtk_progress_bar_get_text(), gtk_progress_bar_get_fraction(), gtk_progress_bar_get_pulse_step(), gtk_progress_bar_get_orientation(). Elles sont groupées au début de la section. Ce qui suit sont des fonctions dépréciées  compatibles avec la version 1.2.

Détails

GtkProgressBar


typedef struct _GtkProgressBar GtkProgressBar;

La structure  GtkProgressBar contient seulement des données privées et on doit y accéder en utilisant les fonctions qui suivent.

gtk_progress_bar_new ()


GtkWidget*          gtk_progress_bar_new                (void);

Crée une nouvelle GtkProgressBar.

Retourne : a GtkProgressBar.

gtk_progress_bar_pulse ()


void                gtk_progress_bar_pulse              (GtkProgressBar *pbar);

Indique qu'une progression a eu lieu mais ne la quantifie pas. Elle fait entrer la barre de progression en mode activité de façon à ce que le bloc se déplace dans les deux sens de la barre.A chaque appel de  gtk_progress_bar_pulse() le bloc se déplace légérement (la quantité de mouvement par impulsion est définie par  gtk_progress_bar_set_pulse_step()).

pbar : une GtkProgressBar

gtk_progress_bar_set_text ()


void                gtk_progress_bar_set_text           (GtkProgressBar *pbar,
                                                         const gchar *text);

Fait en sorte qu'un  text donné apparaisse en surimpression dans la barre de progression.

pbar : une GtkProgressBar
text : une chaîne UTF-8 , ou NULL

gtk_progress_bar_set_fraction ()


void                gtk_progress_bar_set_fraction       (GtkProgressBar *pbar,
                                                         gdouble fraction);

Fait en sorte que la barre de progression remplisse une fraction donnée de la barre. Cette fraction est comprise entre 0.0 et 1.0 inclus.

pbar : une GtkProgressBar
fraction : fraction de la barre qui est complétée.

gtk_progress_bar_set_pulse_step ()


void                gtk_progress_bar_set_pulse_step     (GtkProgressBar *pbar,
                                                         gdouble fraction);

Définit la fraction de la longueur totale de la barre de progression utilisée pour chaque mouvement du bloc, mouvement provoqué par l'appel de  gtk_progress_bar_pulse().

pbar : une GtkProgressBar
fraction : fraction entre 0.0 and 1.0

gtk_progress_bar_set_orientation ()


void                gtk_progress_bar_set_orientation    (GtkProgressBar *pbar,
                                                         GtkProgressBarOrientation orientation);

Fait en sorte que la barre de progression bascule vers une orientation différente ( gauche à droite, droite à gauche, haut en bas, bas en haut).

pbar : une GtkProgressBar
orientation : orientation de la barre de progression

gtk_progress_bar_set_ellipsize ()


void                gtk_progress_bar_set_ellipsize      (GtkProgressBar *pbar,
                                                         PangoEllipsizeMode mode);

Définit le mode utilisé pour ajouter une ellipse ("..." au texte s'il n'y a pas assez de place pour l'afficher entièrement.

pbar : une GtkProgressBar
mode : un PangoEllipsizeMode

Depuis 2.6

enum GtkProgressBarOrientation


typedef enum
{
  GTK_PROGRESS_LEFT_TO_RIGHT,
  GTK_PROGRESS_RIGHT_TO_LEFT,
  GTK_PROGRESS_BOTTOM_TO_TOP,
  GTK_PROGRESS_TOP_TO_BOTTOM
} GtkProgressBarOrientation;

Enumération représentant les orientations possibles et les directions de progression de la barre de progression visible.

GTK_PROGRESS_LEFT_TO_RIGHT barre de progression horizontale avançant de gauche à droite.
GTK_PROGRESS_RIGHT_TO_LEFT barre de progression horizontale avançant de droite.à gauche.
GTK_PROGRESS_BOTTOM_TO_TOP barre de progression verticale avançant de bas en haut.
GTK_PROGRESS_TOP_TO_BOTTOM barre de progression verticale avançant de haut en bas.

gtk_progress_bar_get_text ()


const gchar*        gtk_progress_bar_get_text           (GtkProgressBar *pbar);

Recherche le texte affiché en surimpression sur la barre de progression, s'il y en a un, autrement  NULL. La valeur retournée est la référence du texte, et non une copie de cette référence, elle deviendra invalide si vous changez le texte dans la barre de progression.

pbar : une GtkProgressBar
Retourne : texte, ou NULL; cette chaîne appartient au widget et ne doit ni être modifiée ni libérée.

gtk_progress_bar_get_fraction ()


gdouble             gtk_progress_bar_get_fraction       (GtkProgressBar *pbar);

Retourne la fraction courant de travail qui a été complété.

pbar : une GtkProgressBar
Retourne : fraction comprise entre  0.0 et 1.0

gtk_progress_bar_get_pulse_step ()


gdouble             gtk_progress_bar_get_pulse_step     (GtkProgressBar *pbar);

Recherche  taille d'impulsion définie avec  gtk_progress_bar_set_pulse_step()

pbar : a GtkProgressBar
Retourne :  fraction comprise entre 0.0 et 1.0

gtk_progress_bar_get_orientation ()


GtkProgressBarOrientation gtk_progress_bar_get_orientation
                                                        (GtkProgressBar *pbar);

Recherch l'orientation courante  de la barre de progression.

pbar : une GtkProgressBar
Retourne : orientation de la barre de progression

gtk_progress_bar_get_ellipsize ()


PangoEllipsizeMode  gtk_progress_bar_get_ellipsize      (GtkProgressBar *pbar);

Retourne la position de l'ellipse de la barre de progression. Voir . See gtk_progress_bar_set_ellipsize().

pbar : une GtkProgressBar
Retourne : PangoEllipsizeMode

Depuis 2.6

gtk_progress_bar_new_with_adjustment ()


GtkWidget*          gtk_progress_bar_new_with_adjustment
                                                        (GtkAdjustment *adjustment);

Attention

gtk_progress_bar_new_with_adjustment est dépréciée et ne doit plus être utilisée dans un nouveau code.

Crée une nouvelle GtkProgressBar avec un  GtkAdjustment associé.

adjustment : un GtkAdjustment.
Retourne : une GtkProgressBar.

gtk_progress_bar_set_bar_style ()


void                gtk_progress_bar_set_bar_style      (GtkProgressBar *pbar,
                                                         GtkProgressBarStyle style);

Attention

gtk_progress_bar_set_bar_style est dépréciée et ne doit plus être utilisée dans un nouveau code.

Définit le style de la  GtkProgressBar. Par défaut ce style est  GTK_PROGRESS_CONTINUOUS.

pbar : une  GtkProgressBar.
style : une valeur  GtkProgressBarStyle indiquant le style désiré.

enum GtkProgressBarStyle


typedef enum
{
  GTK_PROGRESS_CONTINUOUS,
  GTK_PROGRESS_DISCRETE
} GtkProgressBarStyle;

Enumération représentant les styles de barre de progression.

GTK_PROGRESS_CONTINUOUS barre de progression lisse et continue.
GTK_PROGRESS_DISCRETE barre de progressions avec des blocs visibles.

gtk_progress_bar_set_discrete_blocks ()


void                gtk_progress_bar_set_discrete_blocks
                                                        (GtkProgressBar *pbar,
                                                         guint blocks);

Attention 

gtk_progress_bar_set_discrete_blocks est dépréciée et ne doit plus être utilisée dans un nouveau code.

Définit le nombre de blocs que contient la barre de progression quand le style est  GTK_PROGRESS_DISCRETE.

pbar : une GtkProgressBar.
blocks : nombre de blocs individuels contenus dans la barre de progression.

gtk_progress_bar_set_activity_step ()


void                gtk_progress_bar_set_activity_step  (GtkProgressBar *pbar,
                                                         guint step);

Attention

gtk_progress_bar_set_activity_step est dépréciée et ne doit plus être utilisée dans un nouveau code.

Définit la valeur d'une étape quand la barre de progression est en mode activité. L'étape est la taille du déplacement  utilisée pour incrémenter la progression à chaque itération.

pbar : une GtkProgressBar.
step : taille du déplacement utilisée pour incrémenter la progression en mode activité.

gtk_progress_bar_set_activity_blocks ()


void                gtk_progress_bar_set_activity_blocks
                                                        (GtkProgressBar *pbar,
                                                         guint blocks);

Attention

gtk_progress_bar_set_activity_blocks est dépréciée et ne doit plus être utilisée dans un nouveau code.

Définit le nombre de blcs utilisés quand la barre de progression est en mode activité. Plu ce nombre est grand plus les blocs sont petits.

pbar : un GtkProgressBar.
blocks : nombre de blocs à l'intérieur de l'aire de la barre de progression.

gtk_progress_bar_update ()


void                gtk_progress_bar_update             (GtkProgressBar *pbar,
                                                         gdouble percentage);

Attention

gtk_progress_bar_update est dépréciée et ne doit plus être utilisée dans un nouveau code.

Cette fonction est dépréciée. Utilisez  gtk_progress_set_value() ou gtk_progress_set_percentage() à la place.

pbar : une GtkProgressBar.
percentage : nouvelle valeur en pourcentage.

Détails des Propriétés

La propriété  "activity-blocks" 


  "activity-blocks"          guint                 : Read / Write

nombre de blocs qui peuvent être contenus dans l'aire de la barre de progression en mode activité (Dépréciée)

Valeurs permises: >= 2

Valeur par défaut: 5

La propriété  "activity-step" 


  "activity-step"            guint                 : Read / Write

Incrémentation utilisée pour chaque itération en mode activité. (Dépréciée)

Valeur par défaut: 3

La propriété  "adjustment" 


  "adjustment"               GtkAdjustment         : Read / Write

Le  GtkAdjustment connecté à la barre de progression (Dépréciée)

La propriété  "bar-style" 


  "bar-style"                GtkProgressBarStyle   : Read / Write

Définit le style visuel de la barre en mode pourcentage (Dépréciée).

Valeur par défaut: GTK_PROGRESS_CONTINUOUS

La propriété  "discrete-blocks" 


  "discrete-blocks"          guint                 : Read / Write

Nombre de blocs discrets dans la barre de progression (quand elle est affichée en style discret)

Valeurs permises: >= 2

Valeur par défaut: 10

La propriété  "ellipsize" 


  "ellipsize"                PangoEllipsizeMode    : Read / Write

Place choisie pour mettre l'ellipse (...)dans une chaîne si la barre de progression n'a pas assez de place pour afficher la chaîne en entier; définie comme un  PangoEllisizeMode.

Notez que la définition de cette propriété à une valeur autre que  PANGO_ELLIPSIZE_NONEaura l'effet sur la taille  que la barre de progression demande seulement s'il y a assez de place pour afficher l'ellipse "...". has the side-effect that the progressbar requests only enough space to display the ellipsis "...".Un autre moyen de définir le largeur des barres de progression est  gtk_widget_set_size_request().

Valeur par défaut: PANGO_ELLIPSIZE_NONE

Depuis 2.6

La propriété  "fraction" 


  "fraction"                 gdouble               : Read / Write

Fraction de la totalité du travail qui a été terminé. 

Valeurs permises: [0,1]

Valeur par défaut: 0

La propriété  "orientation" 


  "orientation"              GtkProgressBarOrientation  : Read / Write

Orientation et direction de la progression de la barre de progression.

Valeur par défaut: GTK_PROGRESS_LEFT_TO_RIGHT

La propriété  "pulse-step" 


  "pulse-step"               gdouble               : Read / Write

Fraction de l'ensemble de la progression qui définit un déplacement d'un  bloc pour une itération.

Valeurs permises: [0,1]

Valeur par défaut: 0.1

La propriété  "text" 


  "text"                     gchararray            : Read / Write

Texte à afficher dans la barre de progression.

Valeur par défaut: "%P %%"

Détails des Propriétés de Style 

La propriété de style "xspacing" 


  "xspacing"                 gint                  : Read / Write

Espace supplémentaire appliqué à la largeur de la barre de progression;

Valeurs permises: >= 0

Valeur par défaut: 7

La propriété de style "yspacing" 


  "yspacing"                 gint                  : Read / Write

Espace supplémentaire appliqué à la hauteur de la barre de progression.

Valeurs permises: >= 0

Valeur par défaut: 7