<para>
A #GdkWindow is a rectangular region on the screen. It's a low-level object,
used to implement high-level objects such as #GtkWidget and #GtkWindow on the
-GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of
-as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow.
+GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of
+as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow.
For example, each #GtkButton has a #GdkWindow associated with it.
</para>
+<refsect2 id="COMPOSITED-WINDOWS"><title>Composited Windows</title>
+<para>
+Normally, the windowing system takes care of rendering the contents of a child
+window onto its parent window. This mechanism can be intercepted by calling
+gdk_window_set_composited() on the child window. For a
+<firstterm>composited</firstterm> window it is the responsibility of the
+application to render the window contents at the right spot.
+</para>
+<example id="composited-window-example"><title>Composited windows</title>
+<programlisting><![CDATA[
+#include <gtk/gtk.h>
+
+/* The expose event handler for the event box.
+ *
+ * This function simply draws a transparency onto a widget on the area
+ * for which it receives expose events. This is intended to give the
+ * event box a "transparent" background.
+ *
+ * In order for this to work properly, the widget must have an RGBA
+ * colourmap. The widget should also be set as app-paintable since it
+ * doesn't make sense for GTK+ to draw a background if we are drawing it
+ * (and because GTK+ might actually replace our transparency with its
+ * default background colour).
+ */
+static gboolean
+transparent_expose (GtkWidget *widget,
+ GdkEventExpose *event)
+{
+ cairo_t *cr;
+
+ cr = gdk_cairo_create (widget->window);
+ cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
+ gdk_cairo_region (cr, event->region);
+ cairo_fill (cr);
+ cairo_destroy (cr);
+
+ return FALSE;
+}
+
+/* The expose event handler for the window.
+ *
+ * This function performs the actual compositing of the event box onto
+ * the already-existing background of the window at 50% normal opacity.
+ *
+ * In this case we do not want app-paintable to be set on the widget
+ * since we want it to draw its own (red) background. Because of this,
+ * however, we must ensure that we use g_signal_connect_after so that
+ * this handler is called after the red has been drawn. If it was
+ * called before then GTK would just blindly paint over our work.
+ *
+ * Note: if the child window has children, then you need a cairo 1.6
+ * feature to make this work correctly.
+ */
+static gboolean
+window_expose_event (GtkWidget *widget,
+ GdkEventExpose *event)
+{
+ GdkRegion *region;
+ GtkWidget *child;
+ cairo_t *cr;
+
+ /* get our child (in this case, the event box) */
+ child = gtk_bin_get_child (GTK_BIN (widget));
+
+ /* create a cairo context to draw to the window */
+ cr = gdk_cairo_create (widget->window);
+
+ /* the source data is the (composited) event box */
+ gdk_cairo_set_source_pixmap (cr, child->window,
+ child->allocation.x,
+ child->allocation.y);
+
+ /* draw no more than our expose event intersects our child */
+ region = gdk_region_rectangle (&child->allocation);
+ gdk_region_intersect (region, event->region);
+ gdk_cairo_region (cr, region);
+ cairo_clip (cr);
+
+ /* composite, with a 50% opacity */
+ cairo_set_operator (cr, CAIRO_OPERATOR_OVER);
+ cairo_paint_with_alpha (cr, 0.5);
+
+ /* we're done */
+ cairo_destroy (cr);
+
+ return FALSE;
+}
+
+int
+main (int argc, char **argv)
+{
+ GtkWidget *window, *event, *button;
+ GdkScreen *screen;
+ GdkColormap *rgba;
+ GdkColor red;
+
+ gtk_init (&argc, &argv);
+
+ /* Make the widgets */
+ button = gtk_button_new_with_label ("A Button");
+ event = gtk_event_box_new ();
+ window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+
+ /* Put a red background on the window */
+ gdk_color_parse ("red", &red);
+ gtk_widget_modify_bg (window, GTK_STATE_NORMAL, &red);
+
+ /* Set the colourmap for the event box.
+ * Must be done before the event box is realised.
+ */
+ screen = gtk_widget_get_screen (event);
+ rgba = gdk_screen_get_rgba_colormap (screen);
+ gtk_widget_set_colormap (event, rgba);
+
+ /* Set our event box to have a fully-transparent background
+ * drawn on it. Currently there is no way to simply tell GTK+
+ * that "transparency" is the background colour for a widget.
+ */
+ gtk_widget_set_app_paintable (GTK_WIDGET (event), TRUE);
+ g_signal_connect (event, "expose-event",
+ G_CALLBACK (transparent_expose), NULL);
+
+ /* Put them inside one another */
+ gtk_container_set_border_width (GTK_CONTAINER (window), 10);
+ gtk_container_add (GTK_CONTAINER (window), event);
+ gtk_container_add (GTK_CONTAINER (event), button);
+
+ /* Realise and show everything */
+ gtk_widget_show_all (window);
+
+ /* Set the event box GdkWindow to be composited.
+ * Obviously must be performed after event box is realised.
+ */
+ gdk_window_set_composited (event->window, TRUE);
+
+ /* Set up the compositing handler.
+ * Note that we do _after_ so that the normal (red) background is drawn
+ * by gtk before our compositing occurs.
+ */
+ g_signal_connect_after (window, "expose-event",
+ G_CALLBACK (window_expose_event), NULL);
+
+ gtk_main ();
+
+ return 0;
+}
+]]>
+</programlisting></example>
+<para>
+In the example <xref linkend="composited-window-example"/>, a button is
+placed inside of an event box inside of a window. The event box is
+set as composited and therefore is no longer automatically drawn to
+the screen.
+</para>
+<para>
+When the contents of the event box change, an expose event is
+generated on its parent window (which, in this case, belongs to
+the toplevel #GtkWindow). The expose handler for this widget is
+responsible for merging the changes back on the screen in the way
+that it wishes.
+</para>
+<para>
+In our case, we merge the contents with a 50% transparency. We
+also set the background colour of the window to red. The effect is
+that the background shows through the button.
+</para>
+</refsect2>
+<refsect2 id="OFFSCREEN-WINDOWS"><title>Offscreen Windows</title>
+<para>
+Offscreen windows are more general than composited windows, since they
+allow not only to modify the rendering of the child window onto its parent,
+but also to apply coordinate transformations.
+</para>
+<para>
+To integrate an offscreen window into a window hierarchy, one has to call
+gdk_offscreen_window_set_embedder() and handle a number of signals. The
+#GdkWindow::pick-embedded-child signal on the embedder window is used to
+select an offscreen child at given coordinates, and the #GdkWindow::to-embedder
+and #GdkWindow::from-embedder signals on the offscreen window are used to
+translate coordinates between the embedder and the offscreen window.
+</para>
+
+<para>
+For rendering an offscreen window onto its embedder, the contents of the
+offscreen window are available as a pixmap, via
+gdk_offscreen_window_get_pixmap().
+</para>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### SECTION Stability_Level ##### -->
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GdkWindow ##### -->
<para>
An opaque structure representing an onscreen drawable.
</para>
+<!-- ##### SIGNAL GdkWindow::from-embedder ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
+@arg4:
+
+<!-- ##### SIGNAL GdkWindow::pick-embedded-child ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1:
+@arg2:
+@Returns:
+
+<!-- ##### SIGNAL GdkWindow::to-embedder ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
+@arg4:
+
+<!-- ##### ARG GdkWindow:cursor ##### -->
+<para>
+
+</para>
+
<!-- ##### ENUM GdkWindowType ##### -->
<para>
Describes the kind of window.
@GDK_WINDOW_ROOT: root window; this window has no parent, covers the entire screen, and is created by the window system
@GDK_WINDOW_TOPLEVEL: toplevel window (used to implement #GtkWindow)
-@GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkButton)
+@GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkEntry)
@GDK_WINDOW_DIALOG: useless/deprecated compatibility type
@GDK_WINDOW_TEMP: override redirect temporary window (used to implement #GtkMenu)
@GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new())
+@GDK_WINDOW_OFFSCREEN: offscreen window (see <xref linkend="OFFSCREEN-WINDOWS"/>). Since 2.18
<!-- ##### ENUM GdkWindowClass ##### -->
<para>
</para>
@min_width: minimum width of window (or -1 to use requisition, with #GtkWindow only)
-@min_height minimum height of window (or -1 to use requisition, with #GtkWindow only)
-@min_height:
+@min_height: minimum height of window (or -1 to use requisition, with #GtkWindow only)
@max_width: maximum width of window (or -1 to use requisition, with #GtkWindow only)
@max_height: maximum height of window (or -1 to use requisition, with #GtkWindow only)
@base_width: allowed window widths are @base_width + @width_inc * N where N is any integer (-1 allowed with #GtkWindow)
Defines the reference point of a window and the meaning of coordinates
passed to gtk_window_move(). See gtk_window_move() and the "implementation
notes" section of the
-<ulink url="http://www.freedesktop.org/standards/wm-spec">extended
-window manager hints</ulink> specification for more details.
+<ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended
+Window Manager Hints</ulink> specification for more details.
</para>
@GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner.
</para>
<para>
See the
-<ulink url="http://www.freedesktop.org/standards/wm-spec">extended
-window manager hints</ulink> specification for more details about
+<ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended
+Window Manager Hints</ulink> specification for more details about
window types.
</para>
@GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window.
@GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window.
-@GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu.
+@GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu; GTK+ uses
+ this hint only for torn-off menus, see #GtkTearoffMenuItem.
@GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars.
@GDK_WINDOW_TYPE_HINT_SPLASHSCREEN: Window used to display a splash
screen during application startup.
@GDK_WINDOW_TYPE_HINT_DOCK: Used for creating dock or panel windows.
@GDK_WINDOW_TYPE_HINT_DESKTOP: Used for creating the desktop background
window.
+@GDK_WINDOW_TYPE_HINT_DROPDOWN_MENU: A menu that belongs to a menubar.
+@GDK_WINDOW_TYPE_HINT_POPUP_MENU: A menu that does not belong to a menubar,
+ e.g. a context menu.
+@GDK_WINDOW_TYPE_HINT_TOOLTIP: A tooltip.
+@GDK_WINDOW_TYPE_HINT_NOTIFICATION: A notification - typically a "bubble"
+ that belongs to a status icon.
+@GDK_WINDOW_TYPE_HINT_COMBO: A popup from a combo box.
+@GDK_WINDOW_TYPE_HINT_DND: A window that is used to implement a DND cursor.
<!-- ##### STRUCT GdkWindowAttr ##### -->
<para>
@wmclass_name: don't use (see gtk_window_set_wmclass())
@wmclass_class: don't use (see gtk_window_set_wmclass())
@override_redirect: %TRUE to bypass the window manager
+@type_hint: a hint of the function of the window
<!-- ##### ENUM GdkWindowAttributesType ##### -->
<para>
@GDK_WA_VISUAL: Honor the visual field
@GDK_WA_WMCLASS: Honor the wmclass_class and wmclass_name fields
@GDK_WA_NOREDIR: Honor the override_redirect field
+@GDK_WA_TYPE_HINT: Honor the type_hint field
<!-- ##### FUNCTION gdk_window_new ##### -->
<para>
@window:
+<!-- ##### FUNCTION gdk_window_is_destroyed ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
<!-- ##### FUNCTION gdk_window_is_visible ##### -->
<para>
@setting:
+<!-- ##### FUNCTION gdk_window_set_opacity ##### -->
+<para>
+
+</para>
+
+@window:
+@opacity:
+
+
+<!-- ##### FUNCTION gdk_window_set_composited ##### -->
+<para>
+
+</para>
+
+@window:
+@composited:
+
+
<!-- ##### FUNCTION gdk_window_move ##### -->
<para>
@dy:
+<!-- ##### FUNCTION gdk_window_flush ##### -->
+<para>
+
+</para>
+
+@window:
+
+
+<!-- ##### FUNCTION gdk_window_ensure_native ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
<!-- ##### FUNCTION gdk_window_reparent ##### -->
<para>
@window:
+<!-- ##### FUNCTION gdk_window_restack ##### -->
+<para>
+
+</para>
+
+@window:
+@sibling:
+@above:
+
+
<!-- ##### FUNCTION gdk_window_focus ##### -->
<para>
@new_height:
+<!-- ##### FUNCTION gdk_window_beep ##### -->
+<para>
+
+</para>
+
+@window:
+
+
<!-- ##### FUNCTION gdk_window_begin_paint_rect ##### -->
<para>
@window:
@region:
-@child_func:
+@GdkWindow *, gpointer:
@user_data:
</para>
+@void:
<!-- ##### FUNCTION gdk_window_process_updates ##### -->
@window:
+<!-- ##### FUNCTION gdk_window_input_shape_combine_mask ##### -->
+<para>
+
+</para>
+
+@window:
+@mask:
+@x:
+@y:
+
+
+<!-- ##### FUNCTION gdk_window_input_shape_combine_region ##### -->
+<para>
+
+</para>
+
+@window:
+@shape_region:
+@offset_x:
+@offset_y:
+
+
+<!-- ##### FUNCTION gdk_window_set_child_input_shapes ##### -->
+<para>
+
+</para>
+
+@window:
+
+
+<!-- ##### FUNCTION gdk_window_merge_child_input_shapes ##### -->
+<para>
+
+</para>
+
+@window:
+
+
<!-- ##### FUNCTION gdk_window_set_static_gravities ##### -->
<para>
@cursor:
+<!-- ##### FUNCTION gdk_window_get_cursor ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
<!-- ##### MACRO gdk_window_set_colormap ##### -->
<para>
Deprecated equivalent to gdk_drawable_set_colormap()
@hint:
+<!-- ##### FUNCTION gdk_window_get_type_hint ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
<!-- ##### FUNCTION gdk_window_set_skip_taskbar_hint ##### -->
<para>
@Returns:
+<!-- ##### FUNCTION gdk_window_get_root_coords ##### -->
+<para>
+
+</para>
+
+@window:
+@x:
+@y:
+@root_x:
+@root_y:
+
+
<!-- ##### FUNCTION gdk_window_get_pointer ##### -->
<para>
<para>
Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.
</para>
+<para>
+Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped
+to Mod2 - Mod5, and indicates this by setting %GDK_SUPER_MASK, %GDK_HYPER_MASK
+or %GDK_META_MASK in the state field of key events.
+</para>
@GDK_SHIFT_MASK: the Shift key.
@GDK_LOCK_MASK: a Lock key (depending on the modifier mapping of the
@GDK_BUTTON3_MASK: the third mouse button.
@GDK_BUTTON4_MASK: the fourth mouse button.
@GDK_BUTTON5_MASK: the fifth mouse button.
+@GDK_SUPER_MASK: the Super modifier. Since 2.10
+@GDK_HYPER_MASK: the Hyper modifier. Since 2.10
+@GDK_META_MASK: the Meta modifier. Since 2.10
@GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate
between (keyval, modifiers) pairs from key press and release events.
@GDK_MODIFIER_MASK: a mask covering all modifier types.
@role:
+<!-- ##### FUNCTION gdk_window_set_startup_id ##### -->
+<para>
+
+</para>
+
+@window:
+@startup_id:
+
+
<!-- ##### FUNCTION gdk_window_set_group ##### -->
<para>
</para>
+@void:
@Returns:
</para>
+@void:
@Returns:
@Returns:
+<!-- ##### FUNCTION gdk_offscreen_window_get_pixmap ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_offscreen_window_set_embedder ##### -->
+<para>
+
+</para>
+
+@window:
+@embedder:
+
+
+<!-- ##### FUNCTION gdk_offscreen_window_get_embedder ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_window_geometry_changed ##### -->
+<para>
+
+</para>
+
+@window:
+
+
+<!-- ##### FUNCTION gdk_window_redirect_to_drawable ##### -->
+<para>
+
+</para>
+
+@window:
+@drawable:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+
+
+<!-- ##### FUNCTION gdk_window_remove_redirection ##### -->
+<para>
+
+</para>
+
+@window:
+
+
<!--
Local variables:
mode: sgml
projects / ~andy / gtk / blobdiff