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