GTK_TYPE_BOOL,
  GTK_TYPE_INT,
  GTK_TYPE_UINT,
  GTK_TYPE_LONG,
  GTK_TYPE_ULONG,
  GTK_TYPE_FLOAT,
  GTK_TYPE_DOUBLE,
  GTK_TYPE_STRING,
  GTK_TYPE_ENUM,
  GTK_TYPE_FLAGS,
  GTK_TYPE_BOXED,
  GTK_TYPE_FOREIGN,
  GTK_TYPE_CALLBACK,
  GTK_TYPE_ARGS,

  GTK_TYPE_POINTER,

  /* it'd be great if the next two could be removed eventually */
  GTK_TYPE_SIGNAL,
  GTK_TYPE_C_CALLBACK,

  GTK_TYPE_OBJECT

} GtkFundamentalType;
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>gtk_signal_new()</CODE> returns a unique integer identifier for the
signal, that we store in the <CODE>tictactoe_signals</CODE> array, which we
index using an enumeration. (Conventionally, the enumeration elements
are the signal name, uppercased, but here there would be a conflict
with the <CODE>TICTACTOE()</CODE> macro, so we called it <CODE>TICTACTOE_SIGNAL</CODE>
instead.
<P>After creating our signals, we need to tell GTK to associate our
signals with the Tictactoe class. We do that by calling
<CODE>gtk_object_class_add_signals()</CODE>. We then set the pointer which
points to the default handler for the "tictactoe" signal to NULL,
indicating that there is no default action.
<P>
<H3>The <CODE>_init()</CODE> function.</H3>

<P>Each widget class also needs a function to initialize the object
structure. Usually, this function has the fairly limited role of
setting the fields of the structure to default values. For composite
widgets, however, this function also creates the component widgets.
<P>
<BLOCKQUOTE><CODE>
<PRE>
static void
tictactoe_init (Tictactoe *ttt)
{
  GtkWidget *table;
  gint i,j;
  
  table = gtk_table_new (3, 3, TRUE);
  gtk_container_add (GTK_CONTAINER(ttt), table);
  gtk_widget_show (table);

  for (i=0;i&lt;3; i++)
    for (j=0;j&lt;3; j++)
      {
        ttt->buttons[i][j] = gtk_toggle_button_new ();
        gtk_table_attach_defaults (GTK_TABLE(table), ttt->buttons[i][j], 
                                   i, i+1, j, j+1);
        gtk_signal_connect (GTK_OBJECT (ttt->buttons[i][j]), "toggled",
                            GTK_SIGNAL_FUNC (tictactoe_toggle), ttt);
        gtk_widget_set_usize (ttt->buttons[i][j], 20, 20);
        gtk_widget_show (ttt->buttons[i][j]);
      }
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>And the rest...</H3>

<P>There is one more function that every widget (except for base widget
types like Bin that cannot be instantiated) needs to have - the
function that the user calls to create an object of that type. This is
conventionally called <CODE>WIDGETNAME_new()</CODE>. In some
widgets, though not for the Tictactoe widgets, this function takes
arguments, and does some setup based on the arguments. The other two
functions are specific to the Tictactoe widget. 
<P><CODE>tictactoe_clear()</CODE> is a public function that resets all the
buttons in the widget to the up position. Note the use of
<CODE>gtk_signal_handler_block_by_data()</CODE> to keep our signal handler for
button toggles from being triggered unnecessarily.
<P><CODE>tictactoe_toggle()</CODE> is the signal handler that is invoked when the
user clicks on a button. It checks to see if there are any winning
combinations that involve the toggled button, and if so, emits
the "tictactoe" signal.
<P>
<BLOCKQUOTE><CODE>
<PRE>
  
GtkWidget*
tictactoe_new ()
{
  return GTK_WIDGET ( gtk_type_new (tictactoe_get_type ()));
}

void           
tictactoe_clear (Tictactoe *ttt)
{
  int i,j;

  for (i=0;i&lt;3;i++)
    for (j=0;j&lt;3;j++)
      {
        gtk_signal_handler_block_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt);
        gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (ttt->buttons[i][j]),
                                     FALSE);
        gtk_signal_handler_unblock_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt);
      }
}

static void
tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt)
{
  int i,k;

  static int rwins[8][3] = { { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 },
                             { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 },
                             { 0, 1, 2 }, { 0, 1, 2 } };
  static int cwins[8][3] = { { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 },
                             { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 },
                             { 0, 1, 2 }, { 2, 1, 0 } };

  int success, found;

  for (k=0; k&lt;8; k++)
    {
      success = TRUE;
      found = FALSE;

      for (i=0;i&lt;3;i++)
        {
          success = success &amp;&amp; 
            GTK_TOGGLE_BUTTON(ttt->buttons[rwins[k][i]][cwins[k][i]])->active;
          found = found ||
            ttt->buttons[rwins[k][i]][cwins[k][i]] == widget;
        }
      
      if (success &amp;&amp; found)
        {
          gtk_signal_emit (GTK_OBJECT (ttt), 
                           tictactoe_signals[TICTACTOE_SIGNAL]);
          break;
        }
    }
}
</PRE>
</CODE></BLOCKQUOTE>
<P>And finally, an example program using our Tictactoe widget:
<P>
<BLOCKQUOTE><CODE>
<PRE>
#include &lt;gtk/gtk.h>
#include "tictactoe.h"

/* Invoked when a row, column or diagonal is completed */
void
win (GtkWidget *widget, gpointer data)
{
  g_print ("Yay!\n");
  tictactoe_clear (TICTACTOE (widget));
}

int 
main (int argc, char *argv[])
{
  GtkWidget *window;
  GtkWidget *ttt;
  
  gtk_init (&amp;argc, &amp;argv);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  
  gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame");
  
  gtk_signal_connect (GTK_OBJECT (window), "destroy",
                      GTK_SIGNAL_FUNC (gtk_exit), NULL);
  
  gtk_container_set_border_width (GTK_CONTAINER (window), 10);

  /* Create a new Tictactoe widget */
  ttt = tictactoe_new ();
  gtk_container_add (GTK_CONTAINER (window), ttt);
  gtk_widget_show (ttt);

  /* And attach to its "tictactoe" signal */
  gtk_signal_connect (GTK_OBJECT (ttt), "tictactoe",
                      GTK_SIGNAL_FUNC (win), NULL);

  gtk_widget_show (window);
  
  gtk_main ();
  
  return 0;
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss22.4">22.4 Creating a widget from scratch.</A>
</H2>

<H3>Introduction</H3>

<P>In this section, we'll learn more about how widgets display themselves
on the screen and interact with events. As an example of this, we'll
create an analog dial widget with a pointer that the user can drag to
set the value.
<P>
<H3>Displaying a widget on the screen</H3>

<P>There are several steps that are involved in displaying on the screen.
After the widget is created with a call to <CODE>WIDGETNAME_new()</CODE>,
several more functions are needed:
<P>
<UL>
<LI> <CODE>WIDGETNAME_realize()</CODE> is responsible for creating an X
window for the widget if it has one.</LI>
<LI> <CODE>WIDGETNAME_map()</CODE> is invoked after the user calls
<CODE>gtk_widget_show()</CODE>. It is responsible for making sure the widget
is actually drawn on the screen (<EM>mapped</EM>). For a container class,
it must also make calls to <CODE>map()</CODE>> functions of any child widgets.</LI>
<LI> <CODE>WIDGETNAME_draw()</CODE> is invoked when <CODE>gtk_widget_draw()</CODE>
is called for the widget or one of its ancestors. It makes the actual
calls to the drawing functions to draw the widget on the screen. For
container widgets, this function must make calls to
<CODE>gtk_widget_draw()</CODE> for its child widgets.</LI>
<LI> <CODE>WIDGETNAME_expose()</CODE> is a handler for expose events for the
widget. It makes the necessary calls to the drawing functions to draw
the exposed portion on the screen. For container widgets, this
function must generate expose events for its child widgets which don't
have their own windows. (If they have their own windows, then X will
generate the necessary expose events.)</LI>
</UL>
<P>You might notice that the last two functions are quite similar - each
is responsible for drawing the widget on the screen. In fact many
types of widgets don't really care about the difference between the
two. The default <CODE>draw()</CODE> function in the widget class simply
generates a synthetic expose event for the redrawn area. However, some
types of widgets can save work by distinguishing between the two
functions. For instance, if a widget has multiple X windows, then
since expose events identify the exposed window, it can redraw only
the affected window, which is not possible for calls to <CODE>draw()</CODE>.
<P>Container widgets, even if they don't care about the difference for
themselves, can't simply use the default <CODE>draw()</CODE> function because
their child widgets might care about the difference. However,
it would be wasteful to duplicate the drawing code between the two
functions. The convention is that such widgets have a function called
<CODE>WIDGETNAME_paint()</CODE> that does the actual work of drawing the
widget, that is then called by the <CODE>draw()</CODE> and <CODE>expose()</CODE>
functions.
<P>In our example approach, since the dial widget is not a container
widget, and only has a single window, we can take the simplest
approach and use the default <CODE>draw()</CODE> function and only implement
an <CODE>expose()</CODE> function.
<P>
<H3>The origins of the Dial Widget</H3>

<P>Just as all land animals are just variants on the first amphibian that
crawled up out of the mud, GTK widgets tend to start off as variants
of some other, previously written widget. Thus, although this section
is entitled "Creating a Widget from Scratch", the Dial widget really
began with the source code for the Range widget. This was picked as a
starting point because it would be nice if our Dial had the same
interface as the Scale widgets which are just specialized descendants
of the Range widget. So, though the source code is presented below in
finished form, it should not be implied that it was written, <EM>ab
initio</EM> in this fashion. Also, if you aren't yet familiar with
how scale widgets work from the application writer's point of view, it
would be a good idea to look them over before continuing.
<P>
<H3>The Basics</H3>

<P>Quite a bit of our widget should look pretty familiar from the
Tictactoe widget. First, we have a header file:
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* GTK - The GIMP Toolkit
 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#ifndef __GTK_DIAL_H__
#define __GTK_DIAL_H__

#include &lt;gdk/gdk.h>
#include &lt;gtk/gtkadjustment.h>
#include &lt;gtk/gtkwidget.h>


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


#define GTK_DIAL(obj)          GTK_CHECK_CAST (obj, gtk_dial_get_type (), GtkDial)
#define GTK_DIAL_CLASS(klass)  GTK_CHECK_CLASS_CAST (klass, gtk_dial_get_type (), GtkDialClass)
#define GTK_IS_DIAL(obj)       GTK_CHECK_TYPE (obj, gtk_dial_get_type ())


typedef struct _GtkDial        GtkDial;
typedef struct _GtkDialClass   GtkDialClass;

struct _GtkDial
{
  GtkWidget widget;

  /* update policy (GTK_UPDATE_[CONTINUOUS/DELAYED/DISCONTINUOUS]) */
  guint policy : 2;

  /* Button currently pressed or 0 if none */
  guint8 button;

  /* Dimensions of dial components */
  gint radius;
  gint pointer_width;

  /* ID of update timer, or 0 if none */
  guint32 timer;

  /* Current angle */
  gfloat angle;

  /* Old values from adjustment stored so we know when something changes */
  gfloat old_value;
  gfloat old_lower;
  gfloat old_upper;

  /* The adjustment object that stores the data for this dial */
  GtkAdjustment *adjustment;
};

struct _GtkDialClass
{
  GtkWidgetClass parent_class;
};


GtkWidget*     gtk_dial_new                    (GtkAdjustment *adjustment);
guint          gtk_dial_get_type               (void);
GtkAdjustment* gtk_dial_get_adjustment         (GtkDial      *dial);
void           gtk_dial_set_update_policy      (GtkDial      *dial,
                                                GtkUpdateType  policy);

void           gtk_dial_set_adjustment         (GtkDial      *dial,
                                                GtkAdjustment *adjustment);