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

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