From bb7ef098c4090afac6bc0044e03f0fc6d45d99fe Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Wed, 13 Nov 2013 15:11:21 +0100 Subject: [PATCH] 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 | 19 ++++ 5 files changed, 120 insertions(+), 69 deletions(-) diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 9b155a249b..dc726b160a 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -190,6 +190,7 @@ + diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 707dea5790..0c9237c660 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -5692,6 +5692,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 GTK_WINDOW @@ -7853,3 +7856,16 @@ gtk_flow_box_child_get_index gtk_flow_box_child_is_selected gtk_flow_box_child_changed + +
+gtkpopover +GtkPopover +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 +
diff --git a/docs/reference/gtk/gtk3.types.in b/docs/reference/gtk/gtk3.types.in index c20b83f9e4..609f54b4ec 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 b1380cbdee..e68e98362f 100644 --- a/gtk/gtkpopover.c +++ b/gtk/gtkpopover.c @@ -15,21 +15,23 @@ * License along with this library. If not, see . */ -/* - * 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 #GtkPopovers, if a + * modal behavior is desired, a GTK+ grab can be added with gtk_grab_add() */ #include "config.h" @@ -791,13 +793,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", @@ -805,6 +821,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", @@ -966,15 +989,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) { @@ -983,20 +1007,16 @@ gtk_popover_new (GtkWidget *relative_to) NULL); } -/* +/** * gtk_popover_set_relative_to: - * @window: a #GtkPopover - * @relative_to: a #GdkWindow + * @popover: a #GtkPopover + * @relative_to: a #GtkWidget * - * 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() + * Sets a new widget to be attached to @popover. If @popover is + * visible, the position will be updated. * - * If @window is currently visible, it will be moved to reflect - * this change. - * - * Since: 3.8 - */ + * Since: 3.12 + **/ void gtk_popover_set_relative_to (GtkPopover *popover, GtkWidget *relative_to) @@ -1008,18 +1028,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) { @@ -1032,17 +1050,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) @@ -1054,19 +1072,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) @@ -1091,23 +1108,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. * * * 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 * * - * Since: 3.8 - */ + * Since: 3.12 + **/ void gtk_popover_set_position (GtkPopover *popover, GtkPositionType position) @@ -1119,16 +1135,14 @@ gtk_popover_set_position (GtkPopover *popover, gtk_popover_update_position (popover); } -/* +/** * gtk_popover_get_position: - * @window: a #GtkPopover + * @popover: a #GtkPopover * - * Returns the preferred position to place @window + * Returns the preferred position of @popover. * - * Returns: The preferred position - * - * 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 1abf559368..532bbafaca 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -11921,6 +11921,16 @@ _gtk_window_get_shadow_width (GtkWindow *window, get_shadow_width (GTK_WIDGET (window), border); } +/** + * 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) @@ -11947,6 +11957,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)