cha-gtk.html

gtk_text program sample&eg

            </p>
            <p>
              Once you have a <span class="STRUCTNAME">
              GtkWidget*</span> representing an object, you can
              manipulate the object using its methods. All GTK+
              widget functions begin with the name of the type they
              operate on, and accept a pointer to that type as the
              first argument. In the above code, <tt class=
              "FUNCTION">gtk_container_add()</tt> accepts a <span
              class="STRUCTNAME">GtkContainer*</span> as the first
              argument. The macro <tt class="FUNCTION">
              GTK_CONTAINER()</tt> casts the <span class=
              "STRUCTNAME">GtkWidget*</span>, and also performs a
              runtime type check. Casting is required because C
              does not understand the inheritance relationship.
            </p>
            <p>
              As you might imagine, <tt class="CLASSNAME">
              GtkButton</tt> and <tt class="CLASSNAME">
              GtkWindow</tt> are both subclasses of <tt class= 
              "CLASSNAME">GtkContainer</tt>. A <tt class=
              "CLASSNAME">GtkContainer</tt> can hold any other
              widget inside. The code creates a toplevel window,
              places a button inside it, and places a label (line
              of text) inside the button. Then it sets the window
              title, and adds a small cosmetic border around the
              button.
            </p>
          </div>
          <div class="SECT3">
            <h3 class="SECT3">
              <a name="Z44">Signals</a>
            </h3>
            <p>
              Next, you'll want to arrange to respond when users
              manipulate the widgets. In this simple application,
              there are two interesting things that can happen: the
              user can click the button, or close the window using
              a window manager decoration. Widgets (actually, all
              <span class="STRUCTNAME">GtkObject</span>s) emit <i
              class="FIRSTTERM">signals</i> when something
              interesting happens a program might want to respond
              to. To respond to a signal, you "connect a callback"
              to it---i.e., register a function to be called when
              the signal is emitted. Here's that code again:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_signal_connect(GTK_OBJECT(window),
                     "delete_event",
                     GTK_SIGNAL_FUNC(delete_event_cb),
                     NULL);

  gtk_signal_connect(GTK_OBJECT(button),
                     "clicked",
                     GTK_SIGNAL_FUNC(button_click_cb),
                     label);
&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <tt class="FUNCTION">gtk_signal_connect()</tt>
              specifies the <span class="STRUCTNAME">
              GtkObject</span> to monitor, which signal to connect
              to, the callback to connect, and finally a <span
              class="STRUCTNAME">user_data</span> argument---this
              is an arbitrary <span class="STRUCTNAME">
              gpointer</span> which will be passed to the callback.
              The macro <tt class="FUNCTION">GTK_SIGNAL_FUNC()</tt>
              casts the callback to a standard function signature;
              since callbacks have a variety of type signatures,
              the alternative would be dozens of <tt class=
              "FUNCTION">gtk_signal_connect()</tt> variants.
            </p>
            <p>
              GTK+ performs copious runtime sanity checking; the
              <tt class="FUNCTION">GTK_OBJECT()</tt> macro includes
              a runtime type check in addition to a C cast, and <tt
              class="FUNCTION">gtk_signal_connect()</tt> will
              verify that the object can actually emit the signal
              you've specified.
            </p>
          </div>
          <div class="SECT3">
            <h3 class="SECT3">
              <a name="Z45">Entering the Main Loop</a>
            </h3>
            <p>
              Once everything is set up, two steps remain: you need
              to show the window on the screen, and wait for user
              input.
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_widget_show_all(window);

  gtk_main();

  return 0;
&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <tt class="FUNCTION">gtk_widget_show_all()</tt>
              recursively calls <tt class="FUNCTION">
              gtk_widget_show()</tt> on a container and its
              children. The following code would have the same
              effect in this case:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_widget_show(label);
  gtk_widget_show(button);
  gtk_widget_show(window);&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              It's necessary to show each and every widget that you
              want to appear on the screen. The opposite operation
              is called <tt class="FUNCTION">
              gtk_widget_hide()</tt>; widgets start their life
              hidden, and can be re-hidden/re-shown any number of
              times. It's good practice to show all child widgets
              before showing the outermost container; otherwise,
              the user will see the container appear first,
              followed by its children. Widgets are not actually
              visible on the screen until their parent container is
              shown---the exception to the rule is <tt class= 
              "CLASSNAME">GtkWindow</tt>, since it has no parent.
            </p>
            <p>
              Once your widgets have been shown, you want to wait
              for the user to do something with them. <tt class= 
              "FUNCTION">gtk_main()</tt> enters the GTK+ main loop;
              the main loop is event-driven. That is, user actions
              trigger <i class="FIRSTTERM">events</i> which
              generally result in signals being emitted and your
              callbacks being called. <tt class="FUNCTION">
              gtk_main()</tt> blocks indefinitely, waiting for and
              responding to user input. The main loop is described
              in more detail in <a href="sec-mainloop.html">the
              section called <i>The Main Loop</i></a>. Events and
              their relation to the main loop are described in <a
              href="sec-gdkevent.html">the section called <i>
              Events</i> in the chapter called <i>GDK
              Basics</i></a>.
            </p>
          </div>
          <div class="SECT3">
            <h3 class="SECT3">
              <a name="Z46">More on Signals and Callbacks</a>
            </h3>
            <p>
              If either of the signals the program connects to is
              emitted, the corresponding callback is called. Our
              <span class="SYMBOL">"delete_event"</span> callback
              ends the <tt class="FUNCTION">gtk_main()</tt> event
              loop by calling <tt class="FUNCTION">
              gtk_main_quit()</tt>; this causes <tt class=
              "FUNCTION">gtk_main()</tt> to return, ending the
              program. The <span class="SYMBOL">"clicked"</span>
              callback replaces the text from the label with the
              same text in reverse. Notice that the label was
              passed to the callback as the <span class=
              "STRUCTNAME">user_data</span> parameter to <tt class= 
              "FUNCTION">gtk_signal_connect()</tt>.
            </p>
            <p>
              A common mistake is to assume that all signals use
              the same kind of callback---not true. Each signal
              requires a callback with a particular type signature
              and particular behavior. The <span class="SYMBOL">
              "clicked"</span> signal has a very common callback
              type; its callback receives a pointer to the widget
              emitting the signal and any <span class="STRUCTNAME">
              user_data</span> provided by the programmer. This
              callback <i class="EMPHASIS">must</i> return <span
              class="STRUCTNAME">void</span> or memory corruption
              is likely to occur.
            </p>
            <p>
              <span class="SYMBOL">"delete_event"</span>, on the
              other hand, is something of a special case. It
              accepts three arguments; the first and last are
              analagous to <span class="SYMBOL">"clicked"</span>,
              while the second is a pointer to the event which
              triggered the signal (<i class="FIRSTTERM">events</i>
              are messages from X to the application, reporting
              mouse movements, key presses, and the like). The
              <span class="SYMBOL">"delete_event"</span> callback
              returns a "magic" value---if <span class=
              "STRUCTNAME">FALSE</span> is returned, GTK+ will
              destroy the window; if <span class="STRUCTNAME">
              TRUE</span> is returned, GTK+ will do nothing. Return
              <span class="STRUCTNAME">TRUE</span> if you need to
              do something other than destroy the window; for
              example, you might want to warn the user about an
              unsaved document.
            </p>
            <p>
              Widget header files are the best quick reference for
              callback signatures. The "class structure" for the
              widget will have a space for a default signal
              handler; your handler should be modeled on the
              default one. For example, in <tt class="FILENAME">
              gtk/gtkbutton.h</tt> the <tt class="CLASSNAME">
              GtkButton</tt> class struct looks like this:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;struct _GtkButtonClass
{
  GtkBinClass        parent_class;
  
  void (* pressed)  (GtkButton *button);
  void (* released) (GtkButton *button);
  void (* clicked)  (GtkButton *button);
  void (* enter)    (GtkButton *button);
  void (* leave)    (GtkButton *button);
};&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <a href="cha-objects.html">the chapter called <i>The
              GTK+ Object and Type System</i></a> explains exactly
              what a class struct is for; for now, just pay
              attention to the function pointers, and note that
              they correspond to signals. To get from this:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  void (* clicked)  (GtkButton *button);&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              to this:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  static void button_click_cb(GtkWidget* w, gpointer data);&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              simply add a <span class="STRUCTNAME">gpointer
              data</span> to the class struct function's signature.
              In Hello, World I've also changed the type from <span
              class="STRUCTNAME">GtkButton*</span> to <span class= 
              "STRUCTNAME">GtkWidget*</span>; this is common, since
              it can be more convenient to have a <span class= 
              "STRUCTNAME">GtkWidget*</span>. The argument will
              always be the <tt class="CLASSNAME">GtkButton</tt>
              emitting the signal.
            </p>
            <p>
              Another example may be useful; here is <span class= 
              "SYMBOL">"delete_event"</span> from <tt class= 
              "FILENAME">gtk/gtkwidget.h</tt>:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;  gint (* delete_event)            (GtkWidget          *widget,
                                    GdkEventAny        *event);&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              and the callback from Hello, World:
            </p>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="PROGRAMLISTING">
&#13;static gint delete_event_cb(GtkWidget* w, GdkEventAny* e, gpointer data);&#13;
</pre>
                </td>
              </tr>
            </table>
            <p>
              That's all there is to it. You can write simple GTK+
              applications using only the information presented in
              this section. GTK+ and Gnome are powerful application
              development tools because you can think about real
              functionality, instead of struggling to get a window
              on the screen.
            </p>
          </div>
        </div>
      </div>
    </div>
    <div class="NAVFOOTER">
      <br>
      <br>
      <table width="100%" border="0" bgcolor="#ffffff" cellpadding= 
      "1" cellspacing="0">
        <tr>
          <td width="25%" bgcolor="#ffffff" align="left">
            <a href="z35.html"><font color="#0000ff" size="2"><b>
            &lt;&lt;&lt; Previous</b></font></a>
          </td>
          <td width="25%" colspan="2" bgcolor="#ffffff" align= 
          "center">
            <font color="#0000ff" size="2"><b><a href="ggad.html">
            <font color="#0000ff" size="2"><b>
            Home</b></font></a></b></font>
          </td>
          <td width="25%" bgcolor="#ffffff" align="right">
            <a href="sec-containers.html"><font color="#0000ff"
            size="2"><b>Next &gt;&gt;&gt;</b></font></a>
          </td>
        </tr>
        <tr>
          <td colspan="2" align="left">
            <font color="#000000" size="2"><b>Other
            Features</b></font>
          </td>
          <td colspan="2" align="right">
            <font color="#000000" size="2"><b>Containers And Widget
            Layout</b></font>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>