z57.html

gtk 开发手册和参考文档。 包括gtk glib gdk等

              If you add a reference to a widget, you are
              responsible for unreferencing the widget again when
              you're done with it.
            </p>
          </li>
        </ul>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="SEC-REALIZINGSHOWING">Realizing, Mapping, and
          Showing</a>
        </h2>
        <p>
          Fully understanding GTK+ requires some minimal
          understanding of the X Window System. This book assumes
          you have a user-level understanding---you know what an X
          server is, that X is network transparent, what a window
          manager does, and so on. A few more details are needed to
          write programs, however.
        </p>
        <p>
          One detail is particularly important: the X Window System
          maintains a tree of <i class="FIRSTTERM">windows</i>.
          "Window" in this sense refers to an X window, not a <tt
          class="CLASSNAME">GtkWindow</tt>---<tt class=
          "CLASSNAME">GtkWindow</tt> is a GTK+-specific concept, a
          widget that corresponds to an application's toplevel X
          window. An X window is not the user-visible concept
          "window" represented by <tt class="CLASSNAME">
          GtkWindow</tt>; rather, it's an abstraction used by the X
          server to partition the screen. The "background"
          displayed by your X server is the <i class="FIRSTTERM">
          root window</i>; the root window has no parent.
          Application windows are typically near-children of the
          root window; most window managers create a child of the
          root window to hold the window's titlebar and other
          decorations, and place the application window inside.
          Window managers have total control over application
          windows---they can reposition them, reparent them, and
          iconify them at will. Application windows can in turn
          contain subwindows, which are controlled by the
          application. Note that GTK+ uses the GDK library, rather
          than using X directly; in GDK, there is a thin X window
          wrapper called <span class="STRUCTNAME">GdkWindow</span>.
          Don't confuse <span class="STRUCTNAME">GdkWindow</span>
          and <tt class="CLASSNAME">GtkWindow</tt>.
        </p>
        <p>
          An X window, or a <span class="STRUCTNAME">
          GdkWindow</span>, gives the X server hints about the
          structure of the graphics being displayed. Since X is
          network transparent, this helps reduce network traffic.
          The X server knows how to show windows on the screen;
          hide them; move them around (keeping children in position
          relative to their parents); capture events such as mouse
          movements on a per-window basis; and so on. A <span
          class="STRUCTNAME">GdkWindow</span> is also the
          fundamental unit for drawing graphics---you can't draw to
          "the screen" as a whole, you must draw on a <span class= 
          "STRUCTNAME">GdkWindow</span>.
        </p>
        <p>
          Most GTK+ widgets have a corresponding <span class= 
          "STRUCTNAME">GdkWindow</span>. There are exceptions, such
          as <tt class="CLASSNAME">GtkLabel</tt>; these are
          referred to as "no window widgets," and are relatively
          lightweight. Widgets with no associated <span class= 
          "STRUCTNAME">GdkWindow</span> draw into their parent's
          <span class="STRUCTNAME">GdkWindow</span>. Some
          operations, such as capturing events, require a <span
          class="STRUCTNAME">GdkWindow</span>; thus they are
          impossible on no-window widgets.
        </p>
        <p>
          Widgets pass through a number of states related to their
          <span class="STRUCTNAME">GdkWindow</span>:
        </p>
        <ul>
          <li>
            <p>
              A widget is said to be <i class="FIRSTTERM">
              realized</i> if its corresponding <span class= 
              "STRUCTNAME">GdkWindow</span> has been created.
              Widgets are realized via <tt class="FUNCTION">
              gtk_widget_realize()</tt>, and unrealized via <tt
              class="FUNCTION">gtk_widget_unrealize()</tt>. Since
              an X window must have a parent, if a widget is
              realized its parent must also be. &#13;
            </p>
          </li>
          <li>
            <p>
              A widget is <i class="FIRSTTERM">mapped</i> if <tt
              class="FUNCTION">gdk_window_show()</tt> has been
              called on its <span class="STRUCTNAME">
              GdkWindow</span>. This means the server has been
              asked to display the window on the screen; obviously
              the <span class="STRUCTNAME">GdkWindow</span> must
              exist, implying that the widget is realized.&#13;
            </p>
          </li>
          <li>
            <p>
              A widget is <i class="FIRSTTERM">visible</i> if it
              will automatically be mapped when its parent is
              mapped. This means that <tt class="FUNCTION">
              gtk_widget_show()</tt> has been called on the widget.
              A widget can be rendered invisible by calling <tt
              class="FUNCTION">gtk_widget_hide()</tt>; this will
              either unschedule the pending map, or unmap the
              widget (hide its <span class="STRUCTNAME">
              GdkWindow</span>). Since toplevel widgets have no
              parent, they are mapped as soon as they are
              shown.&#13;
            </p>
          </li>
        </ul>
        <p>
          In typical user code, you only need to call <tt class= 
          "FUNCTION">gtk_widget_show()</tt>; this implies realizing
          and mapping the widget as soon as its parent is realized
          and mapped. It's important to understand that <tt class= 
          "FUNCTION">gtk_widget_show()</tt> has no immediate
          effect, it merely schedules the widget to be shown. This
          means you don't have to worry about showing widgets in
          any particular order; it also means that you can't
          immediately access the <span class="STRUCTNAME">
          GdkWindow</span> of a widget. Sometimes you need to
          access the <span class="STRUCTNAME">GdkWindow</span>; in
          those cases you'll want to manually call <tt class= 
          "FUNCTION">gtk_widget_realize()</tt> to create it. <tt
          class="FUNCTION">gtk_widget_realize()</tt> will also
          realize a widget's parents, if appropriate. It's uncommon
          to need <tt class="FUNCTION">gtk_widget_realize()</tt>;
          if you find that you do, perhaps you are approaching the
          problem incorrectly.
        </p>
        <p>
          Destroying a widget automatically reverses the entire
          sequence of events, recursively unrealizing the widget's
          children and the widget itself.
        </p>
        <p>
          <a href="z57.html#FL-SHOWREALIZE">Figure 23</a>
          summarizes the functions discussed in this section.
        </p>
        <div class="FIGURE">
          <a name="FL-SHOWREALIZE"></a>
          <div class="FUNCSYNOPSIS">
            <a name="FL-SHOWREALIZE.SYNOPSIS"></a>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;gtk/gtkwidget.h&gt;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_widget_realize</tt></code>(GtkWidget*
              <tt class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">
              gtk_widget_unrealize</tt></code>(GtkWidget* <tt
              class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_widget_map</tt></code>(GtkWidget* <tt
              class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_widget_unmap</tt></code>(GtkWidget*
              <tt class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_widget_show</tt></code>(GtkWidget* <tt
              class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_widget_hide</tt></code>(GtkWidget* <tt
              class="PARAMETER"><i>widget</i></tt>);</code>
            </p>
          </div>
          <p>
            <b>Figure 23. Showing/Realizing Widgets</b>
          </p>
        </div>
        <p>
          <a href="z57.html#ML-STATES">Figure 24</a> summarizes
          macros for querying the states discussed in this section.
        </p>
        <div class="FIGURE">
          <a name="ML-STATES"></a>
          <div class="FUNCSYNOPSIS">
            <a name="ML-STATES.SYNOPSIS"></a>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;gtk/gtkwidget.h&gt;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <code><code class="FUNCDEF"><tt class="FUNCTION">
              GTK_WIDGET_NO_WINDOW</tt></code>(<tt class=
              "PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF"><tt class="FUNCTION">
              GTK_WIDGET_REALIZED</tt></code>(<tt class=
              "PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF"><tt class="FUNCTION">
              GTK_WIDGET_MAPPED</tt></code>(<tt class=
              "PARAMETER"><i>widget</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF"><tt class="FUNCTION">
              GTK_WIDGET_VISIBLE</tt></code>(<tt class=
              "PARAMETER"><i>widget</i></tt>);</code>
            </p>
          </div>
          <p>
            <b>Figure 24. Widget Predicates</b>
          </p>
        </div>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="Z58">Other Widget Concepts</a>
        </h2>
        <p>
          This section describes a few other concepts associated
          with the <tt class="CLASSNAME">GtkWidget</tt> base class,
          including <i class="FIRSTTERM">sensitivity</i>, <i class= 
          "FIRSTTERM">focus</i>, and <i class="FIRSTTERM">widget
          states</i>.
        </p>
        <div class="SECT3">
          <h3 class="SECT3">
            <a name="SEC-SENSITIVITY">Sensitivity</a>
          </h3>
          <p>
            Widgets can be <i class="FIRSTTERM">sensitive</i> or <i
            class="FIRSTTERM">insensitive</i>; insensitive widgets
            do not respond to input. (On other platforms, this is