RubyGems - gdk3 - Versions diffs - 1.2.0-x86-mingw32 - Mend

gdk3 1.2.0-x86-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1337) hide show

data/vendor/local/share/gtk-doc/html/gtk3/ch26s02.html ADDED Viewed

@@ -0,0 +1,53 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Commands and Messages</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.0">
+<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
+<link rel="up" href="gtk-migrating-unique-GtkApplication.html" title="Migrating from libunique to GApplication or GtkApplication">
+<link rel="prev" href="gtk-migrating-unique-GtkApplication.html" title="Migrating from libunique to GApplication or GtkApplication">
+<link rel="next" href="gtk-migrating-smclient-GtkApplication.html" title="Migrating from EggSMClient to GtkApplication">
+<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="gtk-migrating-unique-GtkApplication.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="gtk-migrating-unique-GtkApplication.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GTK+ 3 Reference Manual</th>
+<td><a accesskey="n" href="gtk-migrating-smclient-GtkApplication.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="idm140520297137840"></a>Commands and Messages</h2></div></div></div>
+<p>
+      libunique lets you send messages with commands to a running
+      instance using <code class="function">unique_app_send_message()</code>. The commands can be either
+      predefined or custom. Some of the predefined libunique commands have
+      equivalents in GApplication. Instead of sending the <code class="literal">UNIQUE_ACTIVATE</code>
+      command, call <code class="function">g_application_activate()</code>, instead of sending the
+      <code class="literal">UNIQUE_OPEN</code> command, call <code class="function">g_application_open()</code>. The
+      <code class="literal">UNIQUE_NEW</code> and <code class="literal">UNIQUE_CLOSE</code> and user-defined commands don't
+      have direct replacement at this time.
+    </p>
+<p>
+      As a replacement for custom commands, GApplication implements the
+      <span class="type">GActionGroup</span> interface and lets you add a group of actions with
+      <code class="function">g_application_set_action_group()</code>. The actions can then be invoked,
+      either by using the D-Bus interface for <span class="type">GAction</span> directly, or by
+      calling <code class="function">g_action_group_activate_action()</code> from another instance of
+      the GApplication. The <span class="type">GApplication</span> documentation contains an
+      example for using GApplication with actions.
+    </p>
+<p>
+      For more complex needs, GApplication supports passing entire
+      commandlines to the running instance.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.18.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gtk3/ch28s02.html ADDED Viewed

@@ -0,0 +1,117 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GtkBox versus GtkGrid: sizing</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.0">
+<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
+<link rel="up" href="gtk-migrating-GtkGrid.html" title="Migrating from other containers to GtkGrid">
+<link rel="prev" href="gtk-migrating-GtkGrid.html" title="Migrating from other containers to GtkGrid">
+<link rel="next" href="ch28s03.html" title="GtkBox versus GtkGrid: spacing">
+<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="gtk-migrating-GtkGrid.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="gtk-migrating-GtkGrid.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GTK+ 3 Reference Manual</th>
+<td><a accesskey="n" href="ch28s03.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="idm140520312207808"></a>GtkBox versus GtkGrid: sizing</h2></div></div></div>
+<p>
+      When adding a child to a GtkBox, there are two hard-to-remember
+      parameters (child properties, more exactly) named expand and fill
+      that determine how the child size behaves in the main direction
+      of the box. If expand is set, the box allows the position occupied
+      by the child to grow when extra space is available. If fill is
+      also set, the extra space is allocated to the child widget itself.
+      Otherwise it is left 'free'.
+      There is no control about the 'minor' direction; children
+      are always given the full size in the minor direction.
+    </p>
+<img src="box-expand.png"><p>
+      GtkGrid does not have any custom child properties for controlling
+      size allocation to children. Instead, it fully supports the newly
+      introduced <a class="link" href="GtkWidget.html#GtkWidget--hexpand" title='The "hexpand" property'><span class="type">"hexpand"</span></a>, <a class="link" href="GtkWidget.html#GtkWidget--vexpand" title='The "vexpand" property'><span class="type">"vexpand"</span></a>, <a class="link" href="GtkWidget.html#GtkWidget--halign" title='The "halign" property'><span class="type">"halign"</span></a>
+      and <a class="link" href="GtkWidget.html#GtkWidget--valign" title='The "valign" property'><span class="type">"valign"</span></a> properties.
+    </p>
+<p>
+      The <a class="link" href="GtkWidget.html#GtkWidget--hexpand" title='The "hexpand" property'><span class="type">"hexpand"</span></a> and <a class="link" href="GtkWidget.html#GtkWidget--vexpand" title='The "vexpand" property'><span class="type">"vexpand"</span></a> properties operate
+      in a similar way to the expand child properties of <a class="link" href="GtkBox.html" title="GtkBox"><span class="type">GtkBox</span></a>. As soon
+      as a column contains a hexpanding child, GtkGrid allows the column
+      to grow when extra space is available (similar for rows and vexpand).
+      In contrast to GtkBox, all the extra space is always allocated
+      to the child widget, there are no 'free' areas.
+    </p>
+<p>
+      To replace the functionality of the fill child properties, you can
+      set the <a class="link" href="GtkWidget.html#GtkWidget--halign" title='The "halign" property'><span class="type">"halign"</span></a> and <a class="link" href="GtkWidget.html#GtkWidget--valign" title='The "valign" property'><span class="type">"valign"</span></a> properties. An
+      align value of <a class="link" href="GtkWidget.html#GTK-ALIGN-FILL:CAPS"><span class="type">GTK_ALIGN_FILL</span></a> has the same effect as setting fill
+      to <code class="literal">TRUE</code>, a value of <a class="link" href="GtkWidget.html#GTK-ALIGN-CENTER:CAPS"><span class="type">GTK_ALIGN_CENTER</span></a> has the same effect as setting
+      fill to <code class="literal">FALSE</code>. The image below shows the effect of various combinations
+      of halign and valign.
+    </p>
+<img src="widget-hvalign.png"><div class="example">
+<a name="idm140520312760752"></a><p class="title"><b>Example 130. Expansion and alignment</b></p>
+<div class="example-contents">
+<pre class="programlisting">
+  box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+  gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("One"), TRUE, FALSE, 0);
+  gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("Two"), TRUE, TRUE, 0);
+      </pre>
+<p>This can be done with <a class="link" href="GtkGrid.html" title="GtkGrid"><span class="type">GtkGrid</span></a> as follows:</p>
+<pre class="programlisting">
+  grid = gtk_grid_new ();
+  child1 = gtk_label_new ("One");
+  gtk_widget_set_hexpand (child1, TRUE);
+  gtk_widget_set_halign (child1, GTK_ALIGN_CENTER);
+  gtk_grid_attach (GTK_GRID (grid), child1, 0, 0, 1, 1);
+  child2 = gtk_label_new ("Two");
+  gtk_widget_set_hexpand (child2, TRUE);
+  gtk_widget_set_halign (child1, GTK_ALIGN_FILL);
+  gtk_grid_attach_next_to (GTK_GRID (grid), child2, child1, GTK_POS_RIGHT, 1, 1);
+      </pre>
+</div>
+</div>
+<br class="example-break"><p>
+      One difference between the new GtkWidget expand properties and
+      the GtkBox child property of the same name is that widget expandability
+      is 'inherited' from children. What this means is that a container
+      will become itself expanding as soon as it has
+      an expanding child. This is typically what you want, it lets
+      you e.g. mark the content pane of your application window as
+      expanding, and all the intermediate containers between the
+      content pane and the toplevel window will automatically do
+      the right thing. This automatism can be overridden at any
+      point by setting the expand flags on a container explicitly.
+    </p>
+<p>
+      Another difference between GtkBox and GtkGrid with respect to
+      expandability is when there are no expanding children at all.
+      In this case, GtkBox will forcibly expand all children whereas
+      GtkGrid will not. In practice, the effect of this is typically
+      that a grid will 'stick to the corner' when the toplevel
+      containing it is grown, instead of spreading out its children
+      over the entire area. The problem can be fixed by setting some
+      or all of the children to expand.
+    </p>
+<p>
+      When you set the <a class="link" href="GtkBox.html#GtkBox--homogeneous" title='The "homogeneous" property'><span class="type">"homogeneous"</span></a> property on a GtkBox,
+      it reserves the same space for all its children. GtkGrid does
+      this in a very similar way, with <a class="link" href="GtkGrid.html#GtkGrid--row-homogeneous" title='The "row-homogeneous" property'><span class="type">"row-homogeneous"</span></a> and
+      <a class="link" href="GtkGrid.html#GtkGrid--column-homogeneous" title='The "column-homogeneous" property'><span class="type">"column-homogeneous"</span></a> properties which control whether
+      all rows have the same height and whether all columns have
+      the same width.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.18.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gtk3/ch28s03.html ADDED Viewed

@@ -0,0 +1,70 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GtkBox versus GtkGrid: spacing</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.0">
+<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
+<link rel="up" href="gtk-migrating-GtkGrid.html" title="Migrating from other containers to GtkGrid">
+<link rel="prev" href="ch28s02.html" title="GtkBox versus GtkGrid: sizing">
+<link rel="next" href="gtk-migrating-checklist.html" title="Migration Details Checklist">
+<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="ch28s02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="gtk-migrating-GtkGrid.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GTK+ 3 Reference Manual</th>
+<td><a accesskey="n" href="gtk-migrating-checklist.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="idm140520307922016"></a>GtkBox versus GtkGrid: spacing</h2></div></div></div>
+<p>
+      With GtkBox, you have to specify the <a class="link" href="GtkBox.html#GtkBox--spacing" title='The "spacing" property'><span class="type">"spacing"</span></a> when
+      you construct it. This property specifies the space that
+      separates the children from each other. Additionally, you
+      can specify extra space to put around each child individually,
+      using the <span class="type">"padding"</span> child property.
+    </p>
+<p>
+      GtkGrid is very similar when it comes to spacing between the
+      children, except that it has two separate properties,
+      <a class="link" href="GtkGrid.html#GtkGrid--row-spacing" title='The "row-spacing" property'><span class="type">"row-spacing"</span></a> and <a class="link" href="GtkGrid.html#GtkGrid--column-spacing" title='The "column-spacing" property'><span class="type">"column-spacing"</span></a>, for the
+      space to leave between rows and columns. Note that row-spacing
+      is the space <span class="emphasis"><em>between</em></span> rows, not inside
+      a row. So, if you doing a horizontal layout, you need to set
+      <a class="link" href="GtkGrid.html#GtkGrid--column-spacing" title='The "column-spacing" property'><span class="type">"column-spacing"</span></a>.
+    </p>
+<p>
+      GtkGrid doesn't have any custom child properties to specify
+      per-child padding; instead you can use the <a class="link" href="GtkWidget.html#GtkWidget--margin" title='The "margin" property'><span class="type">"margin"</span></a>
+      property. You can also set different padding on each side with
+      the  <a class="link" href="GtkWidget.html#GtkWidget--margin-left" title='The "margin-left" property'><span class="type">"margin-left"</span></a>, <a class="link" href="GtkWidget.html#GtkWidget--margin-right" title='The "margin-right" property'><span class="type">"margin-right"</span></a>,
+      <a class="link" href="GtkWidget.html#GtkWidget--margin-top" title='The "margin-top" property'><span class="type">"margin-top"</span></a> and <a class="link" href="GtkWidget.html#GtkWidget--margin-bottom" title='The "margin-bottom" property'><span class="type">"margin-bottom"</span></a> properties.
+    </p>
+<div class="example">
+<a name="idm140520306531152"></a><p class="title"><b>Example 131. Spacing in boxes</b></p>
+<div class="example-contents">
+<pre class="programlisting">
+         box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 6);
+         gtk_box_pack_start (GTK_BOX (box), child, FALSE, FALSE, 12);
+      </pre>
+<p>This can be done with <a class="link" href="GtkGrid.html" title="GtkGrid"><span class="type">GtkGrid</span></a> as follows:</p>
+<pre class="programlisting">
+         grid = gtk_grid_new ();
+         gtk_grid_set_row_spacing (GTK_GRID (grid), 6);
+         g_object_set (child, "margin", 12, NULL);
+         gtk_grid_attach (GTK_GRID (box), child, 0, 0, 1, 1);
+      </pre>
+</div>
+</div>
+<br class="example-break">
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.18.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gtk3/chap-drawing-model.html ADDED Viewed

@@ -0,0 +1,461 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>The GTK+ Drawing Model</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.0">
+<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
+<link rel="up" href="gtk.html" title="Part I. GTK+ Overview">
+<link rel="prev" href="gtk-question-index.html" title="Common Questions">
+<link rel="next" href="gtkbase.html" title="Part II. GTK+ Core Reference">
+<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="gtk-question-index.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="gtk.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GTK+ 3 Reference Manual</th>
+<td><a accesskey="n" href="gtkbase.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="refentry">
+<a name="chap-drawing-model"></a><div class="titlepage"></div>
+<div class="refnamediv"><table width="100%"><tr>
+<td valign="top">
+<h2><span class="refentrytitle">The GTK+ Drawing Model</span></h2>
+<p>The GTK+ Drawing Model —
+    The GTK+ drawing model in detail
+</p>
+</td>
+<td valign="top" align="right"></td>
+</tr></table></div>
+<div class="refsect1">
+<a name="drawing-overview"></a><h2>Overview of the drawing model</h2>
+<p>
+      This chapter describes the GTK+ drawing model in detail.  If you
+      are interested in the procedure which GTK+ follows to draw its
+      widgets and windows, you should read this chapter; this will be
+      useful to know if you decide to implement your own widgets.  This
+      chapter will also clarify the reasons behind the ways certain
+      things are done in GTK+; for example, why you cannot change the
+      background color of all widgets with the same method.
+    </p>
+<p>
+      Programs that run in a windowing system generally create
+      rectangular regions in the screen called
+      <em class="firstterm">windows</em>.  Traditional windowing systems
+      do not automatically save the graphical content of windows, and
+      instead ask client programs to repaint those windows whenever it
+      is needed.  For example, if a window that is stacked below other
+      windows gets raised to the top, then a client program has to
+      repaint the area that was previously obscured.  When the
+      windowing system asks a client program to redraw part of a
+      window, it sends an <em class="firstterm">exposure event</em> to the
+      program for that window.
+    </p>
+<p>
+      Here, "windows" means "rectangular regions with automatic
+      clipping", instead of "toplevel application windows".  Most
+      windowing systems support nested windows, where the contents of
+      child windows get clipped by the boundaries of their parents.
+      Although GTK+ and GDK in particular may run on a windowing
+      system with no such notion of nested windows, GDK presents the
+      illusion of being under such a system.  A toplevel window may
+      contain many subwindows and sub-subwindows, for example, one for
+      the menu bar, one for the document area, one for each scrollbar,
+      and one for the status bar.  In addition, controls that receive
+      user input, such as clickable buttons, are likely to have their
+      own subwindows as well.
+    </p>
+<p>
+      Generally, the drawing cycle begins when GTK+ receives an
+      exposure event from the underlying windowing system:  if the
+      user drags a window over another one, the windowing system will
+      tell the underlying window that it needs to repaint itself.  The
+      drawing cycle can also be initiated when a widget itself decides
+      that it needs to update its display.  For example, when the user
+      types a character in a <a class="link" href="GtkEntry.html" title="GtkEntry"><code class="classname">GtkEntry</code></a>
+      widget, the entry asks GTK+ to queue a redraw operation for
+      itself.
+    </p>
+<p>
+      The following sections describe how GTK+ decides which widgets
+      need to be repainted, and how widgets work internally in terms
+      of the resources they use from the windowing system.
+    </p>
+<p>
+      A <a href="../gdk3/gdk3-Windows.html#GdkWindow"><code class="classname">GdkWindow</code></a>
+      represents a window from the underlying windowing system on which GTK+
+      is running.  For example, on X11 it corresponds to a
+      <span class="type">Window</span>; on Win32, it corresponds to a <span class="type">HANDLE</span>.
+      The windowing system generates events for these windows.  The GDK
+      interface to the windowing system translates such native events into
+      <a href="../gdk3/gdk3-Event-Structures.html#GdkEvent"><span class="structname">GdkEvent</span></a>
+      structures and sends them on to the GTK layer.  In turn, the GTK layer
+      finds the widget that corresponds to a particular
+      <code class="classname">GdkWindow</code> and emits the corresponding event
+      signals on that widget.
+    </p>
+<div class="refsect2">
+<a name="emission%20of%20the%20draw%20event"></a><h3>Emission of the draw event</h3>
+<p>
+        When the program needs to redraw a region of a
+        <code class="classname">GdkWindow</code>, generates an event of
+        type <code class="constant">GDK_EVENT_EXPOSE</code>
+        for that window, specifying the region to redraw in the process.
+      </p>
+<p>
+        When generating the event, GDK also sets up double buffering to
+        avoid the flickering that would result from each widget drawing
+        itself in turn.  <a class="xref" href="chap-drawing-model.html#double-buffering" title="Double buffering">the section called “Double buffering”</a> describes
+        the double buffering mechanism in detail.
+      </p>
+<p>
+        When the GTK+ widget layer receives the event, it finds the widget that
+        corresponds to the window, and causes it to render itself using the
+        widget's #GtkWidget::draw signal. For this purpose it creates a
+        cairo context. It then clips the context
+        to the area that needs to be drawn. This makes sure that the minimal
+        amount of work is done if only a small part of the widget needs to be
+        repainted. After translating the context so that its (0, 0) coordinate
+        corresponds to the top left corner of the widget, it effectively calls
+        the widget's <code class="function">gtk_widget_draw</code> function.
+      </p>
+<p>
+        <code class="function">gtk_widget_draw</code> takes care of drawing the widget
+        to the cairo context. It first checks that the widget actually needs to
+        be drawn. Widgets might for example be empty or outside of the cairo
+        context's clipped area, which would make drawing them not do anything.
+        Usually they will need to be drawn. In this case, the context will be
+        clipped to the widget's allocated size and the
+        draw signal will be emitted on
+        the widget which will finally draw the widget.
+      </p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="window-no-window-widgets"></a><h3>Window and no-window widgets</h3>
+<p>
+	In principle, each widget could have a
+	<code class="classname">GdkWindow</code> of its own.  With such a
+	scheme, the drawing cycle would be trivial:  when GDK notifies
+	the GTK layer about an exposure event for a
+	<code class="classname">GdkWindow</code>, the GTK layer would simply
+	emit the #GtkWidget::draw signal for that widget.  The signal
+	handler would subsequently repaint the widget.  No further
+	work would be necessary; the windowing system would generate
+	exposure events for each window that needs it, and then each
+	corresponding widget would draw itself in turn.
+      </p>
+<p>
+	However, in practice it is convenient to have widgets which do
+	not have a <code class="classname">GdkWindow</code> of their own, but
+	rather share the one from their parent widget.  Such widgets
+	have called <code class="function">gtk_widget_set_has_window</code> to
+	disable it; this can be tested easily with the <a class="link" href="GtkWidget.html#gtk-widget-get-has-window" title="gtk_widget_get_has_window ()"><code class="function">gtk_widget_get_has_window()</code></a>
+	function.  As such, these are called <em class="firstterm">no-window
+	widgets</em>.
+      </p>
+<p>
+	No-window widgets are useful for various reasons:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem">
+<p>
+	    Some widgets may want the parent's background to show through, even
+	    when they draw on parts of it.  For example, consider a theme that
+	    uses textured backgrounds, such as gradients or repeating
+	    patterns.  If each widget had its own window, and in turn its own
+	    gradient background, labels would look bad because there would be a
+	    visible break with respect to their surroundings.  <a class="xref" href="chap-drawing-model.html#figure-windowed-label" title="Figure 1. Windowed label vs. no-window label">Figure 1, “Windowed label vs. no-window label”</a> shows this undesirable effect.
+	  </p>
+<div class="figure">
+<a name="figure-windowed-label"></a><p class="title"><b>Figure 1. Windowed label vs. no-window label</b></p>
+<div class="figure-contents"><div><img src="figure-windowed-label.png" alt="Windowed label vs. no-window label"></div></div>
+</div>
+<br class="figure-break">
+</li>
+<li class="listitem"><p>
+	    Reducing the number of windows creates less traffic between GTK+ and
+	    the underlying windowing system, especially when getting events.
+	  </p></li>
+</ul></div>
+<p>
+	On the other hand, widgets that would benefit from having a "hard"
+	clipping region may find it more convenient to create their own
+	windows.  Also, widgets which want to receive events resulting from
+	user interaction may find it convenient to use windows of their own as
+	well.  Widgets may have more than one window if they want to
+	define different regions for capturing events.
+      </p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="hierarchical-drawing"></a><h3>Hierarchical drawing</h3>
+<p>
+	When the GTK layer receives an exposure event from GDK, it
+	finds the widget that corresponds to the window which received
+	the event.  By definition, this corresponds to a widget that
+	has the <code class="constant">GTK_NO_WINDOW</code> flag turned
+	<span class="emphasis"><em>off</em></span> (otherwise, the widget wouldn't own
+	the window!).  First this widget paints its background, and
+	then, if it is a container widget, it tells each of its
+	<code class="constant">GTK_NO_WINDOW</code> children to paint
+	themselves.  This process is applied recursively for all the
+	<code class="constant">GTK_NO_WINDOW</code> descendants of the original
+	widget.
+      </p>
+<p>
+	Note that this process does not get propagated to widgets
+	which have windows of their own, that is, to widgets which
+	have the <code class="constant">GTK_NO_WINDOW</code> flag turned off.
+	If such widgets require redrawing, then the windowing system
+	will already have sent exposure events to their corresponding
+	windows.  As such, there is no need to
+	<em class="firstterm">propagate</em> the exposure to them on the
+	GTK+ side.
+      </p>
+<p>
+	<a class="xref" href="chap-drawing-model.html#figure-hierarchical-drawing" title="Figure 2. Hierarchical drawing order">Figure 2, “Hierarchical drawing order”</a> shows how a simple toplevel window would
+	paint itself when it contains only <code class="constant">GTK_NO_WINDOW</code> descendants:
+	</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>
+	      The outermost, thick rectangle is a toplevel <a class="link" href="GtkWindow.html" title="GtkWindow"><code class="classname">GtkWindow</code></a>,
+	      which is not a <code class="constant">GTK_NO_WINDOW</code> widget —
+	      as such, it does receive its exposure event as it comes from GDK.
+	      First the <code class="classname">GtkWindow</code> would paint its own
+	      background.  Then, it would ask its only child to paint itself,
+	      numbered 2.
+	    </p></li>
+<li class="listitem"><p>
+	      The dotted rectangle represents a <a class="link" href="GtkVBox.html" title="GtkVBox"><code class="classname">GtkVBox</code></a>, which
+	      has been made the sole child of the
+	      <code class="classname">GtkWindow</code>.  Boxes are just layout
+	      containers that do not paint anything by themselves, so this
+	      <code class="classname">GtkVBox</code> would draw nothing, but rather ask
+	      its children to draw themselves.  The children are numbered 3 and
+	      6.
+	    </p></li>
+<li class="listitem"><p>
+	      The thin rectangle is a <a class="link" href="GtkFrame.html" title="GtkFrame"><code class="classname">GtkFrame</code></a>,
+	      which has two children:  a label for the frame, numbered 4, and
+	      another label inside, numbered 5.  First the frame would draw its
+	      own beveled box, then ask the frame label and its internal child to
+	      draw themselves.
+	    </p></li>
+<li class="listitem"><p>
+	      The frame label has no children, so it just draws its text:  "Frame Label".
+	    </p></li>
+<li class="listitem"><p>
+	      The internal label has no children, so it just draws its text:  "This
+	      is some text inside the frame!".
+	    </p></li>
+<li class="listitem"><p>
+	      The dotted rectangle represents a <a class="link" href="GtkHBox.html" title="GtkHBox"><code class="classname">GtkHBox</code></a>.  Again,
+	      this does not draw anything by itself, but rather asks its children
+	      to draw themselves.  The children are numbered 7 and 9.
+	    </p></li>
+<li class="listitem"><p>
+	      The thin rectangle is a <a class="link" href="GtkButton.html" title="GtkButton"><code class="classname">GtkButton</code></a> with
+	      a single child, numbered 8.  First the button would draw its
+	      beveled box, and then it would ask its child to draw itself.
+	    </p></li>
+<li class="listitem"><p>
+	      This is a text label which has no children, so it just draws its
+	      own text:  "Cancel".
+	    </p></li>
+<li class="listitem"><p>
+	      Similar to number 7, this is a button with a single child, numbered
+	      10.  First the button would draw its beveled box, and then it would
+	      ask its child to draw itself.
+	    </p></li>
+<li class="listitem"><p>
+	      Similar to number 8, this is a text label which has no children,
+	      so it just draws its own text:  "OK".
+	    </p></li>
+</ol></div>
+<p>
+      </p>
+<div class="figure">
+<a name="figure-hierarchical-drawing"></a><p class="title"><b>Figure 2. Hierarchical drawing order</b></p>
+<div class="figure-contents"><div><img src="figure-hierarchical-drawing.png" alt="Hierarchical drawing order"></div></div>
+</div>
+<br class="figure-break">
+</div>
+</div>
+<div class="refsect1">
+<a name="double-buffering"></a><h2>Double buffering</h2>
+<p>
+      When the GTK layer receives an exposure event from GDK, it first finds
+      the <code class="literal">!<code class="constant">GTK_NO_WINDOW</code></code> widget that
+      corresponds to the event's window.  Then, it emits the
+      #GtkWidget::draw signal for that
+      widget.  As described above, that widget will first draw its background,
+      and then ask each of its <code class="constant">GTK_NO_WINDOW</code> children to
+      draw themselves.
+    </p>
+<p>
+      If each of the drawing calls made by each subwidget's
+      <code class="literal">draw</code> handler were sent directly to the
+      windowing system, flicker could result.  This is because areas may get
+      redrawn repeatedly:  the background, then decorative frames, then text
+      labels, etc.  To avoid flicker, GTK+ employs a <em class="firstterm">double
+	buffering</em> system at the GDK level.  Widgets normally don't
+      know that they are drawing to an off-screen buffer; they just issue their
+      normal drawing commands, and the buffer gets sent to the windowing system
+      when all drawing operations are done.
+    </p>
+<p>
+      Two basic functions in GDK form the core of the double-buffering
+      mechanism:  <code class="function">gdk_window_begin_paint_region()</code>
+      and <code class="function">gdk_window_end_paint()</code>.
+      The first function tells a <code class="classname">GdkWindow</code> to
+      create a temporary off-screen buffer for drawing.  All
+      subsequent drawing operations to this window get automatically
+      redirected to that buffer.  The second function actually paints
+      the buffer onto the on-screen window, and frees the buffer.
+    </p>
+<div class="refsect2">
+<a name="automatic-double-buffering"></a><h3>Automatic double buffering</h3>
+<p>
+	It would be inconvenient for all widgets to call
+	<code class="function">gdk_window_begin_paint_region()</code> and
+	<code class="function">gdk_window_end_paint()</code> at the beginning
+	and end of their draw handlers.
+      </p>
+<p>
+	To make this easier, most GTK+ widgets have the
+	<code class="constant">GTK_DOUBLE_BUFFERED</code> <a href="http://library.gnome.org/devel/gtk3/GtkWidget.html#GtkWidgetFlags">widget flag</a> turned on by
+	default.  When GTK+ encounters such a widget, it automatically
+	calls <code class="function">gdk_window_begin_paint_region()</code>
+	before emitting the #GtkWidget::draw signal for the widget, and
+	then it calls <code class="function">gdk_window_end_paint()</code>
+	after the signal has been emitted.  This is convenient for
+	most widgets, as they do not need to worry about creating
+	their own temporary drawing buffers or about calling those
+	functions.
+      </p>
+<p>
+	However, some widgets may prefer to disable this kind of
+	automatic double buffering and do things on their own.  To do
+        this, call the
+        <code class="function">gtk_widget_set_double_buffered()</code> function
+	in your widget's constructor.
+      </p>
+<div class="example">
+<a name="disabling-double-buffering"></a><p class="title"><b>Example 5. Disabling automatic double buffering</b></p>
+<div class="example-contents">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
+<span class="function">my_widget_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">widget</span><span class="symbol">)</span>
+<span class="cbracket">{</span>
+<span class="normal">  </span><span class="symbol">...</span>
+<span class="normal">  </span><span class="function"><a href="GtkWidget.html#gtk-widget-set-double-buffered">gtk_widget_set_double_buffered</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">,</span><span class="normal"> FALSE</span><span class="symbol">);</span>
+<span class="normal">  </span><span class="symbol">...</span>
+<span class="cbracket">}</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+</div>
+<br class="example-break"><p>
+	When is it convenient to disable double buffering?  Generally,
+	this is the case only if your widget gets drawn in such a way
+	that the different drawing operations do not overlap each
+	other.  For example, this may be the case for a simple image
+	viewer:  it can just draw the image in a single operation.
+	This would <span class="emphasis"><em>not</em></span> be the case with a word
+	processor, since it will need to draw and over-draw the page's
+	background, then the background for highlighted text, and then
+	the text itself.
+      </p>
+<p>
+	Even if you turn off double buffering on a widget, you
+	can still call
+	<code class="function">gdk_window_begin_paint_region()</code> and
+	<code class="function">gdk_window_end_paint()</code> by hand to use
+	temporary drawing buffers.
+      </p>
+</div>
+</div>
+<div class="refsect1">
+<a name="app-paintable-widgets"></a><h2>App-paintable widgets</h2>
+<p>
+      Generally, applications use the pre-defined widgets in GTK+ and
+      they do not draw extra things on top of them (the exception
+      being <code class="classname">GtkDrawingArea</code>).  However,
+      applications may sometimes find it convenient to draw directly
+      on certain widgets like toplevel windows or event boxes.  When
+      this is the case, GTK+ needs to be told not to overwrite your
+      drawing afterwards, when the window gets to drawing its default
+      contents.
+    </p>
+<p>
+      <code class="classname">GtkWindow</code> and
+      <code class="classname">GtkEventBox</code> are the two widgets that allow
+      turning off drawing of default contents by calling
+      <code class="function">gtk_widget_set_app_paintable()</code>. If you call
+      this function, they will not draw their contents and let you do
+      it instead.
+    </p>
+<p>
+      Since the #GtkWidget::draw signal runs user-connected handlers
+      <span class="emphasis"><em>before</em></span> the widget's default handler, what
+      usually happens is this:
+    </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>
+	  Your own draw handler gets run.  It paints something
+	  on the window or the event box.
+	</p></li>
+<li class="listitem"><p>
+	  The widget's default draw handler gets run.  If
+          <code class="function">gtk_widget_set_app_paintable()</code> has not
+          been called to turn off widget drawing (this
+	  is the default), <span class="emphasis"><em>your drawing will be
+            overwritten</em></span>.  An app paintable widget will not
+          draw its default contents however and preserve your drawing
+          instead.
+	</p></li>
+<li class="listitem"><p>
+	  The draw handler for the parent class gets run.
+	  Since both <code class="classname">GtkWindow</code> and
+	  <code class="classname">GtkEventBox</code> are descendants of
+	  <code class="classname">GtkContainer</code>, their no-window
+	  children will be asked to draw themselves recursively, as
+	  described in <a class="xref" href="chap-drawing-model.html#hierarchical-drawing" title="Hierarchical drawing">the section called “Hierarchical drawing”</a>.
+	</p></li>
+</ol></div>
+<p><b>Summary of app-paintable widgets. </b>
+        Call <code class="function">gtk_widget_set_app_paintable()</code> if you
+	intend to draw your own content directly on a
+	<code class="classname">GtkWindow</code> and
+	<code class="classname">GtkEventBox</code>.  You seldom need to draw
+	on top of other widgets, and
+	<code class="classname">GtkDrawingArea</code> ignores this flag, as it
+	<span class="emphasis"><em>is</em></span> intended to be drawn on.
+      </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.18.1</div>
+</body>
+</html>