AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

infobar: Convert docs

Browse Source 
Change link syntax, add an example image, generally clean things up.
This commit is contained in:
Matthias Clasen 2021-02-19 16:01:07 -05:00 committed by Emmanuele Bassi
parent d58655b4ae
commit 8de0a2c7c6
1 changed files with 103 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
gtk/gtkinfobar.c
View File

@ -53,27 +53,30 @@
* @include: gtk/gtk.h
* @see_also: #GtkStatusbar, #GtkMessageDialog
*
* #GtkInfoBar is a widget that can be used to show messages to
* the user without showing a dialog. It is often temporarily shown
* at the top or bottom of a document. In contrast to #GtkDialog, which
* has an action area at the bottom, #GtkInfoBar has an action area
* at the side.
* `GtkInfoBar` is a widget that can be used to show messages to
* the user without showing a dialog.
*
* The API of #GtkInfoBar is very similar to #GtkDialog, allowing you
* to add buttons to the action area with gtk_info_bar_add_button() or
* gtk_info_bar_new_with_buttons(). The sensitivity of action widgets
* can be controlled with gtk_info_bar_set_response_sensitive().
* ![An example GtkInfoBar](infobar.png)
*
* To add widgets to the main content area of a #GtkInfoBar, use
* gtk_info_bar_add_child().
* It is often temporarily shown at the top or bottom of a document.
* In contrast to [class@Gtk.Dialog], which has an action area at the
* bottom, `GtkInfoBar` has an action area at the side.
*
* Similar to #GtkMessageDialog, the contents of a #GtkInfoBar can by
* classified as error message, warning, informational message, etc,
* by using gtk_info_bar_set_message_type(). GTK may use the message type
* to determine how the message is displayed.
* The API of `GtkInfoBar` is very similar to `GtkDialog`, allowing you
* to add buttons to the action area with [method@Gtk.InfoBar.add_button]
* or [ctor@Gtk.InfoBar.new_with_buttons]. The sensitivity of action widgets
* can be controlled with [method@Gtk.InfoBar.set_response_sensitive].
*
* A simple example for using a #GtkInfoBar:
* |[<!-- language="C" -->
* To add widgets to the main content area of a `GtkInfoBar`, use
* [method@Gtk.InfoBar.add_child].
*
* Similar to [class@Gtk.MessageDialog], the contents of a `GtkInfoBar`
* can by classified as error message, warning, informational message, etc,
* by using [method@Gtk.InfoBar.set_message_type]. GTK may use the message
* type to determine how the message is displayed.
*
* A simple example for using a `GtkInfoBar`:
* ```c
* GtkWidget *message_label;
* GtkWidget *widget;
* GtkWidget *grid;
@ -103,22 +106,22 @@
* gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!");
* gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR);
* gtk_widget_show (bar);
* ]|
* ```
*
* # GtkInfoBar as GtkBuildable
*
* The GtkInfoBar implementation of the GtkBuildable interface exposes
* The `GtkInfoBar` implementation of the `GtkBuildable` interface exposes
* the content area and action area as internal children with the names
* “content_area” and “action_area”.
*
* GtkInfoBar supports a custom <action-widgets> element, which can contain
* `GtkInfoBar` supports a custom <action-widgets> element, which can contain
* multiple <action-widget> elements. The “response” attribute specifies a
* numeric response, and the content of the element is the id of widget
* (which should be a child of the dialogs @action_area).
*
* # CSS nodes
*
* GtkInfoBar has a single CSS node with name infobar. The node may get
* `GtkInfoBar` has a single CSS node with name infobar. The node may get
* one of the style classes .info, .warning, .error or .question, depending
* on the message type.
* If the info bar shows a close button, that button will have the .close
@ -372,6 +375,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
/**
* GtkInfoBar:revealed:
*
* Whether the info bar shows its contents.
*/
props[PROP_REVEALED] =
g_param_spec_boolean ("revealed",
P_("Reveal"),
@ -386,9 +394,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
* @info_bar: the object on which the signal is emitted
* @response_id: the response ID
*
* Emitted when an action widget is clicked or the application programmer
* calls gtk_info_bar_response(). The @response_id depends on which action
* widget was clicked.
* Emitted when an action widget is clicked.
*
* The signal is also emitted when the application programmer
* calls [method@Gtk.InfoBar.response]. The @response_id depends
* on which action widget was clicked.
*/
signals[RESPONSE] = g_signal_new (I_("response"),
G_OBJECT_CLASS_TYPE (klass),
@ -402,10 +412,9 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass)
/**
* GtkInfoBar::close:
*
* The ::close signal is a
* [keybinding signal][GtkSignalAction]
* which gets emitted when the user uses a keybinding to dismiss
* the info bar.
* Gets emitted when the user uses a keybinding to dismiss the info bar.
*
* The ::close signal is a [keybinding signal](class.SignalAction.html).
*
* The default binding for this signal is the Escape key.
*/
@ -523,14 +532,16 @@ action_widget_activated (GtkWidget *widget,
/**
* gtk_info_bar_add_action_widget:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @child: an activatable widget
* @response_id: response ID for @child
*
* Add an activatable widget to the action area of a #GtkInfoBar,
* connecting a signal handler that will emit the #GtkInfoBar::response
* signal on the message area when the widget is activated. The widget
* is appended to the end of the message areas action area.
* Add an activatable widget to the action area of a `GtkInfoBar`.
*
* This also connects a signal handler that will emit the
* [signal@Gtk.InfoBar::response] signal on the message area
* when the widget is activated. The widget is appended to the
* end of the message areas action area.
*/
void
gtk_info_bar_add_action_widget (GtkInfoBar *info_bar,
@ -569,12 +580,13 @@ gtk_info_bar_add_action_widget (GtkInfoBar *info_bar,
/**
* gtk_info_bar_remove_action_widget:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @widget: an action widget to remove
*
* Removes a widget from the action area of @info_bar, after
* it been put there by a call to gtk_info_bar_add_action_widget()
* or gtk_info_bar_add_button().
* Removes a widget from the action area of @info_bar.
*
* The widget must have been put there by a call to
* [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button].
*/
void
gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar,
@ -591,17 +603,18 @@ gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar,
/**
* gtk_info_bar_add_button:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @button_text: text of button
* @response_id: response ID for the button
*
* Adds a button with the given text and sets things up so that
* clicking the button will emit the “response” signal with the given
* response_id. The button is appended to the end of the info bars's
* action area. The button widget is returned, but usually you don't
* need it.
* Adds a button with the given text.
*
* Returns: (transfer none) (type Gtk.Button): the #GtkButton widget
* Clicking the button will emit the [signal@Gtk.InfoBar::response]
* signal with the given response_id. The button is appended to the
* end of the info bars's action area. The button widget is returned,
* but usually you don't need it.
*
* Returns: (transfer none) (type Gtk.Button): the `GtkButton` widget
* that was added
*/
GtkWidget*
@ -654,14 +667,16 @@ add_buttons_valist (GtkInfoBar *info_bar,
/**
* gtk_info_bar_add_buttons:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @first_button_text: button text
* @...: response ID for first button, then more text-response_id pairs,
* ending with %NULL
*
* Adds more buttons, same as calling gtk_info_bar_add_button()
* Adds multiple buttons.
*
* This is the same as calling [method@Gtk.InfoBar.add_button]
* repeatedly. The variable argument list should be %NULL-terminated
* as with gtk_info_bar_new_with_buttons(). Each button must have both
* as with [ctor@Gtk.InfoBar.new_with_buttons]. Each button must have both
* text and response ID.
*/
void
@ -679,9 +694,9 @@ gtk_info_bar_add_buttons (GtkInfoBar *info_bar,
/**
* gtk_info_bar_new:
*
* Creates a new #GtkInfoBar object.
* Creates a new `GtkInfoBar` object.
*
* Returns: a new #GtkInfoBar object
* Returns: a new `GtkInfoBar` object
*/
GtkWidget *
gtk_info_bar_new (void)
@ -695,14 +710,16 @@ gtk_info_bar_new (void)
* @...: response ID for first button, then additional buttons, ending
* with %NULL
*
* Creates a new #GtkInfoBar with buttons. Button text/response ID
* pairs should be listed, with a %NULL pointer ending the list.
* A response ID can be any positive number,
* or one of the values in the #GtkResponseType enumeration. If the
* user clicks one of these dialog buttons, GtkInfoBar will emit
* the “response” signal with the corresponding response ID.
* Creates a new `GtkInfoBar` with buttons.
*
* Returns: a new #GtkInfoBar
* Button text/response ID pairs should be listed, with a %NULL pointer
* ending the list. A response ID can be any positive number,
* or one of the values in the `GtkResponseType` enumeration. If the
* user clicks one of these dialog buttons, GtkInfoBar will emit
* the [signal@Gtk.InfoBar::response] signal with the corresponding
* response ID.
*
* Returns: a new `GtkInfoBar`
*/
GtkWidget*
gtk_info_bar_new_with_buttons (const char *first_button_text,
@ -736,13 +753,15 @@ update_default_response (GtkInfoBar *info_bar,
/**
* gtk_info_bar_set_response_sensitive:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @response_id: a response ID
* @setting: TRUE for sensitive
*
* Calls gtk_widget_set_sensitive (widget, setting) for each
* widget in the info bars’s action area with the given response_id.
* A convenient way to sensitize/desensitize dialog buttons.
* Sets the sensitivity of action widgets for @response_id.
*
* Calls `gtk_widget_set_sensitive (widget, setting)` for each
* widget in the info bars’s action area with the given @response_id.
* A convenient way to sensitize/desensitize buttons.
*/
void
gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar,
@ -769,15 +788,16 @@ gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar,
/**
* gtk_info_bar_set_default_response:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @response_id: a response ID
*
* Sets the last widget in the info bar’s action area with
* the given response_id as the default widget for the dialog.
*
* Pressing “Enter” normally activates the default widget.
*
* Note that this function currently requires @info_bar to
* be added to a widget hierarchy.
* be added to a widget hierarchy.
*/
void
gtk_info_bar_set_default_response (GtkInfoBar *info_bar,
@ -810,7 +830,7 @@ gtk_info_bar_set_default_response (GtkInfoBar *info_bar,
/**
* gtk_info_bar_response:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @response_id: a response ID
*
* Emits the “response” signal with the given @response_id.
@ -1054,7 +1074,7 @@ gtk_info_bar_buildable_add_child (GtkBuildable *buildable,
/**
* gtk_info_bar_set_message_type:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @message_type: a #GtkMessageType
*
* Sets the message type of the message area.
@ -1093,7 +1113,7 @@ gtk_info_bar_set_message_type (GtkInfoBar *info_bar,
/**
* gtk_info_bar_get_message_type:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
*
* Returns the message type of the message area.
*
@ -1110,11 +1130,12 @@ gtk_info_bar_get_message_type (GtkInfoBar *info_bar)
/**
* gtk_info_bar_set_show_close_button:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @setting: %TRUE to include a close button
*
* If true, a standard close button is shown. When clicked it emits
* the response %GTK_RESPONSE_CLOSE.
* If true, a standard close button is shown.
*
* When clicked it emits the response %GTK_RESPONSE_CLOSE.
*/
void
gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar,
@ -1131,7 +1152,7 @@ gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar,
/**
* gtk_info_bar_get_show_close_button:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
*
* Returns whether the widget will display a standard close button.
*
@ -1147,14 +1168,17 @@ gtk_info_bar_get_show_close_button (GtkInfoBar *info_bar)
/**
* gtk_info_bar_set_revealed:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @revealed: The new value of the property
*
* Sets the #GtkInfoBar:revealed property to @revealed. Changing this will make
* @info_bar reveal (%TRUE) or conceal (%FALSE) itself via a sliding transition.
* Sets whether the `GtkInfoBar` is revealed.
*
* Note: this does not show or hide @info_bar in the #GtkWidget:visible sense,
* so revealing has no effect if #GtkWidget:visible is %FALSE.
* Changing this will make @info_bar reveal or conceal
* itself via a sliding transition.
*
* Note: this does not show or hide @info_bar in the
* [property@Gtk.Widget:visible] sense, so revealing has no effect
* if [property@Gtk.Widget:visible] is %FALSE.
*/
void
gtk_info_bar_set_revealed (GtkInfoBar *info_bar,
@ -1171,11 +1195,11 @@ gtk_info_bar_set_revealed (GtkInfoBar *info_bar,
/**
* gtk_info_bar_get_revealed:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
*
* Returns whether the info bar is currently revealed.
*
* Returns: the current value of the #GtkInfoBar:revealed property
* Returns: the current value of the [property@Gtk.InfoBar:revealed] property
*/
gboolean
gtk_info_bar_get_revealed (GtkInfoBar *info_bar)
@ -1187,7 +1211,7 @@ gtk_info_bar_get_revealed (GtkInfoBar *info_bar)
/**
* gtk_info_bar_add_child:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @widget: the child to be added
*
* Adds a widget to the content area of the info bar.
@ -1204,11 +1228,10 @@ gtk_info_bar_add_child (GtkInfoBar *info_bar,
/**
* gtk_info_bar_remove_child:
* @info_bar: a #GtkInfoBar
* @info_bar: a `GtkInfoBar`
* @widget: a child that has been added to the content area
*
* Removes a widget from the content area of the info bar,
* after it has been added with gtk_info_bar_add_child().
* Removes a widget from the content area of the info bar.
*/
void
gtk_info_bar_remove_child (GtkInfoBar *info_bar,
@ -1219,4 +1242,3 @@ gtk_info_bar_remove_child (GtkInfoBar *info_bar,
gtk_box_remove (GTK_BOX (info_bar->content_area), widget);
}