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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkProgress
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Base class for GtkProgressBar
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GtkProgress is the abstract base class used to derive
  10 a #GtkProgressBar which provides a visual representation of
  11 the progress of a long running operation.
  12 </para>
  13
  14 <!-- ##### SECTION See_Also ##### -->
  15 <para>
  16
  17 </para>
  18
  19 <!-- ##### SECTION Stability_Level ##### -->
  20
  21
  22 <!-- ##### SECTION Image ##### -->
  23
  24
  25 <!-- ##### STRUCT GtkProgress ##### -->
  26 <para>
  27 The #GtkProgress-struct struct contains private data only.
  28 and should be accessed using the functions below.
  29 </para>
  30
  31
  32 <!-- ##### ARG GtkProgress:activity-mode ##### -->
  33 <para>
  34
  35 </para>
  36
  37 <!-- ##### ARG GtkProgress:show-text ##### -->
  38 <para>
  39
  40 </para>
  41
  42 <!-- ##### ARG GtkProgress:text-xalign ##### -->
  43 <para>
  44
  45 </para>
  46
  47 <!-- ##### ARG GtkProgress:text-yalign ##### -->
  48 <para>
  49
  50 </para>
  51
  52 <!-- ##### FUNCTION gtk_progress_set_show_text ##### -->
  53 <para>
  54 Controls whether progress text is shown.
  55 </para>
  56
  57 @progress: a #GtkProgress.
  58 @show_text: a boolean indicating whether the progress text
  59 is shown.
  60
  61
  62 <!-- ##### FUNCTION gtk_progress_set_text_alignment ##### -->
  63 <para>
  64 Controls the alignment of the text within the progress bar area.
  65 </para>
  66
  67 @progress: a #GtkProgress.
  68 @x_align: a number between 0.0 and 1.0 indicating the horizontal
  69 alignment of the progress text within the #GtkProgress.
  70 @y_align: a number between 0.0 and 1.0 indicating the vertical
  71 alignment of the progress text within the #GtkProgress.
  72
  73
  74 <!-- ##### FUNCTION gtk_progress_set_format_string ##### -->
  75 <para>
  76 Sets a format string used to display text indicating the
  77 current progress.  The string can contain the following substitution characters:
  78
  79 <itemizedlist>
  80 <listitem>
  81 <para>
  82 &percnt;v - the current progress value.
  83 </para>
  84 </listitem>
  85 <listitem>
  86 <para>
  87 &percnt;l - the lower bound for the progress value.
  88 </para>
  89 </listitem>
  90 <listitem>
  91 <para>
  92 &percnt;u - the upper bound for the progress value.
  93 </para>
  94 </listitem>
  95 <listitem>
  96 <para>
  97 &percnt;p - the current progress percentage.
  98 </para>
  99 </listitem>
 100 </itemizedlist>
 101 </para>
 102
 103 @progress: a #GtkProgress.
 104 @format: a string used to display progress text, or %NULL
 105          to restore to the default format.
 106
 107
 108 <!-- ##### FUNCTION gtk_progress_set_adjustment ##### -->
 109 <para>
 110 Associates a #GtkAdjustment with the #GtkProgress.  A #GtkAdjustment
 111 is used to represent the upper and lower bounds and the step interval
 112 of the underlying value for which progress is shown.
 113 </para>
 114
 115 @progress: a #GtkProgress.
 116 @adjustment: the #GtkAdjustment to be associated with the #GtkProgress.
 117
 118
 119 <!-- ##### FUNCTION gtk_progress_set_percentage ##### -->
 120 <para>
 121 Sets the current percentage completion for the #GtkProgress.
 122 </para>
 123
 124 @progress: a #GtkProgress.
 125 @percentage: the percentage complete which must be between 0.0
 126 and 1.0.
 127
 128
 129 <!-- ##### FUNCTION gtk_progress_set_value ##### -->
 130 <para>
 131 Sets the value within the #GtkProgress to an absolute value.
 132 The value must be within the valid range of values for the
 133 underlying #GtkAdjustment.
 134 </para>
 135
 136 @progress: a #GtkProgress.
 137 @value: the value indicating the current completed amount.
 138
 139
 140 <!-- ##### FUNCTION gtk_progress_get_value ##### -->
 141 <para>
 142 Returns the current progress complete value.
 143 </para>
 144
 145 @progress: a #GtkProgress.
 146 @Returns: the current progress complete value.
 147
 148
 149 <!-- ##### FUNCTION gtk_progress_set_activity_mode ##### -->
 150 <para>
 151 A #GtkProgress can be in one of two different modes: percentage
 152 mode (the default) and activity mode.  In activity mode, the
 153 progress is simply indicated as activity rather than as a percentage
 154 complete.
 155 </para>
 156
 157 @progress: a #GtkProgress.
 158 @activity_mode: a boolean, %TRUE for activity mode.
 159
 160
 161 <!-- ##### FUNCTION gtk_progress_get_current_text ##### -->
 162 <para>
 163 Returns the current text associated with the #GtkProgress.  This
 164 text is the based on the underlying format string after any substitutions
 165 are made.
 166 </para>
 167
 168 @progress: a #GtkProgress.
 169 @Returns: the text indicating the current progress.
 170
 171
 172 <!-- ##### FUNCTION gtk_progress_get_text_from_value ##### -->
 173 <para>
 174 Returns the text indicating the progress based on the supplied value.
 175 The current value for the #GtkProgress remains unchanged.
 176 </para>
 177
 178 @progress: a #GtkProgress.
 179 @value: an absolute progress value to use when formatting the progress text.
 180 @Returns: a string indicating the progress.
 181
 182
 183 <!-- ##### FUNCTION gtk_progress_get_current_percentage ##### -->
 184 <para>
 185 Returns the current progress as a percentage.
 186 </para>
 187
 188 @progress: a #GtkProgress.
 189 @Returns: a number between 0.0 and 1.0 indicating the percentage complete.
 190
 191
 192 <!-- ##### FUNCTION gtk_progress_get_percentage_from_value ##### -->
 193 <para>
 194 Returns the progress as a percentage calculated from the supplied
 195 absolute progress value.
 196 </para>
 197
 198 @progress: a #GtkProgress.
 199 @value: an absolute progress value.
 200 @Returns: a number between 0.0 and 1.0 indicating the percentage complete
 201 represented by @value.
 202
 203
 204 <!-- ##### FUNCTION gtk_progress_configure ##### -->
 205 <para>
 206 Allows the configuration of the minimum, maximum, and current values for
 207 the #GtkProgress.
 208 </para>
 209
 210 @progress: a #GtkProgress.
 211 @value: the current progress value.
 212 @min: the minimum progress value.
 213 @max: the maximum progress value.
 214
 215