GNOME.org
 

[gtk+/popovers: 16/17] popover: Add documentation

commit e8f0c010e5cd000e39d5d41987e05437057d7631
Author: Carlos Garnacho <carlosg gnome org>
Date:   Wed Nov 13 15:11:21 2013 +0100

    popover: Add documentation

 docs/reference/gtk/gtk-docs.sgml     |    1 +
 docs/reference/gtk/gtk3-sections.txt |   16 ++++
 docs/reference/gtk/gtk3.types.in     |    1 +
 gtk/gtkpopover.c                     |  152 ++++++++++++++++++---------------
 gtk/gtkwindow.c                      |   34 ++++++++
 5 files changed, 135 insertions(+), 69 deletions(-)
---
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index ff9f151..4c3e92e 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -189,6 +189,7 @@
       <xi:include href="xml/gtkmenutoolbutton.xml" />
       <xi:include href="xml/gtktoggletoolbutton.xml" />
       <xi:include href="xml/gtkradiotoolbutton.xml" />
+      <xi:include href="xml/gtkpopover.xml" />
     </chapter>
 
     <chapter id="SelectorWidgets">
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index cc56f00..9fbd64d 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -5666,6 +5666,9 @@ gtk_window_get_application
 gtk_window_set_application
 gtk_window_set_has_user_ref_count
 gtk_window_set_titlebar
+gtk_window_add_popover
+gtk_window_remove_popover
+gtk_window_set_popover_position
 
 <SUBSECTION Standard>
 GTK_WINDOW
@@ -7796,3 +7799,16 @@ gtk_flow_box_child_get_index
 gtk_flow_box_child_is_selected
 gtk_flow_box_child_changed
 </SECTION>
+
+<SECTION>
+<FILE>gtkpopover</FILE>
+<TITLE>GtkPopover</TITLE>
+GtkPopover
+gtk_popover_new
+gtk_popover_set_relative_to
+gtk_popover_get_relative_to
+gtk_popover_set_pointing_to
+gtk_popover_get_pointing_to
+gtk_popover_set_position
+gtk_popover_get_position
+</SECTION>
diff --git a/docs/reference/gtk/gtk3.types.in b/docs/reference/gtk/gtk3.types.in
index c20b83f..609f54b 100644
--- a/docs/reference/gtk/gtk3.types.in
+++ b/docs/reference/gtk/gtk3.types.in
@@ -126,6 +126,7 @@ gtk_paned_get_type
 gtk_paper_size_get_type
 gtk_places_sidebar_get_type
 @ENABLE_ON_X11 gtk_plug_get_type
+gtk_popover_get_type
 @DISABLE_ON_W32 gtk_printer_get_type
 gtk_print_context_get_type
 @DISABLE_ON_W32 gtk_print_job_get_type
diff --git a/gtk/gtkpopover.c b/gtk/gtkpopover.c
index 566826c..4558fc8 100644
--- a/gtk/gtkpopover.c
+++ b/gtk/gtkpopover.c
@@ -15,21 +15,23 @@
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
-/*
- * GtkPopover is a bubble-like context window, primarily mean for
- * context-dependent helpers on touch interfaces.
+/**
+ * SECTION:gtkpopover
+ * @Short_description: Context dependent bubbles
+ * @Title: GtkPopover
  *
- * In order to place a GtkPopover to point to some other area,
- * use gtk_popover_set_relative_to(), gtk_popover_set_pointing_to()
- * and gtk_popover_set_position(). Although it is usually  more
- * convenient to use gtk_popover_popup() which handles all of those
- * at once.
+ * GtkPopover is a bubble-like context window, primarily meant to
+ * provide context-dependent information or options. Popovers are
+ * attached to a widget, passed at construction time on gtk_popover_new(),
+ * or updated afterwards through gtk_popover_set_relative_to(), by
+ * default they will point to the whole widget area, although this
+ * behavior can be changed through gtk_popover_set_pointing_to().
  *
- * By default, no grabs are performed on the GtkPopover, leaving
- * the popup/popdown semantics up to the caller, gtk_popover_grab()
- * can be used to grab the window for a device pair, bringing #GtkMenu alike
- * popdown behavior by default on keyboard/pointer interaction. Grabs need
- * to be undone through gtk_popover_ungrab().
+ * The position of a popover relative to the widget it is attached to
+ * can also be changed through gtk_popover_set_position().
+ *
+ * By default, no grabs are performed on #GtkPopover<!-- -->s, if a
+ * modal behavior is desired, a GTK+ grab can be added with gtk_grab_add()
  */
 
 #include "config.h"
@@ -830,13 +832,27 @@ gtk_popover_class_init (GtkPopoverClass *klass)
   widget_class->button_press_event = gtk_popover_button_press;
   widget_class->key_press_event = gtk_popover_key_press;
 
+  /**
+   * GtkPopover:relative-to:
+   *
+   * Sets the attached widget.
+   *
+   * Since: 3.12
+   */
   g_object_class_install_property (object_class,
                                    PROP_RELATIVE_TO,
                                    g_param_spec_object ("relative-to",
                                                         P_("Relative to"),
-                                                        P_("Window the bubble window points to"),
+                                                        P_("Widget the bubble window points to"),
                                                         GTK_TYPE_WIDGET,
                                                         GTK_PARAM_READWRITE));
+  /**
+   * GtkPopover:pointing-to:
+   *
+   * Marks a specific rectangle to be pointed.
+   *
+   * Since: 3.12
+   */
   g_object_class_install_property (object_class,
                                    PROP_POINTING_TO,
                                    g_param_spec_boxed ("pointing-to",
@@ -844,6 +860,13 @@ gtk_popover_class_init (GtkPopoverClass *klass)
                                                        P_("Rectangle the bubble window points to"),
                                                        CAIRO_GOBJECT_TYPE_RECTANGLE_INT,
                                                        GTK_PARAM_READWRITE));
+  /**
+   * GtkPopover:position
+   *
+   * Sets the preferred position of the popover.
+   *
+   * Since: 3.12
+   */
   g_object_class_install_property (object_class,
                                    PROP_POSITION,
                                    g_param_spec_enum ("position",
@@ -975,15 +998,16 @@ gtk_popover_update_preferred_position (GtkPopover      *popover,
   g_object_notify (G_OBJECT (popover), "position");
 }
 
-/*
+/**
  * gtk_popover_new:
+ * @relative_to: #GtkWidget the popover is related to
  *
- * Returns a newly created #GtkBubblewindow
+ * Creates a new popover to point to @relative_to
  *
  * Returns: a new #GtkPopover
  *
- * Since: 3.8
- */
+ * Since: 3.12
+ **/
 GtkWidget *
 gtk_popover_new (GtkWidget *relative_to)
 {
@@ -992,20 +1016,16 @@ gtk_popover_new (GtkWidget *relative_to)
                        NULL);
 }
 
-/*
+/**
  * gtk_popover_set_relative_to:
- * @window: a #GtkPopover
- * @relative_to: a #GdkWindow
- *
- * Sets the #GdkWindow to act as the origin of coordinates of
- * @window, or %NULL to use the root window. See
- * gtk_popover_set_pointing_to()
+ * @popover: a #GtkPopover
+ * @relative_to: a #GtkWidget
  *
- * If @window is currently visible, it will be moved to reflect
- * this change.
+ * Sets a new widget to be attached to @popover. If @popover is
+ * visible, the position will be updated.
  *
- * Since: 3.8
- */
+ * Since: 3.12
+ **/
 void
 gtk_popover_set_relative_to (GtkPopover *popover,
                              GtkWidget  *relative_to)
@@ -1019,18 +1039,16 @@ gtk_popover_set_relative_to (GtkPopover *popover,
     gtk_popover_update_position (popover);
 }
 
-/*
+/**
  * gtk_popover_get_relative_to:
- * @window: a #GtkPopover
+ * @popover: a #GtkPopover
  *
- * Returns the #GdkWindow used as the origin of coordinates.
- * If @window is currently visible, it will be moved to reflect
- * this change.
+ * Returns the wigdet @popover is currently attached to
  *
- * Returns: the #GdkWindow @window is placed upon
+ * Returns: a #GtkWidget
  *
- * Since: 3.8
- */
+ * Since: 3.12
+ **/
 GtkWidget *
 gtk_popover_get_relative_to (GtkPopover *popover)
 {
@@ -1043,17 +1061,17 @@ gtk_popover_get_relative_to (GtkPopover *popover)
   return priv->widget;
 }
 
-/*
+/**
  * gtk_popover_set_pointing_to:
- * @window: a #GtkPopover
+ * @popover: a #GtkPopover
  * @rect: rectangle to point to
  *
- * Sets the rectangle that @window will point to, the coordinates
- * of this rectangle are relative to the #GdkWindow set through
- * gtk_popover_set_relative_to().
+ * Sets the rectangle that @popover will point to, in the coordinate
+ * space of the widget @popover is attached to, see
+ * gtk_popover_set_relative_to()
  *
- * Since: 3.8
- */
+ * Since: 3.12
+ **/
 void
 gtk_popover_set_pointing_to (GtkPopover            *popover,
                              cairo_rectangle_int_t *rect)
@@ -1067,19 +1085,18 @@ gtk_popover_set_pointing_to (GtkPopover            *popover,
     gtk_popover_update_position (popover);
 }
 
-/*
+/**
  * gtk_popover_get_pointing_to:
- * @window: a #GtkPopover
+ * @popover: a #GtkPopover
  * @rect: (out): location to store the rectangle
  *
- * If a rectangle to point to is set, this function will return
- * %TRUE and fill in @rect with the rectangle @window is currently
- * pointing to.
+ * If a rectangle to point to has been set, this function will
+ * return %TRUE and fill in @rect with such rectangle, otherwise
+ * it will return %FALSE and fill in @rect with the attached
+ * widget coordinates.
  *
- * Returns: %TRUE if a rectangle is set
- *
- * Since: 3.8
- */
+ * Returns: %TRUE if a rectangle to point to was set.
+ **/
 gboolean
 gtk_popover_get_pointing_to (GtkPopover            *popover,
                              cairo_rectangle_int_t *rect)
@@ -1104,23 +1121,22 @@ gtk_popover_get_pointing_to (GtkPopover            *popover,
   return priv->has_pointing_to;
 }
 
-/*
+/**
  * gtk_popover_set_position:
- * @window: a #GtkPopover
- * @position: preferred bubble position
+ * @popover: a #GtkPopover
+ * @position: preferred popover position
  *
- * Sets the preferred position for @window to appear.
- * If @window is currently visible, it will be moved to reflect
- * this change.
+ * Sets the preferred position for @popover to appear. If the @popover
+ * is currently visible, it will be immediately updated.
  *
  * <note>
  *   This preference will be respected where possible, although
- *   on lack of space (eg. if close to the screen edges), the
+ *   on lack of space (eg. if close to the window edges), the
  *   #GtkPopover may choose to appear on the opposite side
  * </note>
  *
- * Since: 3.8
- */
+ * Since: 3.12
+ **/
 void
 gtk_popover_set_position (GtkPopover      *popover,
                           GtkPositionType  position)
@@ -1134,16 +1150,14 @@ gtk_popover_set_position (GtkPopover      *popover,
     gtk_popover_update_position (popover);
 }
 
-/*
+/**
  * gtk_popover_get_position:
- * @window: a #GtkPopover
- *
- * Returns the preferred position to place @window
+ * @popover: a #GtkPopover
  *
- * Returns: The preferred position
+ * Returns the preferred position of @popover.
  *
- * Since: 3.8
- */
+ * Returns: The preferred position.
+ **/
 GtkPositionType
 gtk_popover_get_position (GtkPopover *popover)
 {
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 7139041..dbe55ec 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -11866,6 +11866,16 @@ _gtk_window_handle_button_press_for_widget (GtkWidget      *widget,
   return FALSE;
 }
 
+/**
+ * gtk_window_add_popover:
+ * @window: a #GtkWindow
+ * @popover: a #GtkWidget to be added as a popover of @window
+ *
+ * Adds a widget so it acts as a popover within @window, it can
+ * be later positioned through gtk_window_set_popover_position().
+ *
+ * Since: 3.12
+ **/
 void
 gtk_window_add_popover (GtkWindow *window,
                         GtkWidget *popover)
@@ -11892,6 +11902,15 @@ gtk_window_add_popover (GtkWindow *window,
   gtk_widget_set_parent (popover, GTK_WIDGET (window));
 }
 
+/**
+ * gtk_window_remove_popover:
+ * @window: a #GtkWindow
+ * @popover: a #GtkWidget acting as a popover on @window
+ *
+ * Removes @popover from being a popover of @window.
+ *
+ * Since: 3.12
+ **/
 void
 gtk_window_remove_popover (GtkWindow *window,
                            GtkWidget *popover)
@@ -11905,6 +11924,21 @@ gtk_window_remove_popover (GtkWindow *window,
   g_hash_table_remove (priv->popovers, popover);
 }
 
+/**
+ * gtk_window_set_popover_position:
+ * @window: a #GtkWindow
+ * @popover: #GtkWidget to be positioned on top of window contents
+ * @pos: Position of the popover, relative of the contents it's related to
+ * @x: X position in toplevel coordinates
+ * @y: Y position in toplevel coordinates
+ *
+ * Positions @popover in the @x and @y coordinates given, relative to @window.
+ * If @popover is set to expand horizontally or vertically, the position given
+ * by @pos will be used to determine how the popover is allowed to expand
+ * without covering the content it's logically attached to.
+ *
+ * Since: 3.12
+ **/
 void
 gtk_window_set_popover_position (GtkWindow       *window,
                                  GtkWidget       *popover,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]