Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkprogressbar.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkProgressBar
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A widget which indicates progress visually
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkProgressBar is typically used to display the progress of a long
  10 running operation.  It provides a visual clue that processing
  11 is underway.  The #GtkProgressBar can be used in two different
  12 modes: percentage mode and activity mode.
  13 </para>
  14
  15 <para>
  16 When an application can determine how much work needs to take place
  17 (e.g. read a fixed number of bytes from a file) and can monitor its
  18 progress, it can use the #GtkProgressBar in percentage mode and the user
  19 sees a growing bar indicating the percentage of the work that has
  20 been completed.  In this mode, the application is required to call
  21 gtk_progress_bar_set_fraction() periodically to update the progress bar.
  22 </para>
  23
  24 <para>
  25 When an application has no accurate way of knowing the amount of work
  26 to do, it can use the #GtkProgressBar in activity mode, which shows activity
  27 by a block moving back and forth within the progress area. In this mode,
  28 the application is required to call gtk_progress_bar_pulse() perodically
  29 to update the progress bar.
  30 </para>
  31
  32 <para>
  33 There is quite a bit of flexibility provided to control the appearance
  34 of the #GtkProgressBar.  Functions are provided to control the
  35 orientation of the bar, optional text can be displayed along with
  36 the bar, and the step size used in activity mode can be set.
  37 </para>
  38
  39 <note>
  40 <para>
  41 The #GtkProgressBar/#GtkProgress API in GTK 1.2 was bloated, needlessly complex
  42 and hard to use properly.  Therefore #GtkProgress has been deprecated
  43 completely and the #GtkProgressBar API has been reduced to the following 10
  44 functions: gtk_progress_bar_new(), gtk_progress_bar_pulse(),
  45 gtk_progress_bar_set_text(), gtk_progress_bar_set_fraction(),
  46 gtk_progress_bar_set_pulse_step(), gtk_progress_bar_set_orientation(),
  47 gtk_progress_bar_get_text(), gtk_progress_bar_get_fraction(),
  48 gtk_progress_bar_get_pulse_step(), gtk_progress_bar_get_orientation().
  49 These have been grouped at the beginning of this section, followed by
  50 a large chunk of deprecated 1.2 compatibility functions.
  51 </para>
  52 </note>
  53
  54 <!-- ##### SECTION See_Also ##### -->
  55 <para>
  56
  57 </para>
  58
  59 <!-- ##### SECTION Stability_Level ##### -->
  60
  61
  62 <!-- ##### SECTION Image ##### -->
  63
  64
  65 <!-- ##### STRUCT GtkProgressBar ##### -->
  66 <para>
  67 The #GtkProgressBar-struct struct contains private data only,
  68 and should be accessed using the functions below.
  69 </para>
  70
  71
  72 <!-- ##### ARG GtkProgressBar:ellipsize ##### -->
  73 <para>
  74
  75 </para>
  76
  77 <!-- ##### ARG GtkProgressBar:fraction ##### -->
  78 <para>
  79
  80 </para>
  81
  82 <!-- ##### ARG GtkProgressBar:orientation ##### -->
  83 <para>
  84
  85 </para>
  86
  87 <!-- ##### ARG GtkProgressBar:pulse-step ##### -->
  88 <para>
  89
  90 </para>
  91
  92 <!-- ##### ARG GtkProgressBar:text ##### -->
  93 <para>
  94
  95 </para>
  96
  97 <!-- ##### ARG GtkProgressBar:min-horizontal-bar-height ##### -->
  98 <para>
  99
 100 </para>
 101
 102 <!-- ##### ARG GtkProgressBar:min-horizontal-bar-width ##### -->
 103 <para>
 104
 105 </para>
 106
 107 <!-- ##### ARG GtkProgressBar:min-vertical-bar-height ##### -->
 108 <para>
 109
 110 </para>
 111
 112 <!-- ##### ARG GtkProgressBar:min-vertical-bar-width ##### -->
 113 <para>
 114
 115 </para>
 116
 117 <!-- ##### ARG GtkProgressBar:xspacing ##### -->
 118 <para>
 119
 120 </para>
 121
 122 <!-- ##### ARG GtkProgressBar:yspacing ##### -->
 123 <para>
 124
 125 </para>
 126
 127 <!-- ##### FUNCTION gtk_progress_bar_new ##### -->
 128 <para>
 129 Creates a new #GtkProgressBar.
 130 </para>
 131
 132 @void:
 133 @Returns: a #GtkProgressBar.
 134
 135
 136 <!-- ##### FUNCTION gtk_progress_bar_pulse ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @pbar:
 142
 143
 144 <!-- ##### FUNCTION gtk_progress_bar_set_text ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @pbar:
 150 @text:
 151
 152
 153 <!-- ##### FUNCTION gtk_progress_bar_set_fraction ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @pbar:
 159 @fraction:
 160
 161
 162 <!-- ##### FUNCTION gtk_progress_bar_set_pulse_step ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @pbar:
 168 @fraction:
 169
 170
 171 <!-- ##### FUNCTION gtk_progress_bar_set_orientation ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @pbar:
 177 @orientation:
 178
 179
 180 <!-- ##### FUNCTION gtk_progress_bar_set_ellipsize ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @pbar:
 186 @mode:
 187
 188
 189 <!-- ##### ENUM GtkProgressBarOrientation ##### -->
 190 <para>
 191 An enumeration representing possible orientations and growth
 192 directions for the visible progress bar.
 193 </para>
 194
 195 @GTK_PROGRESS_LEFT_TO_RIGHT: A horizontal progress bar growing from left to right.
 196 @GTK_PROGRESS_RIGHT_TO_LEFT: A horizontal progress bar growing from right to left.
 197 @GTK_PROGRESS_BOTTOM_TO_TOP: A vertical progress bar growing from bottom to top.
 198 @GTK_PROGRESS_TOP_TO_BOTTOM: A vertical progress bar growing from top to bottom.
 199
 200 <!-- ##### FUNCTION gtk_progress_bar_get_text ##### -->
 201 <para>
 202
 203 </para>
 204
 205 @pbar:
 206 @Returns:
 207
 208
 209 <!-- ##### FUNCTION gtk_progress_bar_get_fraction ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @pbar:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION gtk_progress_bar_get_pulse_step ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @pbar:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION gtk_progress_bar_get_orientation ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @pbar:
 233 @Returns:
 234
 235
 236 <!-- ##### FUNCTION gtk_progress_bar_get_ellipsize ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @pbar:
 242 @Returns:
 243
 244
 245 <!-- ##### ENUM GtkProgressBarStyle ##### -->
 246 <para>
 247 An enumeration representing the styles for drawing the progress bar.
 248 </para>
 249
 250 @GTK_PROGRESS_CONTINUOUS: The progress bar grows in a smooth, continuous manner.
 251 @GTK_PROGRESS_DISCRETE: The progress bar grows in discrete, visible blocks.
 252