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