callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve CSW docs

Browse Source
This commit is contained in:
Matthias Clasen
2009-08-31 00:55:32 -04:00
parent 97d4b25d02
commit 5e5ab90a57
3 changed files with 71 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/reference/gdk/tmpl/windows.sgml
View File

@ -8,10 +8,18 @@ Onscreen display areas in the target window system
<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>
@ -54,7 +62,7 @@ transparent_expose (GtkWidget *widget,
* 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.16
* Note: if the child window has children, then you need a cairo 1.6
* feature to make this work correctly.
*/
static gboolean
@ -153,10 +161,10 @@ main (int argc, char **argv)
]]>
</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.
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
@ -168,8 +176,25 @@ that it wishes.
<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.
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_window_set_embedder() and handle a number of signals. The
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>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>

7
gdk/gdkoffscreenwindow.c
View File

@ -1161,6 +1161,13 @@ gdk_offscreen_window_queue_translation (GdkWindow *window,
* @window: a #GdkWindow
* @embedder: the #GdkWindow that @window gets embedded in
*
* Sets @window to be embedded in @embedder.
*
* To fully embed an offscreen window, in addition to calling this
* function, it is also necessary to handle the #GdkWindow::pick-embedded-child
* signal on the @embedder and the #GdkWindow::to-embedder and
* #GdkWindow::from-embedder signals on @window.
*
* Since: 2.18
*/
void

49
gdk/gdkwindow.c
View File

@ -480,7 +480,7 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
* The ::pick-embedded-child signal is emitted to find an embedded
* child at the given position.
*
* Returns: the GdkWindow of the embedded child at @x, @y, or %NULL
* Returns: the #GdkWindow of the embedded child at @x, @y, or %NULL
*
* Since: 2.18
*/
@ -507,6 +507,8 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
* The ::to-embedder signal is emitted to translate coordinates
* in an offscreen window to its embedder.
*
* See also #GtkWindow::from-embedder.
*
* Since: 2.18
*/
signals[TO_EMBEDDER] =
@ -534,6 +536,8 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
* The ::from-embedder signal is emitted to translate coordinates
* in the embedder of an offscreen window to the offscreen window.
*
* See also #GtkWindow::to-embedder.
*
* Since: 2.18
*/
signals[FROM_EMBEDDER] =
@ -2307,7 +2311,7 @@ gdk_screen_get_toplevel_windows (GdkScreen *screen)
* Return value: list of toplevel windows, free with g_list_free()
*
* Deprecated: 2.16: Use gdk_screen_get_toplevel_windows() instead.
**/
*/
GList *
gdk_window_get_toplevels (void)
{
@ -7238,7 +7242,6 @@ gdk_window_set_back_pixmap (GdkWindow *window,
/**
* gdk_window_get_cursor:
* @window: a #GdkWindow
* @cursor: a cursor
*
* Retrieves a #GdkCursor pointer for the cursor currently set on the
* specified #GdkWindow, or %NULL. If the return value is %NULL then
@ -8074,8 +8077,8 @@ apply_redirect_to_children (GdkWindowObject *private,
* @src_y: y position in @window
* @dest_x: x position in @drawable
* @dest_y: y position in @drawable
* @width: width of redirection
* @height: height of redirection
* @width: width of redirection, or -1 to use the width of @window
* @height: height of redirection or -1 to use the height of @window
*
* Redirects drawing into @window so that drawing to the
* window in the rectangle specified by @src_x, @src_y,
@ -8351,8 +8354,10 @@ update_cursor (GdkDisplay *display)
static void
from_embedder (GdkWindowObject *window,
double embedder_x, double embedder_y,
double *offscreen_x, double *offscreen_y)
gdouble embedder_x,
gdouble embedder_y,
gdouble *offscreen_x,
gdouble *offscreen_y)
{
g_signal_emit (window,
signals[FROM_EMBEDDER], 0,
@ -8363,8 +8368,10 @@ from_embedder (GdkWindowObject *window,
static void
convert_coords_to_child (GdkWindowObject *child,
double x, double y,
double *child_x, double *child_y)
gdouble x,
gdouble y,
gdouble *child_x,
gdouble *child_y)
{
if (gdk_window_is_offscreen (child))
{
@ -8380,7 +8387,8 @@ convert_coords_to_child (GdkWindowObject *child,
static gboolean
point_in_window (GdkWindowObject *window,
double x, double y)
gdouble x,
gdouble y)
{
return
x >= 0 && x < window->width &&
@ -8395,8 +8403,10 @@ point_in_window (GdkWindowObject *window,
static GdkWindow *
convert_native_coords_to_toplevel (GdkWindow *window,
double child_x, double child_y,
double *toplevel_x, double *toplevel_y)
gdouble child_x,
gdouble child_y,
gdouble *toplevel_x,
gdouble *toplevel_y)
{
GdkWindowObject *private = (GdkWindowObject *)window;
gdouble x, y;
@ -8454,7 +8464,8 @@ convert_toplevel_coords_to_window (GdkWindow *window,
static GdkWindowObject *
pick_embedded_child (GdkWindowObject *window,
double x, double y)
gdouble x,
gdouble y)
{
GdkWindowObject *res;
@ -8468,7 +8479,8 @@ pick_embedded_child (GdkWindowObject *window,
GdkWindow *
_gdk_window_find_child_at (GdkWindow *window,
int x, int y)
int x,
int y)
{
GdkWindowObject *private, *sub;
double child_x, child_y;
@ -8507,12 +8519,13 @@ _gdk_window_find_child_at (GdkWindow *window,
GdkWindow *
_gdk_window_find_descendant_at (GdkWindow *toplevel,
double x, double y,
double *found_x,
double *found_y)
gdouble x,
gdouble y,
gdouble *found_x,
gdouble *found_y)
{
GdkWindowObject *private, *sub;
double child_x, child_y;
gdouble child_x, child_y;
GList *l;
gboolean found;