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 <!-- ##### STRUCT GtkProgressBar ##### -->
  63 <para>
  64 The #GtkProgressBar-struct struct contains private data only,
  65 and should be accessed using the functions below.
  66 </para>
  67
  68
  69 <!-- ##### ARG GtkProgressBar:activity-blocks ##### -->
  70 <para>
  71
  72 </para>
  73
  74 <!-- ##### ARG GtkProgressBar:activity-step ##### -->
  75 <para>
  76
  77 </para>
  78
  79 <!-- ##### ARG GtkProgressBar:adjustment ##### -->
  80 <para>
  81
  82 </para>
  83
  84 <!-- ##### ARG GtkProgressBar:bar-style ##### -->
  85 <para>
  86
  87 </para>
  88
  89 <!-- ##### ARG GtkProgressBar:discrete-blocks ##### -->
  90 <para>
  91
  92 </para>
  93
  94 <!-- ##### ARG GtkProgressBar:ellipsize ##### -->
  95 <para>
  96
  97 </para>
  98
  99 <!-- ##### ARG GtkProgressBar:fraction ##### -->
 100 <para>
 101
 102 </para>
 103
 104 <!-- ##### ARG GtkProgressBar:orientation ##### -->
 105 <para>
 106
 107 </para>
 108
 109 <!-- ##### ARG GtkProgressBar:pulse-step ##### -->
 110 <para>
 111
 112 </para>
 113
 114 <!-- ##### ARG GtkProgressBar:text ##### -->
 115 <para>
 116
 117 </para>
 118
 119 <!-- ##### ARG GtkProgressBar:min-horizontal-bar-height ##### -->
 120 <para>
 121
 122 </para>
 123
 124 <!-- ##### ARG GtkProgressBar:min-horizontal-bar-width ##### -->
 125 <para>
 126
 127 </para>
 128
 129 <!-- ##### ARG GtkProgressBar:min-vertical-bar-height ##### -->
 130 <para>
 131
 132 </para>
 133
 134 <!-- ##### ARG GtkProgressBar:min-vertical-bar-width ##### -->
 135 <para>
 136
 137 </para>
 138
 139 <!-- ##### ARG GtkProgressBar:xspacing ##### -->
 140 <para>
 141
 142 </para>
 143
 144 <!-- ##### ARG GtkProgressBar:yspacing ##### -->
 145 <para>
 146
 147 </para>
 148
 149 <!-- ##### FUNCTION gtk_progress_bar_new ##### -->
 150 <para>
 151 Creates a new #GtkProgressBar.
 152 </para>
 153
 154 @Returns: a #GtkProgressBar.
 155
 156
 157 <!-- ##### FUNCTION gtk_progress_bar_pulse ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @pbar:
 163
 164
 165 <!-- ##### FUNCTION gtk_progress_bar_set_text ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @pbar:
 171 @text:
 172
 173
 174 <!-- ##### FUNCTION gtk_progress_bar_set_fraction ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @pbar:
 180 @fraction:
 181
 182
 183 <!-- ##### FUNCTION gtk_progress_bar_set_pulse_step ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @pbar:
 189 @fraction:
 190
 191
 192 <!-- ##### FUNCTION gtk_progress_bar_set_orientation ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @pbar:
 198 @orientation:
 199
 200
 201 <!-- ##### FUNCTION gtk_progress_bar_set_ellipsize ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @pbar:
 207 @mode:
 208
 209
 210 <!-- ##### ENUM GtkProgressBarOrientation ##### -->
 211 <para>
 212 An enumeration representing possible orientations and growth
 213 directions for the visible progress bar.
 214 </para>
 215
 216 @GTK_PROGRESS_LEFT_TO_RIGHT: A horizontal progress bar growing from left to right.
 217 @GTK_PROGRESS_RIGHT_TO_LEFT: A horizontal progress bar growing from right to left.
 218 @GTK_PROGRESS_BOTTOM_TO_TOP: A vertical progress bar growing from bottom to top.
 219 @GTK_PROGRESS_TOP_TO_BOTTOM: A vertical progress bar growing from top to bottom.
 220
 221 <!-- ##### FUNCTION gtk_progress_bar_get_text ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @pbar:
 227 @Returns:
 228
 229
 230 <!-- ##### FUNCTION gtk_progress_bar_get_fraction ##### -->
 231 <para>
 232
 233 </para>
 234
 235 @pbar:
 236 @Returns:
 237
 238
 239 <!-- ##### FUNCTION gtk_progress_bar_get_pulse_step ##### -->
 240 <para>
 241
 242 </para>
 243
 244 @pbar:
 245 @Returns:
 246
 247
 248 <!-- ##### FUNCTION gtk_progress_bar_get_orientation ##### -->
 249 <para>
 250
 251 </para>
 252
 253 @pbar:
 254 @Returns:
 255
 256
 257 <!-- ##### FUNCTION gtk_progress_bar_get_ellipsize ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @pbar:
 263 @Returns:
 264
 265
 266 <!-- ##### FUNCTION gtk_progress_bar_new_with_adjustment ##### -->
 267
 268
 269 @adjustment:
 270 @Returns:
 271
 272
 273 <!-- ##### FUNCTION gtk_progress_bar_set_bar_style ##### -->
 274 <para>
 275 Sets the style of the #GtkProgressBar.  The default style is
 276 %GTK_PROGRESS_CONTINUOUS.
 277 </para>
 278
 279 @pbar: a #GtkProgressBar.
 280 @style: a #GtkProgressBarStyle value indicating the desired style.
 281
 282
 283 <!-- ##### ENUM GtkProgressBarStyle ##### -->
 284 <para>
 285 An enumeration representing the styles for drawing the progress bar.
 286 </para>
 287
 288 @GTK_PROGRESS_CONTINUOUS: The progress bar grows in a smooth, continuous manner.
 289 @GTK_PROGRESS_DISCRETE: The progress bar grows in discrete, visible blocks.
 290
 291 <!-- ##### FUNCTION gtk_progress_bar_set_discrete_blocks ##### -->
 292 <para>
 293 Sets the number of blocks that the progress bar is divided into
 294 when the style is %GTK_PROGRESS_DISCRETE.
 295 </para>
 296
 297 @pbar: a #GtkProgressBar.
 298 @blocks: number of individual blocks making up the bar.
 299
 300
 301 <!-- ##### FUNCTION gtk_progress_bar_set_activity_step ##### -->
 302 <para>
 303 Sets the step value used when the progress bar is in activity
 304 mode.  The step is the amount by which the progress is incremented
 305 each iteration.
 306 </para>
 307
 308 @pbar: a #GtkProgressBar.
 309 @step: the amount which the progress is incremented in activity
 310 mode.
 311
 312
 313 <!-- ##### FUNCTION gtk_progress_bar_set_activity_blocks ##### -->
 314 <para>
 315 Sets the number of blocks used when the progress bar is in activity
 316 mode.  Larger numbers make the visible block smaller.
 317 </para>
 318
 319 @pbar: a #GtkProgressBar.
 320 @blocks: number of blocks which can fit within the progress bar area.
 321
 322
 323 <!-- ##### FUNCTION gtk_progress_bar_update ##### -->
 324 <para>
 325 This function is deprecated.  Please use gtk_progress_set_value() or
 326 gtk_progress_set_percentage() instead.
 327 </para>
 328
 329 @pbar: a #GtkProgressBar.
 330 @percentage: the new percent complete value.
 331
 332