From f5610001248a1328ca3b604da50b957ad5652a2d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 4 Aug 2020 21:17:49 -0400 Subject: [PATCH] docs: Clean up many dangling links In many cases, these were references to no longer existing api, so some rewording was necessary. --- docs/reference/gtk/actions.md | 7 ++-- docs/reference/gtk/gtk4-sections.txt | 5 +++ docs/reference/gtk/input-handling.md | 2 +- docs/reference/gtk/question_index.md | 3 -- gtk/gtkaboutdialog.c | 2 +- gtk/gtkatcontext.c | 2 +- gtk/gtkbitset.c | 6 +-- gtk/gtkbuilder.c | 15 +++---- gtk/gtkbuilderscope.h | 2 +- gtk/gtkcellarea.c | 22 +++++------ gtk/gtkcellrenderer.c | 2 +- gtk/gtkcheckbutton.c | 2 +- gtk/gtkcolumnviewcolumn.c | 2 +- gtk/gtkcombobox.c | 2 +- gtk/gtkdrawingarea.c | 13 +++---- gtk/gtkdroptargetasync.c | 11 +++--- gtk/gtkeditablelabel.c | 10 ++--- gtk/gtkentry.c | 16 +------- gtk/gtkenums.h | 19 ++++----- gtk/gtkeventcontroller.c | 2 +- gtk/gtkeventcontrollerfocus.c | 4 +- gtk/gtkexpression.c | 2 +- gtk/gtkfilechooser.c | 36 +---------------- gtk/gtkfilefilter.c | 2 +- gtk/gtkfilter.c | 2 +- gtk/gtkgesture.c | 27 +++++-------- gtk/gtkgestureclick.c | 5 --- gtk/gtklistbox.c | 5 ++- gtk/gtkliststore.c | 2 +- gtk/gtknotebook.c | 16 +++----- gtk/gtkpagesetupunixdialog.c | 2 +- gtk/gtkscrolledwindow.c | 5 +-- gtk/gtkspinbutton.c | 2 +- gtk/gtkstylecontext.c | 15 +------ gtk/gtktextiter.c | 19 ++++----- gtk/gtktextview.c | 12 +----- gtk/gtktextview.h | 4 +- gtk/gtktogglebutton.c | 2 +- gtk/gtktooltip.c | 15 +------ gtk/gtktreelistmodel.c | 4 +- gtk/gtktreemodel.c | 2 +- gtk/gtkwidget.c | 58 +++++++++++++--------------- gtk/gtkwindow.c | 53 ++++++------------------- 43 files changed, 145 insertions(+), 294 deletions(-) diff --git a/docs/reference/gtk/actions.md b/docs/reference/gtk/actions.md index c88006e6d4..d2823370b0 100644 --- a/docs/reference/gtk/actions.md +++ b/docs/reference/gtk/actions.md @@ -185,10 +185,9 @@ is to create a menu using a GMenu menu model. GMenu provides an abstract way to describe typical menus: nested groups of items where each item can have a label, and icon, and an action. -Typical uses of GMenu inside GTK are to set up an application -menu or menubar with gtk_application_set_app_menu() or -gtk_application_set_menubar(). Another, maybe more common use -is to create a popover for a menubutton, using +A typical use of GMenu inside GTK is to set up an application +menubar with gtk_application_set_menubar(). Another, maybe more +common use is to create a popover for a menubutton, using gtk_menu_button_set_menu_model(). Unlike traditional menus, those created from menu models don't diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt index 0efe0d7da7..f6d3463a62 100644 --- a/docs/reference/gtk/gtk4-sections.txt +++ b/docs/reference/gtk/gtk4-sections.txt @@ -644,6 +644,7 @@ gtk_grid_view_get_type gtkbuildable GtkBuildable GtkBuildableIface +GtkBuildableParser gtk_buildable_set_name gtk_buildable_get_name gtk_buildable_add_child @@ -666,6 +667,10 @@ GTK_BUILDABLE_GET_IFACE
gtkbuilderscope GtkBuilderScope +GtkBuilderScope +GtkBuilderClosureFlags +GtkBuilderScopeInterface +GtkBuilderCScope gtk_builder_cscope_new gtk_builder_cscope_add_callback_symbol gtk_builder_cscope_add_callback_symbols diff --git a/docs/reference/gtk/input-handling.md b/docs/reference/gtk/input-handling.md index 1404238489..35376f7cb7 100644 --- a/docs/reference/gtk/input-handling.md +++ b/docs/reference/gtk/input-handling.md @@ -66,7 +66,7 @@ the target widget for event propagation is window's current focus widget (see gtk_window_get_focus()). For pointer events, the target widget is determined by picking -the widget at the events coordinates (see gtk_window_pick()). +the widget at the events coordinates (see gtk_widget_pick()). In the first phase (the “capture” phase) the event is delivered to each widget from the top-most (the top-level #GtkWindow or grab widget) diff --git a/docs/reference/gtk/question_index.md b/docs/reference/gtk/question_index.md index 7175090fc1..6386e2f78f 100644 --- a/docs/reference/gtk/question_index.md +++ b/docs/reference/gtk/question_index.md @@ -412,9 +412,6 @@ the question you have, this list is a good place to start. text typed in by the user before or after the tagged block will appear in the default style. - To ensure that all text has the desired appearance, use - gtk_widget_override_font() to change the default font for the widget. - 25. How do I make a text view scroll to the end of the buffer automatically ? A good way to keep a text buffer scrolled to the end is to place a diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c index 7c1a1b0e81..66887e2b66 100644 --- a/gtk/gtkaboutdialog.c +++ b/gtk/gtkaboutdialog.c @@ -567,7 +567,7 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass) * GtkAboutDialog:logo: * * A logo for the about box. If it is %NULL, the default window icon - * set with gtk_window_set_default_icon() will be used. + * set with gtk_window_set_default_icon_name() will be used. */ props[PROP_LOGO] = g_param_spec_object ("logo", diff --git a/gtk/gtkatcontext.c b/gtk/gtkatcontext.c index 0f12bf9121..c18a6cff37 100644 --- a/gtk/gtkatcontext.c +++ b/gtk/gtkatcontext.c @@ -177,7 +177,7 @@ gtk_at_context_class_init (GtkATContextClass *klass) * @self: the #GtkATContext * @changed_states: flags for the changed states * @changed_properties: flags for the changed properties - * @changed_relations: + * @changed_relations: flags for the changed relations * @states: the new states * @properties: the new properties * @relations: the new relations diff --git a/gtk/gtkbitset.c b/gtk/gtkbitset.c index 1d39918639..7a390aaddd 100644 --- a/gtk/gtkbitset.c +++ b/gtk/gtkbitset.c @@ -194,9 +194,9 @@ gtk_bitset_get_maximum (const GtkBitset *self) /** * gtk_bitset_get_size: - * @self: a #GtkBitSet + * @self: a #GtkBitset * - * Gets the number of values that were added to the set. + * Gets the number of values that were added to the set. * For example, if the set is empty, 0 is returned. * * Note that this function returns a #guint64, because when all values are @@ -215,7 +215,7 @@ gtk_bitset_get_size (const GtkBitset *self) /** * gtk_bitset_get_size_in_range: - * @self: a #GtkBitSet + * @self: a #GtkBitset * @first: the first element to include * @last: the last element to include * diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index a3ee15dfde..6c5f5469f0 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -53,9 +53,6 @@ * Non-widget objects need to be reffed with g_object_ref() to keep them * beyond the lifespan of the builder. * - * The function gtk_builder_connect_signals() and variants thereof can be - * used to connect handlers to the named signals in the description. - * * # GtkBuilder UI Definitions # {#BUILDER-UI} * * GtkBuilder parses textual descriptions of user interfaces which are @@ -2717,14 +2714,12 @@ _gtk_builder_get_template_type (GtkBuilder *builder) * @object: (nullable): Object to create the closure with * @error: (allow-none): return location for an error, or %NULL * - * Creates a closure to invoke the function called @function_name. + * Creates a closure to invoke the function called @function_name, + * by using the create_closure() implementation of @builder's + * #GtkBuilderScope. * - * If a closure function was set via gtk_builder_set_closure_func(), - * will be invoked. - * Otherwise, gtk_builder_create_cclosure() will be called. - * - * If no closure could be created, %NULL will be returned and @error will - * be set. + * If no closure could be created, %NULL will be returned and @error + * will be set. * * Returns: (nullable): A new closure for invoking @function_name **/ diff --git a/gtk/gtkbuilderscope.h b/gtk/gtkbuilderscope.h index 23f44fd485..e08adaf6fc 100644 --- a/gtk/gtkbuilderscope.h +++ b/gtk/gtkbuilderscope.h @@ -38,7 +38,7 @@ G_DECLARE_INTERFACE (GtkBuilderScope, gtk_builder_scope, GTK, BUILDER_SCOPE, GOb * @GTK_BUILDER_CLOSURE_SWAPPED: The closure should be created swapped. See * g_cclosure_new_swap() for details. * - * The list of flags that can be passed to gtk_builder_scope_create_closure(). + * The list of flags that can be passed to gtk_builder_create_closure(). * New values may be added in the future for new features, so external * implementations of GtkBuilderScopeInterface should test the flags for unknown * values and raise a %@GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c index d59aa41295..e0ce9e48e6 100644 --- a/gtk/gtkcellarea.c +++ b/gtk/gtkcellarea.c @@ -101,7 +101,7 @@ * exceedingly large amount of rows. The #GtkCellLayout widget in * that case would calculate the required width of the rows in an * idle or timeout source (see g_timeout_add()) and when the widget - * is requested its actual width in #GtkWidgetClass.get_preferred_width() + * is requested its actual width in #GtkWidgetClass.measure() * it can simply consult the width accumulated so far in the * #GtkCellAreaContext object. * @@ -177,7 +177,7 @@ * synchronously. The reasoning here is that any layouting widget is * at least capable of synchronously calculating enough height to fill * the screen height (or scrolled window height) in response to a single - * call to #GtkWidgetClass.get_preferred_height_for_width(). Returning + * call to #GtkWidgetClass.measure(). Returning * a perfect height for width that is larger than the screen area is * inconsequential since after the layouting receives an allocation * from a scrolled window it simply continues to drive the scrollbar @@ -188,7 +188,7 @@ * * Once area sizes have been aquired at least for the rows in the * visible area of the layouting widget they can be rendered at - * #GtkWidgetClass.draw() time. + * #GtkWidgetClass.snapshot() time. * * A crude example of how to render all the rows at the root level * runs as follows: @@ -318,15 +318,13 @@ * * # Cell Properties * - * The #GtkCellArea introduces cell properties for #GtkCellRenderers - * in very much the same way that #GtkContainer introduces - * [child properties][child-properties] - * for #GtkWidgets. This provides some general interfaces for defining - * the relationship cell areas have with their cells. For instance in a - * #GtkCellAreaBox a cell might “expand” and receive extra space when - * the area is allocated more than its full natural request, or a cell - * might be configured to “align” with adjacent rows which were requested - * and rendered with the same #GtkCellAreaContext. + * The #GtkCellArea introduces cell properties for #GtkCellRenderers. + * This provides some general interfaces for defining the relationship + * cell areas have with their cells. For instance in a #GtkCellAreaBox + * a cell might “expand” and receive extra space when the area is allocated + * more than its full natural request, or a cell might be configured to “align” + * with adjacent rows which were requested and rendered with the same + * #GtkCellAreaContext. * * Use gtk_cell_area_class_install_cell_property() to install cell * properties for a cell area class and gtk_cell_area_class_find_cell_property() diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c index b0dcdc9caf..ed9be3e10b 100644 --- a/gtk/gtkcellrenderer.c +++ b/gtk/gtkcellrenderer.c @@ -50,7 +50,7 @@ * There are a number of rules that must be followed when writing a new * #GtkCellRenderer. First and foremost, it’s important that a certain set * of properties will always yield a cell renderer of the same size, - * barring a #GtkStyle change. The #GtkCellRenderer also has a number of + * barring a style change. The #GtkCellRenderer also has a number of * generic properties that are expected to be honored by all children. * * Beyond merely rendering a cell, cell renderers can optionally diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c index 6c5dcdc375..c6db13518f 100644 --- a/gtk/gtkcheckbutton.c +++ b/gtk/gtkcheckbutton.c @@ -44,7 +44,7 @@ * SECTION:gtkcheckbutton * @Short_description: Create widgets with a discrete toggle button * @Title: GtkCheckButton - * @See_also: #GtkCheckMenuItem, #GtkButton, #GtkToggleButton, #GtkRadioButton + * @See_also: #GtkButton, #GtkToggleButton, #GtkRadioButton * * A #GtkCheckButton places a discrete #GtkToggleButton next to a widget, * (usually a #GtkLabel). See the section on #GtkToggleButton widgets for diff --git a/gtk/gtkcolumnviewcolumn.c b/gtk/gtkcolumnviewcolumn.c index 3ee4b84123..f9d0d64246 100644 --- a/gtk/gtkcolumnviewcolumn.c +++ b/gtk/gtkcolumnviewcolumn.c @@ -360,7 +360,7 @@ gtk_column_view_column_init (GtkColumnViewColumn *self) * * Creates a new #GtkColumnViewColumn. * - * You most likely want to call gtk_column_add_column() next. + * You most likely want to call gtk_column_view_add_column() next. * * Returns: a new #GtkColumnViewColumn **/ diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c index 015fe479d6..1050dde853 100644 --- a/gtk/gtkcombobox.c +++ b/gtk/gtkcombobox.c @@ -66,7 +66,7 @@ * * To allow the user to enter values not in the model, the “has-entry” * property allows the GtkComboBox to contain a #GtkEntry. This entry - * can be accessed by calling gtk_bin_get_child() on the combo box. + * can be accessed by calling gtk_combo_box_get_child() on the combo box. * * For a simple list of textual choices, the model-view API of GtkComboBox * can be a bit overwhelming. In this case, #GtkComboBoxText offers a diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c index 65c7198d3c..80753fa27c 100644 --- a/gtk/gtkdrawingarea.c +++ b/gtk/gtkdrawingarea.c @@ -131,16 +131,13 @@ static guint signals[LAST_SIGNAL] = { 0, }; * This will cause the drawing area to call the draw function again. * * The available routines for drawing are documented on the - * [GDK Drawing Primitives][gdk3-Cairo-Interaction] page + * [GDK Drawing Primitives][gdk4-Cairo-Interaction] page * and the cairo documentation. * - * To receive mouse events on a drawing area, you will need to enable - * them with gtk_widget_add_events(). To receive keyboard events, you - * will need to set the “can-focus” property on the drawing area, and you - * should probably draw some user-visible indication that the drawing - * area is focused. Use gtk_widget_has_focus() in your expose event - * handler to decide whether to draw the focus indicator. See - * gtk_render_focus() for one way to draw focus. + * To receive mouse events on a drawing area, you will need to use + * event controllers. To receive keyboard events, you will need to set + * the “can-focus” property on the drawing area, and you should probably + * draw some user-visible indication that the drawing area is focused. * * If you need more complex control over your widget, you should consider * creating your own #GtkWidget subclass. diff --git a/gtk/gtkdroptargetasync.c b/gtk/gtkdroptargetasync.c index 3a8c7b36e3..c14d307096 100644 --- a/gtk/gtkdroptargetasync.c +++ b/gtk/gtkdroptargetasync.c @@ -410,11 +410,12 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) * @drop: the #GdkDrop * * The ::accept signal is emitted on the drop site when a drop operation - * is about to begin. + * is about to begin. + * * If the drop is not accepted, %FALSE will be returned and the drop target * will ignore the drop. If %TRUE is returned, the drop is accepted for now - * but may be rejected later via a call to gtk_drop_target_reject() or - * ultimately by returning %FALSE from GtkDropTarget::drop + * but may be rejected later via a call to gtk_drop_target_async_reject() or + * ultimately by returning %FALSE from #GtkDropTargetAsync::drop. * * The default handler for this signal decides whether to accept the drop * based on the formats provided by the @drop. @@ -422,7 +423,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) * If the decision whether the drop will be accepted or rejected needs * further processing, such as inspecting the data, this function should * return %TRUE and proceed as is @drop was accepted and if it decides to - * reject the drop later, it should call gtk_drop_target_reject_drop(). + * reject the drop later, it should call gtk_drop_target_async_reject_drop(). * * Returns: %TRUE if @drop is accepted */ @@ -514,7 +515,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) * Otherwise, the handler returns %TRUE. In this case, this handler will * accept the drop. The handler must ensure that gdk_drop_finish() is * called to let the source know that the drop is done. The call to - * gtk_drag_finish() must only be done when all data has been received. + * gdk_drop_finish() must only be done when all data has been received. * * To receive the data, use one of the read functions provides by #GdkDrop * such as gdk_drop_read_async() or gdk_drop_read_value_async(). diff --git a/gtk/gtkeditablelabel.c b/gtk/gtkeditablelabel.c index 52ca9f3e82..959d0428d8 100644 --- a/gtk/gtkeditablelabel.c +++ b/gtk/gtkeditablelabel.c @@ -143,7 +143,7 @@ text_changed (GtkEditableLabel *self) /* Sync the entry text to the label, unless we are editing. * * This is necessary to catch apis like gtk_editable_insert_text(), - * which don't go through the ::text property. + * which don't go through the text property. */ if (!gtk_editable_label_get_editing (self)) { @@ -384,7 +384,7 @@ gtk_editable_label_class_init (GtkEditableLabelClass *class) * The default bindings for this action are clicking * on the widget and the Enter key. * - * This action is disabled when #GtkEditable:editing + * This action is disabled when #GtkEditableLabel:editing * is %FALSE. */ gtk_widget_class_install_action (widget_class, "editing.start", NULL, start_editing); @@ -400,7 +400,7 @@ gtk_editable_label_class_init (GtkEditableLabelClass *class) * The default binding for this action is the Escape * key. * - * This action is disabled when #GtkEditable:editing + * This action is disabled when #GtkEditableLabel:editing * is %FALSE. */ gtk_widget_class_install_action (widget_class, "editing.stop", "b", stop_editing); @@ -484,9 +484,9 @@ gtk_editable_label_start_editing (GtkEditableLabel *self) * @commit: whether to set the edited text on the label * * Switches the label out of “editing mode”. If @commit is %TRUE, - * the resulting text is kept as the #GtkEditableLabel:text property + * the resulting text is kept as the #GtkEditable:text property * value, otherwise the resulting text is discarded and the label - * will keep its previous #GtkEditableLabel:text property value. + * will keep its previous #GtkEditable:text property value. */ void gtk_editable_label_stop_editing (GtkEditableLabel *self, diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c index f4acb4c17a..ee4de399d3 100644 --- a/gtk/gtkentry.c +++ b/gtk/gtkentry.c @@ -2834,19 +2834,8 @@ gtk_entry_get_icon_at_pos (GtkEntry *entry, * @provider: a #GdkContentProvider * @actions: a bitmask of the allowed drag actions * - * Sets up the icon at the given position so that GTK+ will start a drag + * Sets up the icon at the given position so that GTK will start a drag * operation when the user clicks and drags the icon. - * - * To handle the drag operation, you need to connect to the usual - * #GtkWidget::drag-data-get (or possibly #GtkWidget::drag-data-delete) - * signal, and use gtk_entry_get_current_icon_drag_source() in - * your signal handler to find out if the drag was started from - * an icon. - * - * By default, GTK+ uses the icon as the drag icon. You can use the - * #GtkWidget::drag-begin signal to set a different icon. Note that you - * have to use g_signal_connect_after() to ensure that your signal handler - * gets executed after the default handler. */ void gtk_entry_set_icon_drag_source (GtkEntry *entry, @@ -2874,9 +2863,6 @@ gtk_entry_set_icon_drag_source (GtkEntry *entry, * Returns the index of the icon which is the source of the current * DND operation, or -1. * - * This function is meant to be used in a #GtkWidget::drag-data-get - * callback. - * * Returns: index of the icon which is the source of the current * DND operation, or -1. */ diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h index d8dbe725b0..d39b867881 100644 --- a/gtk/gtkenums.h +++ b/gtk/gtkenums.h @@ -58,9 +58,9 @@ G_BEGIN_DECLS * dimension. * * Alignment only matters if the widget receives a “too large” allocation, - * for example if you packed the widget with the #GtkWidget:expand - * flag inside a #GtkBox, then the widget might get extra space. If - * you have for example a 16x16 icon inside a 32x32 space, the icon + * for example if you packed the widget with the #GtkWidget:hexpand + * property inside a #GtkBox, then the widget might get extra space. + * If you have for example a 16x16 icon inside a 32x32 space, the icon * could be scaled and stretched, it could be centered, or it could be * positioned to one side of the space. * @@ -234,8 +234,7 @@ typedef enum * @GTK_JUSTIFY_CENTER: The text is placed in the center of the label. * @GTK_JUSTIFY_FILL: The text is placed is distributed across the label. * - * Used for justifying the text inside a #GtkLabel widget. (See also - * #GtkAlignment). + * Used for justifying the text inside a #GtkLabel widget. */ typedef enum { @@ -379,9 +378,8 @@ typedef enum * @GTK_POS_TOP: The feature is at the top edge. * @GTK_POS_BOTTOM: The feature is at the bottom edge. * - * Describes which edge of a widget a certain feature is positioned at, e.g. the - * tabs of a #GtkNotebook, the handle of a #GtkHandleBox or the label of a - * #GtkScale. + * Describes which edge of a widget a certain feature is positioned at, e.g. + * the tabs of a #GtkNotebook, or the label of a #GtkScale. */ typedef enum { @@ -897,10 +895,7 @@ typedef enum /** * GtkPropagationPhase: - * @GTK_PHASE_NONE: Events are not delivered automatically. Those can be - * manually fed through gtk_event_controller_handle_event(). This should - * only be used when full control about when, or whether the controller - * handles the event is needed. + * @GTK_PHASE_NONE: Events are not delivered. * @GTK_PHASE_CAPTURE: Events are delivered in the capture phase. The * capture phase happens before the bubble phase, runs from the toplevel down * to the event widget. This option should only be used on containers that diff --git a/gtk/gtkeventcontroller.c b/gtk/gtkeventcontroller.c index 432990ed91..68670a8e14 100644 --- a/gtk/gtkeventcontroller.c +++ b/gtk/gtkeventcontroller.c @@ -316,7 +316,7 @@ gtk_event_controller_filter_crossing (GtkEventController *controller, return FALSE; } -/** +/* * gtk_event_controller_handle_event: * @controller: a #GtkEventController * @event: a #GdkEvent diff --git a/gtk/gtkeventcontrollerfocus.c b/gtk/gtkeventcontrollerfocus.c index 46c8faba91..a59f9f6f5e 100644 --- a/gtk/gtkeventcontrollerfocus.c +++ b/gtk/gtkeventcontrollerfocus.c @@ -190,8 +190,8 @@ gtk_event_controller_focus_class_init (GtkEventControllerFocusClass *klass) * #GtkEventControllerFocus:contains-focus. * * When handling focus events, this property is updated - * before #GtkEventControllerKey::focus-in or - * #GtkEventControllerKey::focus-out are emitted. + * before #GtkEventControllerFocus::enter or + * #GtkEventControllerFocus::leave are emitted. */ props[PROP_IS_FOCUS] = g_param_spec_boolean ("is-focus", diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c index fada1d1d03..81e1207b40 100644 --- a/gtk/gtkexpression.c +++ b/gtk/gtkexpression.c @@ -1652,7 +1652,7 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression, * @user_destroy: (nullable): destroy notify for @user_data * * This function is a variant of gtk_closure_expression_new() that - * creates a #GClosure by calling gtk_cclosure_new() with the given + * creates a #GClosure by calling g_cclosure_new() with the given * @callback_func, @user_data and @user_destroy. * * Returns: a new #GtkExpression diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index da188eb4f7..bd31cf90ae 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -119,7 +119,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface) * GtkFileChooser:shortcut-folders: * * A #GListModel containing the shortcut folders that have been - * added with gtk_file_chooser_add_shortcut(). + * added with gtk_file_chooser_add_shortcut_folder(). * * The returned object should not be modified. It may * or may not be updated for later changes. @@ -328,12 +328,6 @@ gtk_file_chooser_get_current_name (GtkFileChooser *chooser) return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_name (chooser); } -/** - * gtk_file_chooser_select_all: - * @chooser: a #GtkFileChooser - * - * Selects all the files in the current folder of a file chooser. - **/ void gtk_file_chooser_select_all (GtkFileChooser *chooser) { @@ -342,12 +336,6 @@ gtk_file_chooser_select_all (GtkFileChooser *chooser) GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser); } -/** - * gtk_file_chooser_unselect_all: - * @chooser: a #GtkFileChooser - * - * Unselects all the files in the current folder of a file chooser. - **/ void gtk_file_chooser_unselect_all (GtkFileChooser *chooser) { @@ -396,16 +384,6 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser) return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser); } -/** - * gtk_file_chooser_select_file: - * @chooser: a #GtkFileChooser - * @file: the file to select - * @error: (allow-none): location to store error, or %NULL - * - * Selects the file referred to by @file. - * - * Returns: Not useful. - **/ gboolean gtk_file_chooser_select_file (GtkFileChooser *chooser, GFile *file, @@ -418,14 +396,6 @@ gtk_file_chooser_select_file (GtkFileChooser *chooser, return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error); } -/** - * gtk_file_chooser_unselect_file: - * @chooser: a #GtkFileChooser - * @file: a #GFile - * - * Unselects the file referred to by @file. If the file is not in the current - * directory, does not exist, or is otherwise not currently selected, does nothing. - **/ void gtk_file_chooser_unselect_file (GtkFileChooser *chooser, GFile *file) @@ -467,9 +437,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser) * will also appear in the dialog’s file name entry. * * If the file name isn’t in the current folder of @chooser, then the current - * folder of @chooser will be changed to the folder containing @filename. This - * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by - * gtk_file_chooser_select_filename(). + * folder of @chooser will be changed to the folder containing @filename. * * Note that the file must exist, or nothing will be done except * for the directory change. diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c index 9cd3bde6ad..d2ef36c7aa 100644 --- a/gtk/gtkfilefilter.c +++ b/gtk/gtkfilefilter.c @@ -611,7 +611,7 @@ gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter) * @filter: a #GtkFileFilter * * Gets the attributes that need to be filled in for the #GFileInfo - * passed to gtk_file_filter_filter() + * passed to this filter. * * This function will not typically be used by applications; * it is intended principally for use in the implementation diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c index 096b7aeb06..2d76f8ff1c 100644 --- a/gtk/gtkfilter.c +++ b/gtk/gtkfilter.c @@ -28,7 +28,7 @@ * SECTION:gtkfilter * @Title: GtkFilter * @Short_description: Filtering items - * @See_also: #GtkFilerListModel + * @See_also: #GtkFilterListModel * * A #GtkFilter object describes the filtering to be performed by a * #GtkFilterListModel. diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c index ce40044901..1a791d3339 100644 --- a/gtk/gtkgesture.c +++ b/gtk/gtkgesture.c @@ -34,10 +34,9 @@ * or more than that number of sequences, it won't check wether the gesture * is recognized. * - * As soon as the gesture has the expected number of touches, the gesture will - * run the #GtkGesture::check signal regularly on input events until the gesture - * is recognized, the criteria to consider a gesture as "recognized" is left to - * #GtkGesture subclasses. + * As soon as the gesture has the expected number of touches, it will check + * regularly if it is recognized, the criteria to consider a gesture as + * "recognized" is left to #GtkGesture subclasses. * * A recognized gesture will then emit the following signals: * - #GtkGesture::begin when the gesture is recognized. @@ -46,18 +45,13 @@ * * ## Event propagation * - * In order to receive events, a gesture needs to either set a propagation phase - * through gtk_event_controller_set_propagation_phase(), or feed those manually - * through gtk_event_controller_handle_event(). + * In order to receive events, a gesture needs to set a propagation phase + * through gtk_event_controller_set_propagation_phase(). * * In the capture phase, events are propagated from the toplevel down to the * target widget, and gestures that are attached to containers above the widget * get a chance to interact with the event before it reaches the target. * - * After the capture phase, GTK+ emits the traditional #GtkWidget::event signal. - * Gestures with the %GTK_PHASE_TARGET phase are fed events from the default - * #GtkWidget::event handlers. - * * In the bubble phase, events are propagated up from the target widget to the * toplevel, and gestures that are attached to containers above the widget get * a chance to interact with events that have not been handled yet. @@ -772,8 +766,7 @@ gtk_gesture_class_init (GtkGestureClass *klass) * @sequence: the #GdkEventSequence that made the gesture to be recognized * * This signal is emitted when the gesture is recognized. This means the - * number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture::check - * handler(s) returned #TRUE. + * number of touch sequences matches #GtkGesture:n-points. * * Note: These conditions may also happen when an extra touch (eg. a third touch * on a 2-touches gesture) is lifted, in that situation @sequence won't pertain @@ -792,9 +785,8 @@ gtk_gesture_class_init (GtkGestureClass *klass) * @sequence: the #GdkEventSequence that made gesture recognition to finish * * This signal is emitted when @gesture either stopped recognizing the event - * sequences as something to be handled (the #GtkGesture::check handler returned - * %FALSE), or the number of touch sequences became higher or lower than - * #GtkGesture:n-points. + * sequences as something to be handled, or the number of touch sequences became + * higher or lower than #GtkGesture:n-points. * * Note: @sequence might not pertain to the group of sequences that were * previously triggering recognition on @gesture (ie. a just pressed touch @@ -1383,8 +1375,7 @@ gtk_gesture_is_active (GtkGesture *gesture) * * Returns %TRUE if the gesture is currently recognized. * A gesture is recognized if there are as many interacting - * touch sequences as required by @gesture, and #GtkGesture::check - * returned %TRUE for the sequences being currently interpreted. + * touch sequences as required by @gesture. * * Returns: %TRUE if gesture is recognized **/ diff --git a/gtk/gtkgestureclick.c b/gtk/gtkgestureclick.c index 27f6e1367a..3194fec59c 100644 --- a/gtk/gtkgestureclick.c +++ b/gtk/gtkgestureclick.c @@ -27,11 +27,6 @@ * the #GtkGestureClick::pressed signal. Whenever time or distance * between clicks exceed the GTK+ defaults, #GtkGestureClick::stopped * is emitted, and the click counter is reset. - * - * Callers may also restrict the area that is considered valid for a >1 - * touch/button press through gtk_gesture_click_set_area(), so any - * click happening outside that area is considered to be a first click - * of its own. */ #include "config.h" diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c index 9283312722..fd0a86e4d2 100644 --- a/gtk/gtklistbox.c +++ b/gtk/gtklistbox.c @@ -2690,8 +2690,9 @@ gtk_list_box_drag_unhighlight_row (GtkListBox *box) * @row: a #GtkListBoxRow * * This is a helper function for implementing DnD onto a #GtkListBox. - * The passed in @row will be highlighted via gtk_drag_highlight(), - * and any previously highlighted row will be unhighlighted. + * The passed in @row will be highlighted by setting the + * #GTK_STATE_FLAG_DROP_ACTIVE state and any previously highlighted + * row will be unhighlighted. * * The row will also be unhighlighted when the widget gets * a drag leave event. diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index e27feedc52..fa5fdc725a 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -40,7 +40,7 @@ * can use all of the methods available there. It also implements the * #GtkTreeSortable interface so it can be sorted by the view. * Finally, it also implements the tree - * [drag and drop][gtk3-GtkTreeView-drag-and-drop] + * [drag and drop][gtk4-GtkTreeView-drag-and-drop] * interfaces. * * The #GtkListStore can accept most GObject types as a column type, though diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c index ddcb9d64b9..95108c1dd0 100644 --- a/gtk/gtknotebook.c +++ b/gtk/gtknotebook.c @@ -63,10 +63,9 @@ * SECTION:gtknotebook * @Short_description: A tabbed notebook container * @Title: GtkNotebook - * @See_also: #GtkContainer * - * The #GtkNotebook widget is a #GtkContainer whose children are pages that - * can be switched between using tab labels along one edge. + * The #GtkNotebook widget is a layout container whose children are + * pages that can be switched between using tab labels along one edge. * * There are many configuration options for GtkNotebook. Among other * things, you can choose on which edge the tabs appear @@ -3304,7 +3303,7 @@ gtk_notebook_drag_drop (GtkDropTarget *dest, * * Removes the child from the notebook. * - * This function is very similar to gtk_container_remove(), + * This function is very similar to 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. @@ -3375,7 +3374,7 @@ do_detach_tab (GtkNotebook *from, gtk_notebook_set_current_page (to, page_num); } -/* Private GtkContainer Methods : +/* Private methods: * * gtk_notebook_remove * gtk_notebook_focus @@ -6887,8 +6886,8 @@ 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_container_remove() if you want to remove the tab from + * 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 @@ -6971,9 +6970,6 @@ gtk_notebook_get_action_widget (GtkNotebook *notebook, * 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. - * - * Note that action widgets are “internal” children of the notebook and thus - * not included in the list returned from gtk_container_foreach(). */ void gtk_notebook_set_action_widget (GtkNotebook *notebook, diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c index a6afe27679..6cce41b50f 100644 --- a/gtk/gtkpagesetupunixdialog.c +++ b/gtk/gtkpagesetupunixdialog.c @@ -50,7 +50,7 @@ * which don’t provide a native page setup dialog, like Unix. It can * be used very much like any other GTK dialog, at the cost of * the portability offered by the - * [high-level printing API][gtk3-High-level-Printing-API] + * [high-level printing API][gtk4-High-level-Printing-API] */ typedef struct _GtkPageSetupUnixDialogClass GtkPageSetupUnixDialogClass; diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c index 7af5ce0563..13a5803ca6 100644 --- a/gtk/gtkscrolledwindow.c +++ b/gtk/gtkscrolledwindow.c @@ -2559,9 +2559,8 @@ gtk_scrolled_window_get_kinetic_scrolling (GtkScrolledWindow *scrolled_window) * then later replayed if it is meant to go to the child widget. * * This should be enabled if any child widgets perform non-reversible - * actions on button press events. If they don't, and additionally handle - * #GtkWidget::grab-broken-event, it might be better to set @capture_button_press - * to %FALSE. + * actions on button press events. If they don't, it might be better to + * set @capture_button_press to %FALSE. * * This setting only has an effect if kinetic scrolling is enabled. */ diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c index 6c2cbc4f16..01466dda23 100644 --- a/gtk/gtkspinbutton.c +++ b/gtk/gtkspinbutton.c @@ -88,7 +88,7 @@ * Note that GtkSpinButton will by default make its entry large enough to * accomodate the lower and upper bounds of the adjustment. If this is * not desired, the automatic sizing can be turned off by explicitly - * setting #GtkSpinButton::width-chars to a value != -1. + * setting #GtkEditable::width-chars to a value != -1. * * ## Using a GtkSpinButton to get an integer * diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 36fa633f5a..8563ed4625 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -653,9 +653,8 @@ gtk_style_context_restore (GtkStyleContext *context) * @context: a #GtkStyleContext * @class_name: class name to use in styling * - * Adds a style class to @context, so posterior calls to - * gtk_style_context_get() or any of the gtk_render_*() - * functions will make use of this new class for styling. + * Adds a style class to @context, so later uses of the + * style context will make use of this new class for styling. * * In the CSS file format, a #GtkEntry defining a “search” * class, would be matched by: @@ -866,9 +865,6 @@ gtk_style_context_lookup_color (GtkStyleContext *context, * @color: (out): return value for the foreground color * * Gets the foreground color for a given state. - * - * See gtk_style_context_get_property() and - * #GTK_STYLE_PROPERTY_COLOR for details. **/ void gtk_style_context_get_color (GtkStyleContext *context, @@ -886,9 +882,6 @@ gtk_style_context_get_color (GtkStyleContext *context, * @border: (out): return value for the border settings * * Gets the border for a given state as a #GtkBorder. - * - * See gtk_style_context_get_property() and - * #GTK_STYLE_PROPERTY_BORDER_WIDTH for details. **/ void gtk_style_context_get_border (GtkStyleContext *context, @@ -913,8 +906,6 @@ gtk_style_context_get_border (GtkStyleContext *context, * @padding: (out): return value for the padding settings * * Gets the padding for a given state as a #GtkBorder. - * See gtk_style_context_get() and #GTK_STYLE_PROPERTY_PADDING - * for details. **/ void gtk_style_context_get_padding (GtkStyleContext *context, @@ -939,8 +930,6 @@ gtk_style_context_get_padding (GtkStyleContext *context, * @margin: (out): return value for the margin settings * * Gets the margin for a given state as a #GtkBorder. - * See gtk_style_property_get() and #GTK_STYLE_PROPERTY_MARGIN - * for details. **/ void gtk_style_context_get_margin (GtkStyleContext *context, diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c index 6fdf42d138..abb316fd9c 100644 --- a/gtk/gtktextiter.c +++ b/gtk/gtktextiter.c @@ -1382,10 +1382,11 @@ gtk_text_iter_get_tags (const GtkTextIter *iter) * @default_setting: %TRUE if text is editable by default * * Returns whether the character at @iter is within an editable region - * of text. Non-editable text is “locked” and can’t be changed by the - * user via #GtkTextView. This function is simply a convenience - * wrapper around gtk_text_iter_get_attributes(). If no tags applied - * to this text affect editability, @default_setting will be returned. + * of text. + * + * Non-editable text is “locked” and can’t be changed by the + * user via #GtkTextView. If no tags applied to this text affect + * editability, @default_setting will be returned. * * You don’t want to use this function to decide whether text can be * inserted at @iter, because for insertion you don’t want to know @@ -1393,7 +1394,7 @@ gtk_text_iter_get_tags (const GtkTextIter *iter) * know whether a new character inserted at @iter would be inside an * editable range. Use gtk_text_iter_can_insert() to handle this * case. - * + * * Returns: whether @iter is inside an editable range **/ gboolean @@ -1488,10 +1489,10 @@ gtk_text_iter_get_attributes (const GtkTextIter *iter, * gtk_text_iter_get_language: * @iter: an iterator * - * A convenience wrapper around gtk_text_iter_get_attributes(), - * which returns the language in effect at @iter. If no tags affecting - * language apply to @iter, the return value is identical to that of - * gtk_get_default_language(). + * Returns the language in effect at @iter. + * + * If no tags affecting language apply to @iter, the return + * value is identical to that of gtk_get_default_language(). * * Returns: (transfer full): language in effect at @iter **/ diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c index 5aef271df6..7a53f2d029 100644 --- a/gtk/gtktextview.c +++ b/gtk/gtktextview.c @@ -889,8 +889,6 @@ gtk_text_view_class_init (GtkTextViewClass *klass) * Note that this property is confusingly named. In CSS terms, * the value set here is padding, and it is applied in addition * to the padding from the theme. - * - * Don't confuse this property with #GtkWidget:margin-left. */ g_object_class_install_property (gobject_class, PROP_LEFT_MARGIN, @@ -909,8 +907,6 @@ gtk_text_view_class_init (GtkTextViewClass *klass) * Note that this property is confusingly named. In CSS terms, * the value set here is padding, and it is applied in addition * to the padding from the theme. - * - * Don't confuse this property with #GtkWidget:margin-right. */ g_object_class_install_property (gobject_class, PROP_RIGHT_MARGIN, @@ -9023,10 +9019,7 @@ text_window_get_height (GtkTextWindow *win) * @window_y: (out) (allow-none): window y coordinate return location or %NULL * * Converts coordinate (@buffer_x, @buffer_y) to coordinates for the window - * @win, and stores the result in (@window_x, @window_y). - * - * Note that you can’t convert coordinates for a nonexisting window (see - * gtk_text_view_set_border_window_size()). + * @win, and stores the result in (@window_x, @window_y). **/ void gtk_text_view_buffer_to_window_coords (GtkTextView *text_view, @@ -9091,9 +9084,6 @@ gtk_text_view_buffer_to_window_coords (GtkTextView *text_view, * * Converts coordinates on the window identified by @win to buffer * coordinates, storing the result in (@buffer_x,@buffer_y). - * - * Note that you can’t convert coordinates for a nonexisting window (see - * gtk_text_view_set_border_window_size()). **/ void gtk_text_view_window_to_buffer_coords (GtkTextView *text_view, diff --git a/gtk/gtktextview.h b/gtk/gtktextview.h index 1d929f040b..1c18d087b5 100644 --- a/gtk/gtktextview.h +++ b/gtk/gtktextview.h @@ -142,9 +142,7 @@ struct _GtkTextView * view is drawing its own text. Applications can override this vfunc * in a subclass to draw customized content underneath or above the * text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT - * the drawing is done in the buffer coordinate space, but the older (deprecated) - * layers %GTK_TEXT_VIEW_LAYER_BELOW and %GTK_TEXT_VIEW_LAYER_ABOVE work in viewport - * coordinates, which makes them unnecessarily hard to use. + * layers the drawing is done in the buffer coordinate space. * @extend_selection: The class handler for the #GtkTextView::extend-selection signal. * @insert_emoji: The class handler for the #GtkTextView::insert-emoji signal. */ diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c index 66c65f9a6e..bb6a3e8adf 100644 --- a/gtk/gtktogglebutton.c +++ b/gtk/gtktogglebutton.c @@ -40,7 +40,7 @@ * SECTION:gtktogglebutton * @Short_description: Create buttons which retain their state * @Title: GtkToggleButton - * @See_also: #GtkButton, #GtkCheckButton, #GtkCheckMenuItem + * @See_also: #GtkButton, #GtkCheckButton * * A #GtkToggleButton is a #GtkButton which will remain “pressed-in” when * clicked. Clicking again will cause the toggle button to return to its diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c index 284e96d912..e3011b4d6a 100644 --- a/gtk/gtktooltip.c +++ b/gtk/gtktooltip.c @@ -62,19 +62,6 @@ * * Return %TRUE from your query-tooltip handler. This causes the tooltip to be * show. If you return %FALSE, it will not be shown. - * - * In the probably rare case where you want to have even more control over the - * tooltip that is about to be shown, you can set your own #GtkWindow which - * will be used as tooltip window. This works as follows: - * - * - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before. - * Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as - * tooltip window. - * - * - In the #GtkWidget::query-tooltip callback you can access your window using - * gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of - * the return value are exactly as before, return %TRUE to show the window, - * %FALSE to not show it. */ @@ -357,7 +344,7 @@ gtk_tooltip_set_tip_area (GtkTooltip *tooltip, } } -/** +/* * gtk_tooltip_trigger_tooltip_query: * @display: a #GdkDisplay * diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c index 82b6bf5056..3857ad9ea6 100644 --- a/gtk/gtktreelistmodel.c +++ b/gtk/gtktreelistmodel.c @@ -819,7 +819,7 @@ gtk_tree_list_model_get_passthrough (GtkTreeListModel *self) * * If set to %TRUE, the model will recursively expand all rows that * get added to the model. This can be either rows added by changes - * to the underlying models or via gtk_tree_list_model_set_expanded(). + * to the underlying models or via gtk_tree_list_row_set_expanded(). **/ void gtk_tree_list_model_set_autoexpand (GtkTreeListModel *self, @@ -841,7 +841,7 @@ gtk_tree_list_model_set_autoexpand (GtkTreeListModel *self, * * Gets whether the model is set to automatically expand new rows * that get added. This can be either rows added by changes to the - * underlying models or via gtk_tree_list_model_set_expanded(). + * underlying models or via gtk_tree_list_row_set_expanded(). * * Returns: %TRUE if the model is set to autoexpand **/ diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index 23495b44f3..28e7a73716 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -32,7 +32,7 @@ * @Title: GtkTreeModel * @Short_description: The tree interface used by GtkTreeView * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore, - * [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop] + * [GtkTreeView drag-and-drop][gtk4-GtkTreeView-drag-and-drop] * #GtkTreeSortable * * The #GtkTreeModel interface defines a generic tree interface for diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index b76e46bb80..8f92c09a88 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -118,8 +118,9 @@ * itself or its child widgets, the #GtkWidgetClass.get_request_mode() * virtual function must be implemented as well and return the widget's * preferred request mode. The default implementation of this virtual function - * returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will only ever - * get -1 passed as the for_size value to its #GtkWidgetClass.measure() implementation. + * returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will + * only ever get -1 passed as the for_size value to its #GtkWidgetClass.measure() + * implementation. * * The geometry management system will query a widget hierarchy in * only one orientation at a time. When widgets are initially queried @@ -129,18 +130,17 @@ * For example, when queried in the normal * %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: * First, the default minimum and natural width for each widget - * in the interface will be computed using gtk_widget_measure() with an orientation - * of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1. + * in the interface will be computed using gtk_widget_measure() with an + * orientation of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1. * Because the preferred widths for each widget depend on the preferred * widths of their children, this information propagates up the hierarchy, * and finally a minimum and natural width is determined for the entire * toplevel. Next, the toplevel will use the minimum width to query for the * minimum height contextual to that width using gtk_widget_measure() with an * orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed - * width. This will also be a highly recursive operation. - * The minimum height for the minimum width is normally - * used to set the minimum size constraint on the toplevel - * (unless gtk_window_set_geometry_hints() is explicitly used instead). + * width. This will also be a highly recursive operation. The minimum height + * for the minimum width is normally used to set the minimum size constraint + * on the toplevel. * * After the toplevel window has initially requested its size in both * dimensions it can go on to allocate itself a reasonable size (or a size @@ -5285,15 +5285,8 @@ gtk_widget_update_state_flags (GtkWidget *widget, * values in the current widget state (insensitive, prelighted, etc.). * * This function accepts the values %GTK_STATE_FLAG_DIR_LTR and - * %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's - * direction, use gtk_widget_set_direction(). - * - * It is worth mentioning that any other state than %GTK_STATE_FLAG_INSENSITIVE, - * will be propagated down to all non-internal children if @widget is a - * #GtkContainer, while %GTK_STATE_FLAG_INSENSITIVE itself will be propagated - * down to all #GtkContainer children by different means than turning on the - * state flag down the hierarchy, both gtk_widget_get_state_flags() and - * gtk_widget_is_sensitive() will make use of these. + * %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set + * the widget's direction, use gtk_widget_set_direction(). **/ void gtk_widget_set_state_flags (GtkWidget *widget, @@ -6499,11 +6492,11 @@ gtk_widget_get_display (GtkWidget *widget) * gtk_widget_child_focus() is called by widgets as the user moves * around the window using keyboard shortcuts. @direction indicates * what kind of motion is taking place (up, down, left, right, tab - * forward, tab backward). gtk_widget_child_focus() emits the - * #GtkWidget::focus signal; widgets override the default handler - * for this signal in order to implement appropriate focus behavior. + * forward, tab backward). gtk_widget_child_focus() calls the + * #GtkWidgetClass.focus() vfunc; widgets override this vfunc + * in order to implement appropriate focus behavior. * - * The default ::focus handler for a widget should return %TRUE if + * The default focus() vfunc for a widget should return %TRUE if * moving in @direction left the focus on a focusable location inside * that widget, and %FALSE if moving in @direction moved the focus * outside the widget. If returning %TRUE, widgets normally @@ -8992,9 +8985,8 @@ gtk_widget_remove_mnemonic_label (GtkWidget *widget, * gtk_widget_trigger_tooltip_query: * @widget: a #GtkWidget * - * Triggers a tooltip query on the display where the toplevel of @widget - * is located. See gtk_tooltip_trigger_tooltip_query() for more - * information. + * Triggers a tooltip query on the display where the toplevel + * of @widget is located. */ void gtk_widget_trigger_tooltip_query (GtkWidget *widget) @@ -9214,17 +9206,19 @@ gtk_widget_get_has_tooltip (GtkWidget *widget) * * Retrieves the widget’s allocation. * - * Note, when implementing a #GtkContainer: a widget’s allocation will - * be its “adjusted” allocation, that is, the widget’s parent - * container typically calls gtk_widget_size_allocate() with an - * allocation, and that allocation is then adjusted (to handle margin + * Note, when implementing a layout container: a widget’s allocation + * will be its “adjusted” allocation, that is, the widget’s parent + * typically calls gtk_widget_size_allocate() with an allocation, + * and that allocation is then adjusted (to handle margin * and alignment for example) before assignment to the widget. * gtk_widget_get_allocation() returns the adjusted allocation that * was actually assigned to the widget. The adjusted allocation is * guaranteed to be completely contained within the - * gtk_widget_size_allocate() allocation, however. So a #GtkContainer - * is guaranteed that its children stay inside the assigned bounds, - * but not that they have exactly the bounds the container assigned. + * gtk_widget_size_allocate() allocation, however. + * + * So a layout container is guaranteed that its children stay inside + * the assigned bounds, but not that they have exactly the bounds the + * container assigned. */ void gtk_widget_get_allocation (GtkWidget *widget, @@ -9588,7 +9582,7 @@ gtk_widget_get_allocated_height (GtkWidget *widget) * Returns the baseline that has currently been allocated to @widget. * This function is intended to be used when implementing handlers * for the #GtkWidgetClass.snapshot() function, and when allocating child - * widgets in #GtkWidget::size_allocate. + * widgets in #GtkWidgetClass.size_allocate(). * * Returns: the baseline of the @widget, or -1 if none **/ diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c index 984e766be0..066b1dd873 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -106,24 +106,6 @@ * * # GtkWindow as GtkBuildable * - * The GtkWindow implementation of the #GtkBuildable interface supports a - * custom element, which supports any number of - * elements representing the #GtkAccelGroup objects you want to add to - * your window (synonymous with gtk_window_add_accel_group(). - * - * An example of a UI definition fragment with accel groups: - * |[ - * - * - * - * - * - * - * ... - * - * - * ]| - * * The GtkWindow implementation of the #GtkBuildable interface supports * setting a child as the titlebar by specifying “titlebar” as the “type” * attribute of a element. @@ -2122,8 +2104,9 @@ gtk_window_set_default_widget (GtkWindow *window, * gtk_window_get_default_widget: * @window: a #GtkWindow * - * Returns the default widget for @window. See - * gtk_window_set_default() for more details. + * Returns the default widget for @window. + * + * See gtk_window_set_default_widget() for more details. * * Returns: (nullable) (transfer none): the default widget, or %NULL * if there is none. @@ -3252,9 +3235,8 @@ gtk_window_get_icon_name (GtkWindow *window) * gtk_window_set_default_icon_name: * @name: the name of the themed icon * - * Sets an icon to be used as fallback for windows that haven't - * had gtk_window_set_icon_list() called on them from a named - * themed icon, see gtk_window_set_icon_name(). + * Sets an icon to be used as fallback for windows that + * haven't had gtk_window_set_icon_name() called on them. **/ void gtk_window_set_default_icon_name (const char *name) @@ -3588,20 +3570,6 @@ gtk_window_resize (GtkWindow *window, * // ... * } * ]| - * - * If you are getting a window size in order to position the window - * on the screen, don't. You should, instead, simply let the window - * manager place windows. Also, if you set the transient parent of - * dialogs with gtk_window_set_transient_for() window managers will - * often center the dialog over its parent window. It's much preferred - * to let the window manager handle these cases rather than doing it - * yourself, because all apps will behave consistently and according to - * user or system preferences, if the window manager handles it. Also, - * the window manager can take into account the size of the window - * decorations and border that it may add, and of which GTK+ has no - * knowledge. Additionally, positioning windows in global screen coordinates - * may not be allowed by the windowing system. For more information, - * see: gtk_window_set_position(). */ void gtk_window_get_size (GtkWindow *window, @@ -6342,11 +6310,12 @@ _gtk_window_set_is_active (GtkWindow *window, * gtk_window_set_auto_startup_notification: * @setting: %TRUE to automatically do startup notification * - * By default, after showing the first #GtkWindow, GTK+ calls - * gdk_notify_startup_complete(). Call this function to disable - * the automatic startup notification. You might do this if your - * first window is a splash screen, and you want to delay notification - * until after your real main window has been shown, for example. + * By default, after showing the first #GtkWindow, GTK calls + * gdk_display_notify_startup_complete(). Call this function to + * disable the automatic startup notification. You might do this + * if your first window is a splash screen, and you want to delay + * notification until after your real main window has been shown, + * for example. * * In that example, you would disable startup notification * temporarily, show your splash screen, then re-enable it so that