Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

popover: Add documentation

Browse Source
This commit is contained in:
Carlos Garnacho
2013-11-13 15:11:21 +01:00
parent 3ce119c47f
commit 8a4f597379
5 changed files with 120 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/gtk-docs.sgml
View File

@@ -190,6 +190,7 @@
<xi:include href="xml/gtkmenutoolbutton.xml" /> <xi:include href="xml/gtkmenutoolbutton.xml" />
<xi:include href="xml/gtktoggletoolbutton.xml" /> <xi:include href="xml/gtktoggletoolbutton.xml" />
<xi:include href="xml/gtkradiotoolbutton.xml" /> <xi:include href="xml/gtkradiotoolbutton.xml" />
<xi:include href="xml/gtkpopover.xml" />
</chapter> </chapter>
<chapter id="SelectorWidgets"> <chapter id="SelectorWidgets">

16
docs/reference/gtk/gtk3-sections.txt
View File

@@ -5673,6 +5673,9 @@ gtk_window_get_application
gtk_window_set_application gtk_window_set_application
gtk_window_set_has_user_ref_count gtk_window_set_has_user_ref_count
gtk_window_set_titlebar gtk_window_set_titlebar
gtk_window_add_popover
gtk_window_remove_popover
gtk_window_set_popover_position
<SUBSECTION Standard> <SUBSECTION Standard>
GTK_WINDOW GTK_WINDOW
@@ -7831,3 +7834,16 @@ gtk_flow_box_child_get_index
gtk_flow_box_child_is_selected gtk_flow_box_child_is_selected
gtk_flow_box_child_changed gtk_flow_box_child_changed
</SECTION> </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>

1
docs/reference/gtk/gtk3.types.in
View File

@@ -126,6 +126,7 @@ gtk_paned_get_type
gtk_paper_size_get_type gtk_paper_size_get_type
gtk_places_sidebar_get_type gtk_places_sidebar_get_type
@ENABLE_ON_X11@gtk_plug_get_type @ENABLE_ON_X11@gtk_plug_get_type
gtk_popover_get_type
@DISABLE_ON_W32@gtk_printer_get_type @DISABLE_ON_W32@gtk_printer_get_type
gtk_print_context_get_type gtk_print_context_get_type
@DISABLE_ON_W32@gtk_print_job_get_type @DISABLE_ON_W32@gtk_print_job_get_type

152
gtk/gtkpopover.c
View File

@@ -15,21 +15,23 @@
* License along with this library. If not, see <http://www.gnu.org/licenses/>. * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/ */
/* /**
* GtkPopover is a bubble-like context window, primarily mean for * SECTION:gtkpopover
* context-dependent helpers on touch interfaces. * @Short_description: Context dependent bubbles
* @Title: GtkPopover
* *
* In order to place a GtkPopover to point to some other area, * GtkPopover is a bubble-like context window, primarily meant to
* use gtk_popover_set_relative_to(), gtk_popover_set_pointing_to() * provide context-dependent information or options. Popovers are
* and gtk_popover_set_position(). Although it is usually more * attached to a widget, passed at construction time on gtk_popover_new(),
* convenient to use gtk_popover_popup() which handles all of those * or updated afterwards through gtk_popover_set_relative_to(), by
* at once. * 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 position of a popover relative to the widget it is attached to
* the popup/popdown semantics up to the caller, gtk_popover_grab() * can also be changed through gtk_popover_set_position().
* can be used to grab the window for a device pair, bringing #GtkMenu alike *
* popdown behavior by default on keyboard/pointer interaction. Grabs need * By default, no grabs are performed on #GtkPopover<!-- -->s, if a
* to be undone through gtk_popover_ungrab(). * modal behavior is desired, a GTK+ grab can be added with gtk_grab_add()
*/ */
#include "config.h" #include "config.h"
@@ -791,13 +793,27 @@ gtk_popover_class_init (GtkPopoverClass *klass)
widget_class->button_press_event = gtk_popover_button_press; widget_class->button_press_event = gtk_popover_button_press;
widget_class->key_press_event = gtk_popover_key_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, g_object_class_install_property (object_class,
PROP_RELATIVE_TO, PROP_RELATIVE_TO,
g_param_spec_object ("relative-to", g_param_spec_object ("relative-to",
P_("Relative to"), P_("Relative to"),
P_("Window the bubble window points to"), P_("Widget the bubble window points to"),
GTK_TYPE_WIDGET, GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE)); GTK_PARAM_READWRITE));
/**
* GtkPopover:pointing-to:
*
* Marks a specific rectangle to be pointed.
*
* Since: 3.12
*/
g_object_class_install_property (object_class, g_object_class_install_property (object_class,
PROP_POINTING_TO, PROP_POINTING_TO,
g_param_spec_boxed ("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"), P_("Rectangle the bubble window points to"),
CAIRO_GOBJECT_TYPE_RECTANGLE_INT, CAIRO_GOBJECT_TYPE_RECTANGLE_INT,
GTK_PARAM_READWRITE)); GTK_PARAM_READWRITE));
/**
* GtkPopover:position
*
* Sets the preferred position of the popover.
*
* Since: 3.12
*/
g_object_class_install_property (object_class, g_object_class_install_property (object_class,
PROP_POSITION, PROP_POSITION,
g_param_spec_enum ("position", g_param_spec_enum ("position",
@@ -966,15 +989,16 @@ gtk_popover_update_preferred_position (GtkPopover *popover,
g_object_notify (G_OBJECT (popover), "position"); g_object_notify (G_OBJECT (popover), "position");
} }
/* /**
* gtk_popover_new: * 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 * Returns: a new #GtkPopover
* *
* Since: 3.8 * Since: 3.12
*/ **/
GtkWidget * GtkWidget *
gtk_popover_new (GtkWidget *relative_to) gtk_popover_new (GtkWidget *relative_to)
{ {
@@ -983,20 +1007,16 @@ gtk_popover_new (GtkWidget *relative_to)
NULL); NULL);
} }
/* /**
* gtk_popover_set_relative_to: * gtk_popover_set_relative_to:
* @window: a #GtkPopover * @popover: a #GtkPopover
* @relative_to: a #GdkWindow * @relative_to: a #GtkWidget
* *
* Sets the #GdkWindow to act as the origin of coordinates of * Sets a new widget to be attached to @popover. If @popover is
* @window, or %NULL to use the root window. See * visible, the position will be updated.
* gtk_popover_set_pointing_to()
* *
* If @window is currently visible, it will be moved to reflect * Since: 3.12
* this change. **/
*
* Since: 3.8
*/
void void
gtk_popover_set_relative_to (GtkPopover *popover, gtk_popover_set_relative_to (GtkPopover *popover,
GtkWidget *relative_to) GtkWidget *relative_to)
@@ -1008,18 +1028,16 @@ gtk_popover_set_relative_to (GtkPopover *popover,
gtk_popover_update_position (popover); gtk_popover_update_position (popover);
} }
/* /**
* gtk_popover_get_relative_to: * gtk_popover_get_relative_to:
* @window: a #GtkPopover * @popover: a #GtkPopover
* *
* Returns the #GdkWindow used as the origin of coordinates. * Returns the wigdet @popover is currently attached to
* If @window is currently visible, it will be moved to reflect
* this change.
* *
* Returns: the #GdkWindow @window is placed upon * Returns: a #GtkWidget
* *
* Since: 3.8 * Since: 3.12
*/ **/
GtkWidget * GtkWidget *
gtk_popover_get_relative_to (GtkPopover *popover) gtk_popover_get_relative_to (GtkPopover *popover)
{ {
@@ -1032,17 +1050,17 @@ gtk_popover_get_relative_to (GtkPopover *popover)
return priv->widget; return priv->widget;
} }
/* /**
* gtk_popover_set_pointing_to: * gtk_popover_set_pointing_to:
* @window: a #GtkPopover * @popover: a #GtkPopover
* @rect: rectangle to point to * @rect: rectangle to point to
* *
* Sets the rectangle that @window will point to, the coordinates * Sets the rectangle that @popover will point to, in the coordinate
* of this rectangle are relative to the #GdkWindow set through * space of the widget @popover is attached to, see
* gtk_popover_set_relative_to(). * gtk_popover_set_relative_to()
* *
* Since: 3.8 * Since: 3.12
*/ **/
void void
gtk_popover_set_pointing_to (GtkPopover *popover, gtk_popover_set_pointing_to (GtkPopover *popover,
cairo_rectangle_int_t *rect) cairo_rectangle_int_t *rect)
@@ -1054,19 +1072,18 @@ gtk_popover_set_pointing_to (GtkPopover *popover,
gtk_popover_update_position (popover); gtk_popover_update_position (popover);
} }
/* /**
* gtk_popover_get_pointing_to: * gtk_popover_get_pointing_to:
* @window: a #GtkPopover * @popover: a #GtkPopover
* @rect: (out): location to store the rectangle * @rect: (out): location to store the rectangle
* *
* If a rectangle to point to is set, this function will return * If a rectangle to point to has been set, this function will
* %TRUE and fill in @rect with the rectangle @window is currently * return %TRUE and fill in @rect with such rectangle, otherwise
* pointing to. * it will return %FALSE and fill in @rect with the attached
* widget coordinates.
* *
* Returns: %TRUE if a rectangle is set * Returns: %TRUE if a rectangle to point to was set.
* **/
* Since: 3.8
*/
gboolean gboolean
gtk_popover_get_pointing_to (GtkPopover *popover, gtk_popover_get_pointing_to (GtkPopover *popover,
cairo_rectangle_int_t *rect) cairo_rectangle_int_t *rect)
@@ -1091,23 +1108,22 @@ gtk_popover_get_pointing_to (GtkPopover *popover,
return priv->has_pointing_to; return priv->has_pointing_to;
} }
/* /**
* gtk_popover_set_position: * gtk_popover_set_position:
* @window: a #GtkPopover * @popover: a #GtkPopover
* @position: preferred bubble position * @position: preferred popover position
* *
* Sets the preferred position for @window to appear. * Sets the preferred position for @popover to appear. If the @popover
* If @window is currently visible, it will be moved to reflect * is currently visible, it will be immediately updated.
* this change.
* *
* <note> * <note>
* This preference will be respected where possible, although * 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 * #GtkPopover may choose to appear on the opposite side
* </note> * </note>
* *
* Since: 3.8 * Since: 3.12
*/ **/
void void
gtk_popover_set_position (GtkPopover *popover, gtk_popover_set_position (GtkPopover *popover,
GtkPositionType position) GtkPositionType position)
@@ -1119,16 +1135,14 @@ gtk_popover_set_position (GtkPopover *popover,
gtk_popover_update_position (popover); gtk_popover_update_position (popover);
} }
/* /**
* gtk_popover_get_position: * 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 * Returns: The preferred position.
* **/
* Since: 3.8
*/
GtkPositionType GtkPositionType
gtk_popover_get_position (GtkPopover *popover) gtk_popover_get_position (GtkPopover *popover)
{ {

19
gtk/gtkwindow.c
View File

@@ -11914,6 +11914,16 @@ _gtk_window_get_shadow_width (GtkWindow *window,
get_shadow_width (GTK_WIDGET (window), border); 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 void
gtk_window_add_popover (GtkWindow *window, gtk_window_add_popover (GtkWindow *window,
GtkWidget *popover) GtkWidget *popover)
@@ -11940,6 +11950,15 @@ gtk_window_add_popover (GtkWindow *window,
gtk_widget_set_parent (popover, GTK_WIDGET (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 void
gtk_window_remove_popover (GtkWindow *window, gtk_window_remove_popover (GtkWindow *window,
GtkWidget *popover) GtkWidget *popover)