[gtk/ebassi/gidocgen: 274/483] notebook: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 274/483] notebook: Convert docs
- Date: Sun, 7 Mar 2021 16:13:19 +0000 (UTC)
commit 53226c4eba067f80e9f58aa6c94da18b6909cb22
Author: Matthias Clasen <mclasen redhat com>
Date: Sat Feb 27 18:20:56 2021 -0500
notebook: Convert docs
gtk/gtknotebook.c | 461 +++++++++++++++++++++++++++++++++---------------------
gtk/gtknotebook.h | 9 +-
2 files changed, 287 insertions(+), 183 deletions(-)
---
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index ed712517b4..3e65f125c8 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -59,24 +59,24 @@
#include <math.h>
/**
- * SECTION:gtknotebook
- * @Short_description: A tabbed notebook container
- * @Title: GtkNotebook
+ * GtkNotebook:
*
- * The #GtkNotebook widget is a layout container whose children are
- * pages that can be switched between using tab labels along one edge.
+ * `GtkNotebook` is a container whose children are pages switched
+ * between using tabs.
*
- * There are many configuration options for GtkNotebook. Among other
- * things, you can choose on which edge the tabs appear
- * (see gtk_notebook_set_tab_pos()), whether, if there are too many
- * tabs to fit the notebook should be made bigger or scrolling
- * arrows added (see gtk_notebook_set_scrollable()), and whether there
- * will be a popup menu allowing the users to switch pages.
- * (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable())
+ * 
+ *
+ * There are many configuration options for `GtkNotebook`. Among
+ * other things, you can choose on which edge the tabs appear
+ * (see [method@Gtk.Notebook.set_tab_pos]), whether, if there are
+ * too many tabs to fit the notebook should be made bigger or scrolling
+ * arrows added (see [method@Gtk.Notebook.set_scrollable]), and whether
+ * there will be a popup menu allowing the users to switch pages.
+ * (see [method@Gtk.Notebook.popup_enable]).
*
* # GtkNotebook as GtkBuildable
- *
- * The GtkNotebook implementation of the #GtkBuildable interface
+ *
+ * The `GtkNotebook` implementation of the `GtkBuildable` interface
* supports placing children into tabs by specifying “tab” as the
* “type” attribute of a <child> element. Note that the content
* of the tab must be created before the tab can be filled.
@@ -87,8 +87,9 @@
* "action-start" or “action-end” as the “type” attribute of the
* <child> element.
*
- * An example of a UI definition fragment with GtkNotebook:
- * |[
+ * An example of a UI definition fragment with `GtkNotebook`:
+ *
+ * ```xml
* <object class="GtkNotebook">
* <child>
* <object class="GtkLabel" id="notebook-content">
@@ -101,11 +102,11 @@
* </object>
* </child>
* </object>
- * ]|
+ * ```
*
* # CSS nodes
*
- * |[<!-- language="plain" -->
+ * ```
* notebook
* ├── header.top
* │ ├── [<action widget>]
@@ -123,9 +124,9 @@
* ├── <child>
* ┊
* ╰── <child>
- * ]|
+ * ```
*
- * GtkNotebook has a main CSS node with name `notebook`, a subnode
+ * `GtkNotebook` has a main CSS node with name `notebook`, a subnode
* with name `header` and below that a subnode with name `tabs` which
* contains one subnode per tab with name `tab`.
*
@@ -134,7 +135,7 @@
* name `arrow` are placed as first and last child of the `tabs` node.
*
* The main node gets the `.frame` style class when the notebook
- * has a border (see gtk_notebook_set_show_border()).
+ * has a border (see [method@Gtk.Notebook.set_show_border]).
*
* The header node gets one of the style class `.top`, `.bottom`,
* `.left` or `.right`, depending on where the tabs are placed. For
@@ -146,7 +147,7 @@
*
* # Accessibility
*
- * GtkNotebook uses the following roles:
+ * `GtkNotebook` uses the following roles:
*
* - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget
* - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs
@@ -154,6 +155,11 @@
* - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page
*/
+/**
+ * GtkNotebookPage:
+ *
+ * `GtkNotebookPage` is an auxiliary object used by `GtkNotebook`.
+ */
#define SCROLL_DELAY_FACTOR 5
#define SCROLL_THRESHOLD 12
@@ -569,6 +575,11 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
object_class->get_property = gtk_notebook_page_get_property;
object_class->set_property = gtk_notebook_page_set_property;
+ /**
+ * GtkNotebookPage:child: (attributes org.gtk.Property.get=gtk_notebook_page_get_child)
+ *
+ * The child for this page.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_CHILD,
g_param_spec_object ("child",
@@ -576,6 +587,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The child for this page"),
GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+ /**
+ * GtkNotebookPage:tab:
+ *
+ * The tab widget for tihs page.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_TAB,
g_param_spec_object ("tab",
@@ -583,6 +600,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The tab widget for this page"),
GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+ /**
+ * GtkNotebookPage:menu:
+ *
+ * The label widget displayed in the childs menu entry.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_MENU,
g_param_spec_object ("menu",
@@ -590,6 +613,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The label widget displayed in the child’s menu
entry"),
GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+ /**
+ * GtkNotebookPage:tab-label:
+ *
+ * The text of the tab widget.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_TAB_LABEL,
g_param_spec_string ("tab-label",
@@ -597,6 +626,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The text of the tab widget"),
NULL,
GTK_PARAM_READWRITE));
+
+ /**
+ * GtkNotebookPage:menu-label:
+ *
+ * The text of the menu widget.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_MENU_LABEL,
g_param_spec_string ("menu-label",
@@ -604,6 +639,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The text of the menu widget"),
NULL,
GTK_PARAM_READWRITE));
+
+ /**
+ * GtkNotebookPage:position:
+ *
+ * The index of the child in the parent.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_POSITION,
g_param_spec_int ("position",
@@ -611,6 +652,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("The index of the child in the parent"),
-1, G_MAXINT, 0,
GTK_PARAM_READWRITE));
+
+ /**
+ * GtkNotebookPage:tab-expand:
+ *
+ * Whether to expand the childs tab.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_TAB_EXPAND,
g_param_spec_boolean ("tab-expand",
@@ -618,6 +665,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("Whether to expand the child’s tab"),
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+ /**
+ * GtkNotebookPage:tab-fill:
+ *
+ * Whether the childs tab should fill the allocated area.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_TAB_FILL,
g_param_spec_boolean ("tab-fill",
@@ -625,6 +678,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("Whether the child’s tab should fill the
allocated area"),
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+ /**
+ * GtkNotebookPage:reorderable:
+ *
+ * Whether the tab is reorderable by user action.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_REORDERABLE,
g_param_spec_boolean ("reorderable",
@@ -632,6 +691,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
P_("Whether the tab is reorderable by user action"),
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+ /**
+ * GtkNotebookPage:detachable:
+ *
+ * Whether the tab is detachable.
+ */
g_object_class_install_property (object_class,
CHILD_PROP_DETACHABLE,
g_param_spec_boolean ("detachable",
@@ -1051,6 +1116,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
class->reorder_tab = gtk_notebook_reorder_tab;
class->create_window = gtk_notebook_create_window;
+ /**
+ * GtkNotebook:page: (attributes org.gtk.Property.get=gtk_notebook_get_current_page
org.gtk.Property.set=gtk_notebook_set_current_page)
+ *
+ * The index of the current page.
+ */
properties[PROP_PAGE] =
g_param_spec_int ("page",
P_("Page"),
@@ -1059,6 +1129,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
-1,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:tab-pos: (attributes org.gtk.Property.get=gtk_notebook_get_tab_pos
org.gtk.Property.set=gtk_notebook_set_tab_pos)
+ *
+ * Which side of the notebook holds the tabs.
+ */
properties[PROP_TAB_POS] =
g_param_spec_enum ("tab-pos",
P_("Tab Position"),
@@ -1067,6 +1142,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
GTK_POS_TOP,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:show-tabs: (attributes org.gtk.Property.get=gtk_notebook_get_show_tabs
org.gtk.Property.set=gtk_notebook_set_show_tabs)
+ *
+ * Whether tabs should be shown.
+ */
properties[PROP_SHOW_TABS] =
g_param_spec_boolean ("show-tabs",
P_("Show Tabs"),
@@ -1074,6 +1154,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:show-border: (attributes org.gtk.Property.get=gtk_notebook_get_show_border
org.gtk.Property.set=gtk_notebook_set_show_border)
+ *
+ * Whether the border should be shown.
+ */
properties[PROP_SHOW_BORDER] =
g_param_spec_boolean ("show-border",
P_("Show Border"),
@@ -1081,6 +1166,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:scrollable: (attributes org.gtk.Property.get=gtk_notebook_get_scrollable
org.gtk.Property.set=gtk_notebook_set_scrollable)
+ *
+ * If %TRUE, scroll arrows are added if there are too many pages to fit.
+ */
properties[PROP_SCROLLABLE] =
g_param_spec_boolean ("scrollable",
P_("Scrollable"),
@@ -1088,6 +1178,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:enable-popup:
+ *
+ * If %TRUE, pressing the right mouse button on the notebook shows a page switching menu.
+ */
properties[PROP_ENABLE_POPUP] =
g_param_spec_boolean ("enable-popup",
P_("Enable Popup"),
@@ -1096,7 +1191,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkNotebook:group-name:
+ * GtkNotebook:group-name: (attributes org.gtk.Property.get=gtk_notebook_get_group_name
org.gtk.Property.set=gtk_notebook_set_group_name)
*
* Group name for tab drag and drop.
*/
@@ -1107,6 +1202,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
NULL,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkNotebook:pages: (attributes org.gtk.Property.get=gtk_notebook_get_pages)
+ *
+ * A selection model with the pages.
+ */
properties[PROP_PAGES] =
g_param_spec_object ("pages",
P_("Pages"),
@@ -1197,7 +1297,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
_gtk_marshal_BOOLEAN__ENUM_BOOLEANv);
/**
* GtkNotebook::page-reordered:
- * @notebook: the #GtkNotebook
+ * @notebook: the `GtkNotebook`
* @child: the child #GtkWidget affected
* @page_num: the new page number for @child
*
@@ -1219,7 +1319,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
_gtk_marshal_VOID__OBJECT_UINTv);
/**
* GtkNotebook::page-removed:
- * @notebook: the #GtkNotebook
+ * @notebook: the `GtkNotebook`
* @child: the child #GtkWidget affected
* @page_num: the @child page number
*
@@ -1241,7 +1341,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
_gtk_marshal_VOID__OBJECT_UINTv);
/**
* GtkNotebook::page-added:
- * @notebook: the #GtkNotebook
+ * @notebook: the `GtkNotebook`
* @child: the child #GtkWidget affected
* @page_num: the new page number for @child
*
@@ -1264,7 +1364,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
/**
* GtkNotebook::create-window:
- * @notebook: the #GtkNotebook emitting the signal
+ * @notebook: the `GtkNotebook` emitting the signal
* @page: the tab of @notebook that is being detached
*
* The ::create-window signal is emitted when a detachable
@@ -1274,9 +1374,9 @@ gtk_notebook_class_init (GtkNotebookClass *class)
* a notebook where the tab will be attached. It is also
* responsible for moving/resizing the window and adding the
* necessary properties to the notebook (e.g. the
- * #GtkNotebook:group-name ).
+ * `GtkNotebook`:group-name ).
*
- * Returns: (transfer none): a #GtkNotebook that @page should be
+ * Returns: (transfer none): a `GtkNotebook` that @page should be
* added to, or %NULL.
*/
notebook_signals[CREATE_WINDOW] =
@@ -1783,9 +1883,9 @@ gtk_notebook_reorder_tab (GtkNotebook *notebook,
/**
* gtk_notebook_new:
*
- * Creates a new #GtkNotebook widget with no pages.
+ * Creates a new `GtkNotebook` widget with no pages.
- * Returns: the newly created #GtkNotebook
+ * Returns: the newly created `GtkNotebook`
*/
GtkWidget*
gtk_notebook_new (void)
@@ -3323,12 +3423,12 @@ gtk_notebook_drag_drop (GtkDropTarget *dest,
/**
* gtk_notebook_detach_tab:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: a child
*
* Removes the child from the notebook.
*
- * This function is very similar to gtk_notebook_remove_page(),
+ * This function is very similar to [method@Gtk.Notebook.remove_page],
* but additionally informs the notebook that the removal
* is happening as part of a tab DND operation, which should
* not be cancelled.
@@ -5572,9 +5672,9 @@ gtk_notebook_menu_label_unparent (GtkWidget *widget)
*/
/**
* gtk_notebook_append_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
* for the page, or %NULL to use the default label, “page N”
*
* Appends a page to @notebook.
@@ -5596,15 +5696,15 @@ gtk_notebook_append_page (GtkNotebook *notebook,
/**
* gtk_notebook_append_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
* for the page, or %NULL to use the default label, “page N”
* @menu_label: (allow-none): the widget to use as a label for the
* page-switch menu, if that is enabled. If %NULL, and @tab_label
* is a #GtkLabel or %NULL, then the menu label will be a newly
* created label with the same text as @tab_label; if @tab_label
- * is not a #GtkLabel, @menu_label must be specified if the
+ * is not a `GtkLabel`, @menu_label must be specified if the
* page-switch menu is to be used.
*
* Appends a page to @notebook, specifying the widget to use as the
@@ -5629,8 +5729,8 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook,
/**
* gtk_notebook_prepend_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
* @tab_label: (allow-none): the #GtkWidget to be used as the label
* for the page, or %NULL to use the default label, “page N”
*
@@ -5653,9 +5753,9 @@ gtk_notebook_prepend_page (GtkNotebook *notebook,
/**
* gtk_notebook_prepend_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
* for the page, or %NULL to use the default label, “page N”
* @menu_label: (allow-none): the widget to use as a label for the
* page-switch menu, if that is enabled. If %NULL, and @tab_label
@@ -5686,9 +5786,9 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook,
/**
* gtk_notebook_insert_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
* for the page, or %NULL to use the default label, “page N”
* @position: the index (starting at 0) at which to insert the page,
* or -1 to append the page after all other pages
@@ -5743,9 +5843,9 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child,
/**
* gtk_notebook_insert_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
* for the page, or %NULL to use the default label, “page N”
* @menu_label: (allow-none): the widget to use as a label for the
* page-switch menu, if that is enabled. If %NULL, and @tab_label
@@ -5783,7 +5883,7 @@ gtk_notebook_insert_page_menu (GtkNotebook *notebook,
/**
* gtk_notebook_remove_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @page_num: the index of a notebook page, starting
* from 0. If -1, the last page will be removed.
*
@@ -5814,9 +5914,10 @@ gtk_notebook_remove_page (GtkNotebook *notebook,
* gtk_notebook_next_page
* gtk_notebook_prev_page
*/
+
/**
- * gtk_notebook_get_current_page:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_current_page: (attributes org.gtk.Method.get_property=page)
+ * @notebook: a `GtkNotebook`
*
* Returns the page number of the current page.
*
@@ -5837,7 +5938,7 @@ gtk_notebook_get_current_page (GtkNotebook *notebook)
/**
* gtk_notebook_get_nth_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @page_num: the index of a page in the notebook, or -1
* to get the last page
*
@@ -5871,7 +5972,7 @@ gtk_notebook_get_nth_page (GtkNotebook *notebook,
/**
* gtk_notebook_get_n_pages:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
*
* Gets the number of pages in a notebook.
*
@@ -5887,8 +5988,8 @@ gtk_notebook_get_n_pages (GtkNotebook *notebook)
/**
* gtk_notebook_page_num:
- * @notebook: a #GtkNotebook
- * @child: a #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a `GtkWidget`
*
* Finds the index of the page which contains the given child
* widget.
@@ -5922,8 +6023,8 @@ gtk_notebook_page_num (GtkNotebook *notebook,
}
/**
- * gtk_notebook_set_current_page:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_current_page: (attributes org.gtk.Method.set_property=page)
+ * @notebook: a `GtkNotebook`
* @page_num: index of the page to switch to, starting from 0.
* If negative, the last page will be used. If greater
* than the number of pages in the notebook, nothing
@@ -5954,10 +6055,11 @@ gtk_notebook_set_current_page (GtkNotebook *notebook,
/**
* gtk_notebook_next_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
+ *
+ * Switches to the next page.
*
- * Switches to the next page. Nothing happens if the current page is
- * the last page.
+ * Nothing happens if the current page is the last page.
*/
void
gtk_notebook_next_page (GtkNotebook *notebook)
@@ -5979,10 +6081,11 @@ gtk_notebook_next_page (GtkNotebook *notebook)
/**
* gtk_notebook_prev_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
*
- * Switches to the previous page. Nothing happens if the current page
- * is the first page.
+ * Switches to the previous page.
+ *
+ * Nothing happens if the current page is the first page.
*/
void
gtk_notebook_prev_page (GtkNotebook *notebook)
@@ -6014,13 +6117,13 @@ gtk_notebook_prev_page (GtkNotebook *notebook)
* gtk_notebook_get_scrollable
*/
/**
- * gtk_notebook_set_show_border:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_show_border: (attributes org.gtk.Method.set_property=show-border)
+ * @notebook: a `GtkNotebook`
* @show_border: %TRUE if a bevel should be drawn around the notebook
*
* Sets whether a bevel will be drawn around the notebook pages.
+ *
* This only has a visual effect when the tabs are not shown.
- * See gtk_notebook_set_show_tabs().
*/
void
gtk_notebook_set_show_border (GtkNotebook *notebook,
@@ -6042,11 +6145,10 @@ gtk_notebook_set_show_border (GtkNotebook *notebook,
}
/**
- * gtk_notebook_get_show_border:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_show_border: (attributes org.gtk.Method.get_property=show-border)
+ * @notebook: a `GtkNotebook`
*
* Returns whether a bevel will be drawn around the notebook pages.
- * See gtk_notebook_set_show_border().
*
* Returns: %TRUE if the bevel is drawn
*/
@@ -6059,8 +6161,8 @@ gtk_notebook_get_show_border (GtkNotebook *notebook)
}
/**
- * gtk_notebook_set_show_tabs:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_show_tabs: (attributes org.gtk.Method.set_property=show-tabs)
+ * @notebook: a `GtkNotebook`
* @show_tabs: %TRUE if the tabs should be shown
*
* Sets whether to show the tabs for the notebook or not.
@@ -6119,11 +6221,10 @@ gtk_notebook_set_show_tabs (GtkNotebook *notebook,
}
/**
- * gtk_notebook_get_show_tabs:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_show_tabs: (attributes org.gtk.Method.get_property=show-tabs)
+ * @notebook: a `GtkNotebook`
*
* Returns whether the tabs of the notebook are shown.
- * See gtk_notebook_set_show_tabs().
*
* Returns: %TRUE if the tabs are shown
*/
@@ -6221,12 +6322,11 @@ gtk_notebook_update_tab_pos (GtkNotebook *notebook)
}
/**
- * gtk_notebook_set_tab_pos:
- * @notebook: a #GtkNotebook.
+ * gtk_notebook_set_tab_pos: (attributes org.gtk.Method.set_property=tab-pos)
+ * @notebook: a `GtkNotebook`.
* @pos: the edge to draw the tabs at
*
- * Sets the edge at which the tabs for switching pages in the
- * notebook are drawn.
+ * Sets the edge at which the tabs are drawn.
*/
void
gtk_notebook_set_tab_pos (GtkNotebook *notebook,
@@ -6246,11 +6346,10 @@ gtk_notebook_set_tab_pos (GtkNotebook *notebook,
}
/**
- * gtk_notebook_get_tab_pos:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_tab_pos: (attributes org.gtk.Method.get_property=tab-pos)
+ * @notebook: a `GtkNotebook`
*
- * Gets the edge at which the tabs for switching pages in the
- * notebook are drawn.
+ * Gets the edge at which the tabs are drawn.
*
* Returns: the edge at which the tabs are drawn
*/
@@ -6263,8 +6362,8 @@ gtk_notebook_get_tab_pos (GtkNotebook *notebook)
}
/**
- * gtk_notebook_set_scrollable:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_scrollable: (attributes org.gtk.Method.set_property=scrollable)
+ * @notebook: a `GtkNotebook`
* @scrollable: %TRUE if scroll arrows should be added
*
* Sets whether the tab label area will have arrows for
@@ -6292,11 +6391,10 @@ gtk_notebook_set_scrollable (GtkNotebook *notebook,
}
/**
- * gtk_notebook_get_scrollable:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_scrollable: (attributes or.gtk.Method.get_property=scrollable)
+ * @notebook: a `GtkNotebook`
*
* Returns whether the tab label area has arrows for scrolling.
- * See gtk_notebook_set_scrollable().
*
* Returns: %TRUE if arrows for scrolling are present
*/
@@ -6318,11 +6416,12 @@ gtk_notebook_get_scrollable (GtkNotebook *notebook)
/**
* gtk_notebook_popup_enable:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
+ *
+ * Enables the popup menu.
*
- * Enables the popup menu: if the user clicks with the right
- * mouse button on the tab labels, a menu with all the pages
- * will be popped up.
+ * If the user clicks with the right mouse button on the tab labels,
+ * a menu with all the pages will be popped up.
*/
void
gtk_notebook_popup_enable (GtkNotebook *notebook)
@@ -6353,7 +6452,7 @@ gtk_notebook_popup_enable (GtkNotebook *notebook)
/**
* gtk_notebook_popup_disable:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
*
* Disables the popup menu.
*/
@@ -6393,10 +6492,11 @@ gtk_notebook_popup_disable (GtkNotebook *notebook)
/**
* gtk_notebook_get_tab_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the page
*
* Returns the tab label widget for the page @child.
+ *
* %NULL is returned if @child is not in @notebook or
* if no tab label has specifically been set for @child.
*
@@ -6423,12 +6523,13 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook,
/**
* gtk_notebook_set_tab_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the page
* @tab_label: (allow-none): the tab label widget to use, or %NULL
* for default tab label
*
* Changes the tab label for @child.
+ *
* If %NULL is specified for @tab_label, then the page will
* have the label “page N”.
*/
@@ -6501,7 +6602,7 @@ gtk_notebook_set_tab_label (GtkNotebook *notebook,
/**
* gtk_notebook_set_tab_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the page
* @tab_text: the label text
*
@@ -6524,15 +6625,15 @@ gtk_notebook_set_tab_label_text (GtkNotebook *notebook,
/**
* gtk_notebook_get_tab_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: a widget contained in a page of @notebook
*
* Retrieves the text of the tab label for the page containing
* @child.
*
- * Returns: (nullable): the text of the tab label, or %NULL if the tab label
- * widget is not a #GtkLabel. The string is owned by the widget and must not be
- * freed.
+ * Returns: (nullable): the text of the tab label, or %NULL if
+ * the tab label idget is not a `GtkLabel`. The string is owned
+ * by the widget and must not be freed.
*/
const char *
gtk_notebook_get_tab_label_text (GtkNotebook *notebook,
@@ -6553,14 +6654,14 @@ gtk_notebook_get_tab_label_text (GtkNotebook *notebook,
/**
* gtk_notebook_get_menu_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: a widget contained in a page of @notebook
*
* Retrieves the menu label widget of the page containing @child.
*
- * Returns: (nullable) (transfer none): the menu label, or %NULL if the
- * notebook page does not have a menu label other than the default (the tab
- * label).
+ * Returns: (nullable) (transfer none): the menu label, or %NULL
+ * if the notebook page does not have a menu label other than
+ * the default (the tab label).
*/
GtkWidget*
gtk_notebook_get_menu_label (GtkNotebook *notebook,
@@ -6582,7 +6683,7 @@ gtk_notebook_get_menu_label (GtkNotebook *notebook,
/**
* gtk_notebook_set_menu_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the child widget
* @menu_label: (allow-none): the menu label, or %NULL for default
*
@@ -6627,7 +6728,7 @@ gtk_notebook_set_menu_label (GtkNotebook *notebook,
/**
* gtk_notebook_set_menu_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the child widget
* @menu_text: the label text
*
@@ -6653,16 +6754,16 @@ gtk_notebook_set_menu_label_text (GtkNotebook *notebook,
/**
* gtk_notebook_get_menu_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the child widget of a page of the notebook.
*
* Retrieves the text of the menu label for the page containing
* @child.
*
- * Returns: (nullable): the text of the tab label, or %NULL if the widget does
- * not have a menu label other than the default menu label, or the menu label
- * widget is not a #GtkLabel. The string is owned by the widget and must not be
- * freed.
+ * Returns: (nullable): the text of the tab label, or %NULL if
+ * the widget does not have a menu label other than the default
+ * menu label, or the menu label widget is not a `GtkLabel`.
+ * The string is owned by the widget and must not be freed.
*/
const char *
gtk_notebook_get_menu_label_text (GtkNotebook *notebook,
@@ -6712,14 +6813,15 @@ gtk_notebook_child_reordered (GtkNotebook *notebook,
/**
* gtk_notebook_reorder_child:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: the child to move
* @position: the new position, or -1 to move to the end
*
* Reorders the page containing @child, so that it appears in position
- * @position. If @position is greater than or equal to the number of
- * children in the list or negative, @child will be moved to the end
- * of the list.
+ * @position.
+ *
+ * If @position is greater than or equal to the number of children in
+ * the list or negative, @child will be moved to the end of the list.
*/
void
gtk_notebook_reorder_child (GtkNotebook *notebook,
@@ -6776,8 +6878,8 @@ gtk_notebook_reorder_child (GtkNotebook *notebook,
}
/**
- * gtk_notebook_set_group_name:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_group_name: (attributes org.gtk.Method.set_property=group-name)
+ * @notebook: a `GtkNotebook`
* @group_name: (allow-none): the name of the notebook group,
* or %NULL to unset it
*
@@ -6806,12 +6908,13 @@ gtk_notebook_set_group_name (GtkNotebook *notebook,
}
/**
- * gtk_notebook_get_group_name:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_group_name: (attributes org.gtk.Method.get_property=group-name)
+ * @notebook: a `GtkNotebook`
*
* Gets the current group name for @notebook.
*
- * Returns: (nullable) (transfer none): the group name, or %NULL if none is set
+ * Returns: (nullable) (transfer none): the group name,
+ * or %NULL if none is set
*/
const char *
gtk_notebook_get_group_name (GtkNotebook *notebook)
@@ -6823,8 +6926,8 @@ gtk_notebook_get_group_name (GtkNotebook *notebook)
/**
* gtk_notebook_get_tab_reorderable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
*
* Gets whether the tab can be reordered via drag and drop or not.
*
@@ -6847,8 +6950,8 @@ gtk_notebook_get_tab_reorderable (GtkNotebook *notebook,
/**
* gtk_notebook_set_tab_reorderable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
* @reorderable: whether the tab is reorderable or not
*
* Sets whether the notebook tab can be reordered
@@ -6885,8 +6988,8 @@ gtk_notebook_set_tab_reorderable (GtkNotebook *notebook,
/**
* gtk_notebook_get_tab_detachable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
*
* Returns whether the tab contents can be detached from @notebook.
*
@@ -6909,15 +7012,15 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
/**
* gtk_notebook_set_tab_detachable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
* @detachable: whether the tab is detachable or not
*
* Sets whether the tab can be detached from @notebook to another
* notebook or widget.
*
- * Note that 2 notebooks must share a common group identificator
- * (see gtk_notebook_set_group_name()) to allow automatic tabs
+ * Note that two notebooks must share a common group identificator
+ * (see [method@Gtk.Notebook.set_group_name]) to allow automatic tabs
* interchange between them.
*
* If you want a widget to interact with a notebook through DnD
@@ -6926,34 +7029,34 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
* will fill the selection with a GtkWidget** pointing to the child
* widget that corresponds to the dropped tab.
*
- * Note that you should use gtk_notebook_detach_tab() instead of
- * gtk_notebook_remove_page() if you want to remove the tab from
- * the source notebook as part of accepting a drop. Otherwise,
- * the source notebook will think that the dragged tab was
- * removed from underneath the ongoing drag operation, and
- * will initiate a drag cancel animation.
+ * Note that you should use [method@Gtk.Notebook.detach_tab] instead
+ * of [method@Gtk.Notebook.remove_page] if you want to remove the tab
+ * from the source notebook as part of accepting a drop. Otherwise,
+ * the source notebook will think that the dragged tab was removed
+ * from underneath the ongoing drag operation, and will initiate a
+ * drag cancel animation.
*
- * |[<!-- language="C" -->
- * static void
- * on_drag_data_received (GtkWidget *widget,
- * GdkDrop *drop,
- * GtkSelectionData *data,
- * guint time,
- * gpointer user_data)
- * {
- * GtkDrag *drag;
- * GtkWidget *notebook;
- * GtkWidget **child;
+ * ```c
+ * static void
+ * on_drag_data_received (GtkWidget *widget,
+ * GdkDrop *drop,
+ * GtkSelectionData *data,
+ * guint time,
+ * gpointer user_data)
+ * {
+ * GtkDrag *drag;
+ * GtkWidget *notebook;
+ * GtkWidget **child;
*
- * drag = gtk_drop_get_drag (drop);
- * notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
- * child = (void*) gtk_selection_data_get_data (data);
+ * drag = gtk_drop_get_drag (drop);
+ * notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
+ * child = (void*) gtk_selection_data_get_data (data);
*
- * // process_widget (*child);
+ * // process_widget (*child);
*
- * gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
- * }
- * ]|
+ * gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
+ * }
+ * ```
*
* If you want a notebook to accept drags from other widgets,
* you will have to set your own DnD code to do it.
@@ -6984,13 +7087,16 @@ gtk_notebook_set_tab_detachable (GtkNotebook *notebook,
/**
* gtk_notebook_get_action_widget:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @pack_type: pack type of the action widget to receive
*
- * Gets one of the action widgets. See gtk_notebook_set_action_widget().
+ * Gets one of the action widgets.
+ *
+ * See [method@Gtk.Notebook.set_action_widget].
*
- * Returns: (nullable) (transfer none): The action widget with the given
- * @pack_type or %NULL when this action widget has not been set
+ * Returns: (nullable) (transfer none): The action widget
+ * with the given @pack_type or %NULL when this action
+ * widget has not been set
*/
GtkWidget*
gtk_notebook_get_action_widget (GtkNotebook *notebook,
@@ -7003,13 +7109,15 @@ gtk_notebook_get_action_widget (GtkNotebook *notebook,
/**
* gtk_notebook_set_action_widget:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @widget: a #GtkWidget
* @pack_type: pack type of the action widget
*
- * Sets @widget as one of the action widgets. Depending on the pack type
- * the widget will be placed before or after the tabs. You can use
- * a #GtkBox if you need to pack more than one widget on the same side.
+ * Sets @widget as one of the action widgets.
+ *
+ * Depending on the pack type the widget will be placed before
+ * or after the tabs. You can use a `GtkBox` if you need to pack
+ * more than one widget on the same side.
*/
void
gtk_notebook_set_action_widget (GtkNotebook *notebook,
@@ -7040,12 +7148,12 @@ gtk_notebook_set_action_widget (GtkNotebook *notebook,
/**
* gtk_notebook_get_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
* @child: a child of @notebook
*
- * Returns the #GtkNotebookPage for @child.
+ * Returns the `GtkNotebookPage` for @child.
*
- * Returns: (transfer none): the #GtkNotebookPage for @child
+ * Returns: (transfer none): the `GtkNotebookPage` for @child
*/
GtkNotebookPage *
gtk_notebook_get_page (GtkNotebook *notebook,
@@ -7065,8 +7173,8 @@ gtk_notebook_get_page (GtkNotebook *notebook,
}
/**
- * gtk_notebook_page_get_child:
- * @page: a #GtkNotebookPage
+ * gtk_notebook_page_get_child: (attributes org.gtk.Method.get_property=child)
+ * @page: a `GtkNotebookPage`
*
* Returns the notebook child to which @page belongs.
*
@@ -7151,14 +7259,17 @@ gtk_notebook_pages_new (GtkNotebook *notebook)
}
/**
- * gtk_notebook_get_pages:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_pages: (attributes org.gtk.Method.get_property=pages)
+ * @notebook: a `GtkNotebook`
*
- * Returns a #GListModel that contains the pages of the notebook,
- * and can be used to keep an up-to-date view.
- *
+ * Returns a `GListModel` that contains the pages of the notebook.
+ *
+ * This can be used to keep an up-to-date view. The model also
+ * implements [iface@Gtk.SelectionModel] and can be used to track
+ * and modify the visible page.
+
* Returns: (transfer full) (attributes element-type=GtkNotebookPage): a
- * #GListModel for the notebook's children
+ * `GListModel` for the notebook's children
*/
GListModel *
gtk_notebook_get_pages (GtkNotebook *notebook)
diff --git a/gtk/gtknotebook.h b/gtk/gtknotebook.h
index d219f78c42..73139d6580 100644
--- a/gtk/gtknotebook.h
+++ b/gtk/gtknotebook.h
@@ -44,13 +44,6 @@ G_BEGIN_DECLS
#define GTK_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_NOTEBOOK_PAGE, GtkNotebookPage))
#define GTK_IS_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_NOTEBOOK_PAGE))
-/**
- * GtkNotebookPage:
- *
- * A page in the #GtkNotebook.
- *
- * The `GtkNotebookPage` structure only contains private data.
- */
typedef struct _GtkNotebookPage GtkNotebookPage;
/**
@@ -58,7 +51,7 @@ typedef struct _GtkNotebookPage GtkNotebookPage;
* @GTK_NOTEBOOK_TAB_FIRST: the first tab in the notebook
* @GTK_NOTEBOOK_TAB_LAST: the last tab in the notebook
*
- * The parameter used in the action signals of #GtkNotebook.
+ * The parameter used in the action signals of `GtkNotebook`.
*/
typedef enum
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
