[gtkmm: 3/4] Update docs with latest changes from Gtk

From: Kjell Ahlstedt <kjellahl src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtkmm: 3/4] Update docs with latest changes from Gtk
Date: Wed, 5 Aug 2020 15:02:36 +0000 (UTC)

commit 26db10c7a9b8f8ed5c685037da33a12b7f376a8a
Author: Andreas Persson <andreasp56 outlook com>
Date:   Wed Aug 5 11:06:27 2020 +0200

    Update docs with latest changes from Gtk

 gtk/src/cellarea.hg         | 10 ++++------
 gtk/src/columnviewcolumn.hg |  6 ++++++
 gtk/src/drawingarea.hg      | 11 ++++-------
 gtk/src/dropdown.hg         |  6 ++----
 gtk/src/gesture.hg          | 17 +++++------------
 gtk/src/notebook.hg         |  2 +-
 gtk/src/singleselection.hg  |  5 +++++
 gtk/src/tooltip.hg          | 15 ---------------
 gtk/src/widget.hg           | 17 ++++++++---------
 9 files changed, 35 insertions(+), 54 deletions(-)
---
diff --git a/gtk/src/cellarea.hg b/gtk/src/cellarea.hg
index 2ee0de8a..9a0f571c 100644
--- a/gtk/src/cellarea.hg
+++ b/gtk/src/cellarea.hg
@@ -77,14 +77,12 @@ class GTKMM_API Snapshot;
  *
  * <h2>Cell Properties</h2>
  *
- * The CellArea introduces cell properties
- * for CellRenderers in very much the same way that Gtk::Container
- * introduces child properties
- * for Widgets. This provides some general interfaces for defining
+ * The CellArea introduces cell properties for CellRenderers.
+ * This provides some general interfaces for defining
  * the relationship cell areas have with their cells. For instance in a
- * CellAreaBox a cell might "expand" and receive extra space when
+ * CellAreaBox 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
+ * might be configured to “align” with adjacent rows which were requested
  * and rendered with the same CellAreaContext.
  *
  * To set the value of a cell property, use cell_set_property(). To obtain
diff --git a/gtk/src/columnviewcolumn.hg b/gtk/src/columnviewcolumn.hg
index bcfc8dac..8b836c55 100644
--- a/gtk/src/columnviewcolumn.hg
+++ b/gtk/src/columnviewcolumn.hg
@@ -32,6 +32,12 @@ class GTKMM_API ColumnView;
  *
  * %Gtk::ColumnViewColumn represents the columns being added to Gtk::ColumnView.
  *
+ * Columns have a title, and can optionally have a header menu set
+ * with set_header_menu().
+ *
+ * A sorter can be associated with a column using set_sorter(), to let
+ * users influence sorting by clicking on the column header.
+ *
  * @see Gtk::ColumnView
  */
 class GTKMM_API ColumnViewColumn : public Glib::Object
diff --git a/gtk/src/drawingarea.hg b/gtk/src/drawingarea.hg
index cd56d2e4..e7ca7535 100644
--- a/gtk/src/drawingarea.hg
+++ b/gtk/src/drawingarea.hg
@@ -90,13 +90,10 @@ namespace Gtk
  * Gtk::Widget::queue_draw_area() or Gtk::Widget::queue_draw().
  * This will cause the drawing area to call the draw function again.
  *
- * 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 draw function
- * to decide whether to draw the focus indicator. See
- * Gtk::StyleContext::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 is focused.
  *
  * @ingroup Widgets
  */
diff --git a/gtk/src/dropdown.hg b/gtk/src/dropdown.hg
index ba917907..3bf80d95 100644
--- a/gtk/src/dropdown.hg
+++ b/gtk/src/dropdown.hg
@@ -32,13 +32,11 @@ namespace Gtk
  *
  * The options are given to %Gtk::DropDown in the form of Gio::ListModel,
  * and how the individual options are represented is determined by
- * a Gtk::ListItemFactory. The default factory displays simple strings,
- * and expects to obtain these from the model by evaluating an expression
- * that has to be provided via set_expression().
+ * a Gtk::ListItemFactory. The default factory displays simple strings.
  *
  * %Gtk::DropDown knows how to obtain strings from the items in a
  * Gtk::StringList; for other models, you have to provide an expression
- * to find the strings.
+ * to find the strings via set_expression().
  *
  * %Gtk::DropDown can optionally allow search in the popup, which is
  * useful if the list of options is long. To enable the search entry,
diff --git a/gtk/src/gesture.hg b/gtk/src/gesture.hg
index a794a386..c2d73c52 100644
--- a/gtk/src/gesture.hg
+++ b/gtk/src/gesture.hg
@@ -42,10 +42,9 @@ _WRAP_ENUM(EventSequenceState, GtkEventSequenceState, decl_prefix GTKMM_API)
  * or more than that number of sequences, it won't check whether the gesture
  * is recognized.
  *
- * As soon as the gesture has the expected number of touches, the gesture will
- * run check signal regularly on input events until the gesture
- * is recognized. The criteria to consider a gesture as "recognized" is left to
- * Gesture 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 Gesture subclasses.
  *
  * A recognized gesture will then emit the following signals:
  * - signal_begin() when the gesture is recognized.
@@ -54,19 +53,13 @@ _WRAP_ENUM(EventSequenceState, GtkEventSequenceState, decl_prefix GTKMM_API)
  *
  * <h2>Event propagation</h2>
  *
- * In order to receive events, a gesture needs to either set a propagation phase
- * through EventController::set_propagation_phase(), or feed those manually
- * through EventController::handle_event().
+ * In order to receive events, a gesture needs to set a propagation phase
+ * through EventController::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 Widget::signal_button_press_event(),
- * Widget::signal_button_release_event(), Widget::signal_touch_event(), etc. Gestures
- * with the Gtk::PropagationPhase::TARGET phase are fed events from the default
- * Widget::signal_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.
diff --git a/gtk/src/notebook.hg b/gtk/src/notebook.hg
index 656f1dfd..dcf3749c 100644
--- a/gtk/src/notebook.hg
+++ b/gtk/src/notebook.hg
@@ -34,7 +34,7 @@ _CC_INCLUDE(gtk/gtk.h)
 
 /** Container which shows one of its children at a time, in tabbed windows.
  *
- * The Gtk::Notebook widget is a container whose children are pages that
+ * The Gtk::Notebook widget is a layout container whose children are pages that
  * can be switched between using tab labels along one edge.
  *
  * A Notebook widget looks like this:
diff --git a/gtk/src/singleselection.hg b/gtk/src/singleselection.hg
index 42dd0aff..0e8691ba 100644
--- a/gtk/src/singleselection.hg
+++ b/gtk/src/singleselection.hg
@@ -31,6 +31,11 @@ namespace Gtk
  * that allows selecting a single element. It is the default selection method
  * used by list widgets in GTK.
  *
+ * Note that the selection is *persistent* -- if the selected item is removed
+ * and re-added in the same Gio::ListModel::signal_items_changed() emission,
+ * it stays selected. In particular, this means that changing the sort order
+ * of an underlying sort model will preserve the selection.
+ *
  * @see SelectionModel
  * @newin{3,96}
  */
diff --git a/gtk/src/tooltip.hg b/gtk/src/tooltip.hg
index 53779064..3c635480 100644
--- a/gtk/src/tooltip.hg
+++ b/gtk/src/tooltip.hg
@@ -52,21 +52,6 @@ namespace Gtk
  * - 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
- * Window which will be used as tooltip window. This works as follows:
- *
- * - Do Gtk::Widget::set_has_tooltip() and connect to
- * Gtk::Widget::signal_query_tooltip() as before.
- *
- * - Use Gtk::Widget::set_tooltip_window() to set a Gtk::Window created
- * by you as tooltip window.
- *
- * - In the query-tooltip callback you can access your window
- * using Gtk::Widget::get_tooltip_window() and manipulate it as you
- * wish. The semantics of the return value are exactly as before,
- * return true to show the window, false to not show it.
- *
  * @newin{2,12}
  */
 class GTKMM_API Tooltip : public Glib::Object
diff --git a/gtk/src/widget.hg b/gtk/src/widget.hg
index 0d847c2d..2ad96d54 100644
--- a/gtk/src/widget.hg
+++ b/gtk/src/widget.hg
@@ -192,19 +192,18 @@ public:
   _WRAP_METHOD(int get_allocated_height() const, gtk_widget_get_allocated_height)
   _WRAP_METHOD(int get_allocated_baseline() const, gtk_widget_get_allocated_baseline)
 
-  /** Retrieves the widget's location.
-   * Note, when implementing a Container: a widget's allocation will be its "adjusted" allocation,
-   * that is, the widget's parent container typically calls size_allocate() with an allocation,
+  /** Retrieves the widget’s location.
+   * Note, when implementing a layout container: a widget’s allocation will be its “adjusted” allocation,
+   * that is, the widget’s parent container typically calls size_allocate() with an allocation,
    * and that allocation is then adjusted (to handle margin and alignment for example) before
    * assignment to the 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 size_allocate() allocation, however. So a Container is guaranteed that its
-   * children stay inside the assigned bounds, but not that they have exactly the bounds the
-   * container assigned. There is no way to get the original allocation assigned by
-   * size_allocate(), since it isn't stored. If a container implementation needs that information
-   * it will have to track it itself.
+   * within the size_allocate() allocation, however.
    *
-   * @return The widget's allocated area.
+   * 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.
+   *
+   * @return The widget’s allocated area.
    */
   Allocation get_allocation() const;
   _IGNORE(gtk_widget_get_allocation)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]