From d58655b4ae17b21af26db49b406d200154f0ba01 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 19 Feb 2021 15:43:33 -0500 Subject: [PATCH] progressbar: Convert docs Change link syntax, add an example image, generally clean things up. --- gtk/gtkprogressbar.c | 168 ++++++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 64 deletions(-) diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c index 417c4538a0..2f7355c611 100644 --- a/gtk/gtkprogressbar.c +++ b/gtk/gtkprogressbar.c @@ -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. + * + * ![An example GtkProgressBar](progressbar.png) * * 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)