← Back to branch summary

~ubuntu-branches/ubuntu/raring/gtk+2.0/raring-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gtk/tmpl/gtkprogressbar.sgml

  • Committer: Package Import Robot
  • Author(s): Ken VanDine
  • Date: 2011-12-01 11:40:06 UTC
  • mfrom: (1.14.11)
  • Revision ID: package-import@ubuntu.com-20111201114006-nrmf6qu3pg512veo
Tags: 2.24.8-0ubuntu1
https://launchpad.net/bugs/189494
https://launchpad.net/bugs/889019
* New upstream release 
  - gtkfilechooser should be more robust to malformed URIs
    in .gtk-bookmarks (LP: #189494)
* debian/patches/010_make_bg_changes_queue_repaint.patch
  - dropped it introduces performance regressions in some gtk2 
    apps (LP: #889019)
* 101_filechooser.patch, 000git_file_chooser.patch: dropped, upstream

Show diffs side-by-side

added added

removed removed

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