forked from AuroraMiddleware/gtk
togglebutton: Convert docs
Change link syntax, add an example image, generally clean things up.
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
4bf7bfb41a
commit
ec78bf3309
@ -36,39 +36,48 @@
|
||||
#include "gtkprivate.h"
|
||||
|
||||
/**
|
||||
* SECTION:gtktogglebutton
|
||||
* @Short_description: Create buttons which retain their state
|
||||
* @Title: GtkToggleButton
|
||||
* @See_also: #GtkButton, #GtkCheckButton
|
||||
* GtkToggleButton:
|
||||
*
|
||||
* A #GtkToggleButton is a #GtkButton which will remain “pressed-in” when
|
||||
* clicked. Clicking again will cause the toggle button to return to its
|
||||
* normal state.
|
||||
* A `GtkToggleButton` is a button which remains “pressed-in” when
|
||||
* clicked.
|
||||
*
|
||||
* A toggle button is created by calling either gtk_toggle_button_new() or
|
||||
* gtk_toggle_button_new_with_label(). If using the former, it is advisable to
|
||||
* pack a widget, (such as a #GtkLabel and/or a #GtkImage), into the toggle
|
||||
* button’s container. (See #GtkButton for more information).
|
||||
* Clicking again will cause the toggle button to return to its normal state.
|
||||
*
|
||||
* The state of a #GtkToggleButton can be set specifically using
|
||||
* gtk_toggle_button_set_active(), and retrieved using
|
||||
* gtk_toggle_button_get_active().
|
||||
* A toggle button is created by calling either [ctor@Gtk.ToggleButton.new] or
|
||||
* [ctor@Gtk.ToggleButton.new_with_label]. If using the former, it is advisable
|
||||
* to pack a widget, (such as a `GtkLabel` and/or a `GtkImage`), into the toggle
|
||||
* button’s container. (See [class@Gtk.Button] for more information).
|
||||
*
|
||||
* To simply switch the state of a toggle button, use gtk_toggle_button_toggled().
|
||||
* The state of a `GtkToggleButton` can be set specifically using
|
||||
* [method@Gtk.ToggleButton.set_active], and retrieved using
|
||||
* [method@Gtk.ToggleButton.get_active].
|
||||
*
|
||||
* To simply switch the state of a toggle button, use
|
||||
* [method@Gtk.ToggleButton.toggled].
|
||||
*
|
||||
* # Grouping
|
||||
*
|
||||
* Toggle buttons can be grouped together, to form mutually exclusive
|
||||
* groups - only one of the buttons can be toggled at a time, and toggling
|
||||
* another one will switch the currently toggled one off.
|
||||
*
|
||||
* To add a `GtkToggleButton` to a group, use [method@Gtk.ToggleButton.set_group].
|
||||
*
|
||||
* # CSS nodes
|
||||
*
|
||||
* GtkToggleButton has a single CSS node with name button. To differentiate
|
||||
* it from a plain #GtkButton, it gets the .toggle style class.
|
||||
* `GtkToggleButton` has a single CSS node with name button. To differentiate
|
||||
* it from a plain `GtkButton`, it gets the .toggle style class.
|
||||
*
|
||||
* ## Creating two #GtkToggleButton widgets.
|
||||
* ## Creating two `GtkToggleButton` widgets.
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* static void output_state (GtkToggleButton *source, gpointer user_data) {
|
||||
* ```c
|
||||
* static void output_state (GtkToggleButton *source, gpointer user_data)
|
||||
* {
|
||||
* printf ("Active: %d\n", gtk_toggle_button_get_active (source));
|
||||
* }
|
||||
*
|
||||
* void make_toggles (void) {
|
||||
* void make_toggles (void)
|
||||
* {
|
||||
* GtkWidget *window, *toggle1, *toggle2;
|
||||
* GtkWidget *box;
|
||||
* const char *text;
|
||||
@ -94,7 +103,7 @@
|
||||
* gtk_window_set_child (GTK_WINDOW (window), box);
|
||||
* gtk_widget_show (window);
|
||||
* }
|
||||
* ]|
|
||||
* ```
|
||||
*/
|
||||
|
||||
typedef struct _GtkToggleButtonPrivate GtkToggleButtonPrivate;
|
||||
@ -254,6 +263,11 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
|
||||
|
||||
class->toggled = NULL;
|
||||
|
||||
/**
|
||||
* GtkToggleButton:active:
|
||||
*
|
||||
* If the toggle button should be pressed in.
|
||||
*/
|
||||
toggle_button_props[PROP_ACTIVE] =
|
||||
g_param_spec_boolean ("active",
|
||||
P_("Active"),
|
||||
@ -261,6 +275,11 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
|
||||
FALSE,
|
||||
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkToggleButton:group:
|
||||
*
|
||||
* The toggle button whose group this widget belongs to.
|
||||
*/
|
||||
toggle_button_props[PROP_GROUP] =
|
||||
g_param_spec_object ("group",
|
||||
P_("Group"),
|
||||
@ -274,8 +293,7 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class)
|
||||
* GtkToggleButton::toggled:
|
||||
* @togglebutton: the object which received the signal.
|
||||
*
|
||||
* Should be connected if you wish to perform an action whenever the
|
||||
* #GtkToggleButton's state is changed.
|
||||
* Emitted whenever the `GtkToggleButton`'s state is changed.
|
||||
*/
|
||||
toggle_button_signals[TOGGLED] =
|
||||
g_signal_new (I_("toggled"),
|
||||
@ -303,7 +321,9 @@ gtk_toggle_button_init (GtkToggleButton *toggle_button)
|
||||
/**
|
||||
* gtk_toggle_button_new:
|
||||
*
|
||||
* Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().
|
||||
* Creates a new toggle button.
|
||||
*
|
||||
* A widget should be packed into the button, as in [ctor@Gtk.Button.new].
|
||||
*
|
||||
* Returns: a new toggle button.
|
||||
*/
|
||||
@ -332,11 +352,12 @@ gtk_toggle_button_new_with_label (const char *label)
|
||||
* @label: the text of the button, with an underscore in front of the
|
||||
* mnemonic character
|
||||
*
|
||||
* Creates a new #GtkToggleButton containing a label. The label
|
||||
* will be created using gtk_label_new_with_mnemonic(), so underscores
|
||||
* in @label indicate the mnemonic for the button.
|
||||
* Creates a new `GtkToggleButton` containing a label.
|
||||
*
|
||||
* Returns: a new #GtkToggleButton
|
||||
* The label will be created using [ctor@Gtk.Label.new_with_mnemonic],
|
||||
* so underscores in @label indicate the mnemonic for the button.
|
||||
*
|
||||
* Returns: a new `GtkToggleButton`
|
||||
*/
|
||||
GtkWidget *
|
||||
gtk_toggle_button_new_with_mnemonic (const char *label)
|
||||
@ -349,14 +370,16 @@ gtk_toggle_button_new_with_mnemonic (const char *label)
|
||||
|
||||
/**
|
||||
* gtk_toggle_button_set_active:
|
||||
* @toggle_button: a #GtkToggleButton.
|
||||
* @toggle_button: a `GtkToggleButton`.
|
||||
* @is_active: %TRUE or %FALSE.
|
||||
*
|
||||
* Sets the status of the toggle button. Set to %TRUE if you want the
|
||||
* GtkToggleButton to be “pressed in”, and %FALSE to raise it.
|
||||
* Sets the status of the toggle button.
|
||||
*
|
||||
* Set to %TRUE if you want the `GtkToggleButton` to be “pressed in”,
|
||||
* and %FALSE to raise it.
|
||||
*
|
||||
* If the status of the button changes, this action causes the
|
||||
* #GtkToggleButton::toggled signal to be emitted.
|
||||
* [signal@GtkToggleButton::toggled] signal to be emitted.
|
||||
*/
|
||||
void
|
||||
gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
|
||||
@ -404,12 +427,14 @@ gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
|
||||
|
||||
/**
|
||||
* gtk_toggle_button_get_active:
|
||||
* @toggle_button: a #GtkToggleButton.
|
||||
* @toggle_button: a `GtkToggleButton`.
|
||||
*
|
||||
* Queries a #GtkToggleButton and returns its current state. Returns %TRUE if
|
||||
* the toggle button is pressed in and %FALSE if it is raised.
|
||||
* Queries a `GtkToggleButton` and returns its current state.
|
||||
*
|
||||
* Returns: a #gboolean value.
|
||||
* Returns %TRUE if the toggle button is pressed in and %FALSE
|
||||
* if it is raised.
|
||||
*
|
||||
* Returns: whether the button is pressed
|
||||
*/
|
||||
gboolean
|
||||
gtk_toggle_button_get_active (GtkToggleButton *toggle_button)
|
||||
@ -423,11 +448,11 @@ gtk_toggle_button_get_active (GtkToggleButton *toggle_button)
|
||||
|
||||
/**
|
||||
* gtk_toggle_button_toggled:
|
||||
* @toggle_button: a #GtkToggleButton.
|
||||
* @toggle_button: a `GtkToggleButton`.
|
||||
*
|
||||
* Emits the #GtkToggleButton::toggled signal on the
|
||||
* #GtkToggleButton. There is no good reason for an
|
||||
* application ever to call this function.
|
||||
* Emits the ::toggled signal on the `GtkToggleButton`.
|
||||
*
|
||||
* There is no good reason for an application ever to call this function.
|
||||
*/
|
||||
void
|
||||
gtk_toggle_button_toggled (GtkToggleButton *toggle_button)
|
||||
@ -439,18 +464,19 @@ gtk_toggle_button_toggled (GtkToggleButton *toggle_button)
|
||||
|
||||
/**
|
||||
* gtk_toggle_button_set_group:
|
||||
* @toggle_button: a #GtkToggleButton
|
||||
* @group: (nullable) (transfer none): another #GtkToggleButton to
|
||||
* @toggle_button: a `GtkToggleButton`
|
||||
* @group: (nullable) (transfer none): another `GtkToggleButton` to
|
||||
* form a group with
|
||||
*
|
||||
* Adds @self to the group of @group. In a group of multiple toggle buttons,
|
||||
* only one button can be active at a time.
|
||||
* Adds @self to the group of @group.
|
||||
*
|
||||
* Note that the same effect can be achieved via the #GtkActionable
|
||||
* api, by using the same action with parameter type and state type 's'
|
||||
* In a group of multiple toggle buttons, only one button can be active
|
||||
* at a time.
|
||||
*
|
||||
* Note that the same effect can be achieved via the [interface@Gtk.Actionable]
|
||||
* API, by using the same action with parameter type and state type 's'
|
||||
* for all buttons in the group, and giving each button its own target
|
||||
* value.
|
||||
|
||||
*/
|
||||
void
|
||||
gtk_toggle_button_set_group (GtkToggleButton *toggle_button,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user