mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2025-01-06 10:50:08 +00:00
progressbar: Convert docs
Change link syntax, add an example image, generally clean things up.
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
f2b482ef65
commit
d58655b4ae
@ -42,26 +42,29 @@
|
||||
* @Short_description: A widget which indicates progress visually
|
||||
* @Title: GtkProgressBar
|
||||
*
|
||||
* The #GtkProgressBar is typically used to display the progress of a long
|
||||
* running operation. It provides a visual clue that processing is underway.
|
||||
* The GtkProgressBar can be used in two different modes: percentage mode
|
||||
* and activity mode.
|
||||
* `GtkProgressBar` is typically used to display the progress of a long
|
||||
* running operation.
|
||||
*
|
||||
* It provides a visual clue that processing is underway. `GtkProgressBar`
|
||||
* can be used in two different modes: percentage mode and activity mode.
|
||||
*
|
||||
* 
|
||||
*
|
||||
* When an application can determine how much work needs to take place
|
||||
* (e.g. read a fixed number of bytes from a file) and can monitor its
|
||||
* progress, it can use the GtkProgressBar in percentage mode and the
|
||||
* progress, it can use the `GtkProgressBar` in percentage mode and the
|
||||
* user sees a growing bar indicating the percentage of the work that
|
||||
* has been completed. In this mode, the application is required to call
|
||||
* gtk_progress_bar_set_fraction() periodically to update the progress bar.
|
||||
* [method@Gtk.ProgressBar.set_fraction] periodically to update the progress bar.
|
||||
*
|
||||
* When an application has no accurate way of knowing the amount of work
|
||||
* to do, it can use the #GtkProgressBar in activity mode, which shows
|
||||
* to do, it can use the `GtkProgressBar` in activity mode, which shows
|
||||
* activity by a block moving back and forth within the progress area. In
|
||||
* this mode, the application is required to call gtk_progress_bar_pulse()
|
||||
* this mode, the application is required to call [method@Gtk.ProgressBar.pulse]
|
||||
* periodically to update the progress bar.
|
||||
*
|
||||
* There is quite a bit of flexibility provided to control the appearance
|
||||
* of the #GtkProgressBar. Functions are provided to control the orientation
|
||||
* of the `GtkProgressBar`. Functions are provided to control the orientation
|
||||
* of the bar, optional text can be displayed along with the bar, and the
|
||||
* step size used in activity mode can be set.
|
||||
*
|
||||
@ -74,7 +77,7 @@
|
||||
* ╰── progress[.pulse]
|
||||
* ]|
|
||||
*
|
||||
* GtkProgressBar has a main CSS node with name progressbar and subnodes with
|
||||
* `GtkProgressBar` has a main CSS node with name progressbar and subnodes with
|
||||
* names text and trough, of which the latter has a subnode named progress. The
|
||||
* text subnode is only present if text is shown. The progress subnode has the
|
||||
* style class .pulse when in activity mode. It gets the style classes .left,
|
||||
@ -84,7 +87,7 @@
|
||||
*
|
||||
* # Accessibility
|
||||
*
|
||||
* GtkProgressBar uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
|
||||
* `GtkProgressBar` uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
|
||||
*/
|
||||
|
||||
typedef struct _GtkProgressBarClass GtkProgressBarClass;
|
||||
@ -177,6 +180,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
|
||||
g_object_class_override_property (gobject_class, PROP_ORIENTATION, "orientation");
|
||||
|
||||
/**
|
||||
* GtkProgressBar:inverted:
|
||||
*
|
||||
* Invert the direction in which the progress bar grows.
|
||||
*/
|
||||
progress_props[PROP_INVERTED] =
|
||||
g_param_spec_boolean ("inverted",
|
||||
P_("Inverted"),
|
||||
@ -184,6 +192,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
FALSE,
|
||||
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkProgressBar:fraction:
|
||||
*
|
||||
* The fraction of total work that has been completed.
|
||||
*/
|
||||
progress_props[PROP_FRACTION] =
|
||||
g_param_spec_double ("fraction",
|
||||
P_("Fraction"),
|
||||
@ -192,6 +205,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
0.0,
|
||||
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkProgressBar:pulse-step:
|
||||
*
|
||||
* The fraction of total progress to move the bounding block when pulsed.
|
||||
*/
|
||||
progress_props[PROP_PULSE_STEP] =
|
||||
g_param_spec_double ("pulse-step",
|
||||
P_("Pulse Step"),
|
||||
@ -200,6 +218,11 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
0.1,
|
||||
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkProgressBar:text:
|
||||
*
|
||||
* Text to be displayed in the progress bar.
|
||||
*/
|
||||
progress_props[PROP_TEXT] =
|
||||
g_param_spec_string ("text",
|
||||
P_("Text"),
|
||||
@ -211,14 +234,15 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
* GtkProgressBar:show-text:
|
||||
*
|
||||
* Sets whether the progress bar will show a text in addition
|
||||
* to the bar itself. The shown text is either the value of
|
||||
* the #GtkProgressBar:text property or, if that is %NULL,
|
||||
* the #GtkProgressBar:fraction value, as a percentage.
|
||||
* to the bar itself.
|
||||
*
|
||||
* To make a progress bar that is styled and sized suitably for
|
||||
* showing text (even if the actual text is blank), set
|
||||
* #GtkProgressBar:show-text to %TRUE and #GtkProgressBar:text
|
||||
* to the empty string (not %NULL).
|
||||
* The shown text is either the value of the [property@Gtk.ProgressBar:text]
|
||||
* property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction]
|
||||
* value, as a percentage.
|
||||
*
|
||||
* To make a progress bar that is styled and sized suitably for showing text
|
||||
* (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text]
|
||||
* to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL).
|
||||
*/
|
||||
progress_props[PROP_SHOW_TEXT] =
|
||||
g_param_spec_boolean ("show-text",
|
||||
@ -230,14 +254,15 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
|
||||
/**
|
||||
* GtkProgressBar:ellipsize:
|
||||
*
|
||||
* The preferred place to ellipsize the string, if the progress bar does
|
||||
* not have enough room to display the entire string, specified as a
|
||||
* #PangoEllipsizeMode.
|
||||
* The preferred place to ellipsize the string.
|
||||
*
|
||||
* The text will be ellipsized if the progress bar does not have enough room
|
||||
* to display the entire string, specified as a `PangoEllipsizeMode`.
|
||||
*
|
||||
* Note that setting this property to a value other than
|
||||
* %PANGO_ELLIPSIZE_NONE has the side-effect that the progress bar requests
|
||||
* only enough space to display the ellipsis ("..."). Another means to set a
|
||||
* progress bar's width is gtk_widget_set_size_request().
|
||||
* progress bar's width is [method@Gtk.Widget.set_size_request].
|
||||
*/
|
||||
progress_props[PROP_ELLIPSIZE] =
|
||||
g_param_spec_enum ("ellipsize",
|
||||
@ -548,9 +573,9 @@ gtk_progress_bar_get_property (GObject *object,
|
||||
/**
|
||||
* gtk_progress_bar_new:
|
||||
*
|
||||
* Creates a new #GtkProgressBar.
|
||||
* Creates a new `GtkProgressBar`.
|
||||
*
|
||||
* Returns: a #GtkProgressBar.
|
||||
* Returns: a `GtkProgressBar`.
|
||||
*/
|
||||
GtkWidget*
|
||||
gtk_progress_bar_new (void)
|
||||
@ -727,12 +752,13 @@ gtk_progress_bar_set_activity_mode (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_fraction:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @fraction: fraction of the task that’s been completed
|
||||
*
|
||||
* Causes the progress bar to “fill in” the given fraction
|
||||
* of the bar. The fraction should be between 0.0 and 1.0,
|
||||
* inclusive.
|
||||
* of the bar.
|
||||
*
|
||||
* The fraction should be between 0.0 and 1.0, inclusive.
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
|
||||
@ -790,13 +816,14 @@ gtk_progress_bar_update_pulse (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_pulse:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Indicates that some progress has been made, but you don’t know how much.
|
||||
*
|
||||
* Causes the progress bar to enter “activity mode,” where a block
|
||||
* bounces back and forth. Each call to gtk_progress_bar_pulse()
|
||||
* bounces back and forth. Each call to [method@Gtk.ProgressBar.pulse]
|
||||
* causes the block to move by a little bit (the amount of movement
|
||||
* per pulse is determined by gtk_progress_bar_set_pulse_step()).
|
||||
* per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]).
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_pulse (GtkProgressBar *pbar)
|
||||
@ -809,19 +836,20 @@ gtk_progress_bar_pulse (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_text:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @text: (allow-none): a UTF-8 string, or %NULL
|
||||
*
|
||||
* Causes the given @text to appear next to the progress bar.
|
||||
*
|
||||
* If @text is %NULL and #GtkProgressBar:show-text is %TRUE, the current
|
||||
* value of #GtkProgressBar:fraction will be displayed as a percentage.
|
||||
* If @text is %NULL and [property@Gtk.ProgressBar:show-text] is %TRUE,
|
||||
* the current value of [property@Gtk.ProgressBar:fraction] will be displayed
|
||||
* as a percentage.
|
||||
*
|
||||
* If @text is non-%NULL and #GtkProgressBar:show-text is %TRUE, the text
|
||||
* will be displayed. In this case, it will not display the progress
|
||||
* If @text is non-%NULL and [property@Gtk.ProgressBar:show-text] is %TRUE,
|
||||
* the text will be displayed. In this case, it will not display the progress
|
||||
* percentage. If @text is the empty string, the progress bar will still
|
||||
* be styled and sized suitably for containing text, as long as
|
||||
* #GtkProgressBar:show-text is %TRUE.
|
||||
* [property@Gtk.ProgressBar:show-text] is %TRUE.
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_set_text (GtkProgressBar *pbar,
|
||||
@ -844,17 +872,18 @@ gtk_progress_bar_set_text (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_show_text:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @show_text: whether to show text
|
||||
*
|
||||
* Sets whether the progress bar will show text next to the bar.
|
||||
* The shown text is either the value of the #GtkProgressBar:text
|
||||
* property or, if that is %NULL, the #GtkProgressBar:fraction value,
|
||||
*
|
||||
* The shown text is either the value of the [property@Gtk.ProgressBar:text]
|
||||
* property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value,
|
||||
* as a percentage.
|
||||
*
|
||||
* To make a progress bar that is styled and sized suitably for containing
|
||||
* text (even if the actual text is blank), set #GtkProgressBar:show-text to
|
||||
* %TRUE and #GtkProgressBar:text to the empty string (not %NULL).
|
||||
* text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text]
|
||||
* to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL).
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_set_show_text (GtkProgressBar *pbar,
|
||||
@ -893,10 +922,11 @@ gtk_progress_bar_set_show_text (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_show_text:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Gets the value of the #GtkProgressBar:show-text property.
|
||||
* See gtk_progress_bar_set_show_text().
|
||||
* Returns whether the `GtkProgressBar` shows text.
|
||||
*
|
||||
* See [method@Gtk.ProgressBar.set_show_text].
|
||||
*
|
||||
* Returns: %TRUE if text is shown in the progress bar
|
||||
*/
|
||||
@ -910,11 +940,14 @@ gtk_progress_bar_get_show_text (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_pulse_step:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @fraction: fraction between 0.0 and 1.0
|
||||
*
|
||||
* Sets the fraction of total progress bar length to move the
|
||||
* bouncing block for each call to gtk_progress_bar_pulse().
|
||||
* bouncing block.
|
||||
*
|
||||
* The bouncing block is moved when [method@Gtk.ProgressBar.pulse]
|
||||
* is called.
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
|
||||
@ -975,9 +1008,11 @@ gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_inverted:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @inverted: %TRUE to invert the progress bar
|
||||
*
|
||||
* Sets whether the progress bar is inverted.
|
||||
*
|
||||
* Progress bars normally grow from top to bottom or left to right.
|
||||
* Inverted progress bars grow in the opposite direction.
|
||||
*/
|
||||
@ -999,12 +1034,12 @@ gtk_progress_bar_set_inverted (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_text:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Retrieves the text that is displayed with the progress bar,
|
||||
* if any, otherwise %NULL. The return value is a reference
|
||||
* to the text, not a copy of it, so will become invalid
|
||||
* if you change the text in the progress bar.
|
||||
* Retrieves the text that is displayed with the progress bar.
|
||||
*
|
||||
* The return value is a reference to the text, not a copy of it,
|
||||
* so will become invalid if you change the text in the progress bar.
|
||||
*
|
||||
* Returns: (nullable): text, or %NULL; this string is owned by the widget
|
||||
* and should not be modified or freed.
|
||||
@ -1019,7 +1054,7 @@ gtk_progress_bar_get_text (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_fraction:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Returns the current fraction of the task that’s been completed.
|
||||
*
|
||||
@ -1035,9 +1070,11 @@ gtk_progress_bar_get_fraction (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_pulse_step:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Retrieves the pulse step set with gtk_progress_bar_set_pulse_step().
|
||||
* Retrieves the pulse step.
|
||||
*
|
||||
* See [method@Gtk.ProgressBar.set_pulse_step].
|
||||
*
|
||||
* Returns: a fraction from 0.0 to 1.0
|
||||
*/
|
||||
@ -1051,9 +1088,9 @@ gtk_progress_bar_get_pulse_step (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_inverted:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Gets the value set by gtk_progress_bar_set_inverted().
|
||||
* Returns whether the progress bar is inverted.
|
||||
*
|
||||
* Returns: %TRUE if the progress bar is inverted
|
||||
*/
|
||||
@ -1067,11 +1104,13 @@ gtk_progress_bar_get_inverted (GtkProgressBar *pbar)
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_set_ellipsize:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @mode: a #PangoEllipsizeMode
|
||||
* @pbar: a `GtkProgressBar`
|
||||
* @mode: a `PangoEllipsizeMode`
|
||||
*
|
||||
* Sets the mode used to ellipsize (add an ellipsis: "...") the
|
||||
* text if there is not enough space to render the entire string.
|
||||
* Sets the mode used to ellipsize the text.
|
||||
*
|
||||
* The text is ellipsized if there is not enough space
|
||||
* to render the entire string.
|
||||
*/
|
||||
void
|
||||
gtk_progress_bar_set_ellipsize (GtkProgressBar *pbar,
|
||||
@ -1094,12 +1133,13 @@ gtk_progress_bar_set_ellipsize (GtkProgressBar *pbar,
|
||||
|
||||
/**
|
||||
* gtk_progress_bar_get_ellipsize:
|
||||
* @pbar: a #GtkProgressBar
|
||||
* @pbar: a `GtkProgressBar`
|
||||
*
|
||||
* Returns the ellipsizing position of the progress bar.
|
||||
* See gtk_progress_bar_set_ellipsize().
|
||||
*
|
||||
* Returns: #PangoEllipsizeMode
|
||||
* See [method@Gtk.ProgressBar.set_ellipsize].
|
||||
*
|
||||
* Returns: `PangoEllipsizeMode`
|
||||
*/
|
||||
PangoEllipsizeMode
|
||||
gtk_progress_bar_get_ellipsize (GtkProgressBar *pbar)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user