on the screen, is then:
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* Draw a rectangle on the screen */
static void
draw_brush (GtkWidget *widget, gdouble x, gdouble y)
{
  GdkRectangle update_rect;

  update_rect.x = x - 5;
  update_rect.y = y - 5;
  update_rect.width = 10;
  update_rect.height = 10;
  gdk_draw_rectangle (pixmap,
                      widget->style->black_gc,
                      TRUE,
                      update_rect.x, update_rect.y,
                      update_rect.width, update_rect.height);
  gtk_widget_draw (widget, &amp;update_rect);
}
</PRE>
</CODE></BLOCKQUOTE>
<P>After we draw the rectangle representing the brush onto the pixmap,
we call the function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void       gtk_widget_draw                (GtkWidget           *widget,
                                           GdkRectangle        *area);
</PRE>
</CODE></BLOCKQUOTE>
<P>which notifies X that the area given by the <CODE>area</CODE> parameter
needs to be updated. X will eventually generate an expose event
(possibly combining the areas passed in several calls to
<CODE>gtk_widget_draw()</CODE>) which will cause our expose event handler
to copy the relevant portions to the screen.
<P>We have now covered the entire drawing program except for a few
mundane details like creating the main window.
<P>
<H2><A NAME="ss23.4">23.4 Adding XInput support</A>
</H2>

<P>It is now possible to buy quite inexpensive input devices such 
as drawing tablets, which allow drawing with a much greater
ease of artistic expression than does a mouse. The simplest way
to use such devices is simply as a replacement for the mouse,
but that misses out many of the advantages of these devices,
such as:
<P>
<UL>
<LI> Pressure sensitivity</LI>
<LI> Tilt reporting</LI>
<LI> Sub-pixel positioning</LI>
<LI> Multiple inputs (for example, a stylus with a point and eraser)</LI>
</UL>
<P>For information about the XInput extension, see the 
<A HREF="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html">XInput-HOWTO</A>.
<P>If we examine the full definition of, for example, the GdkEventMotion
structure, we see that it has fields to support extended device
information.
<P>
<BLOCKQUOTE><CODE>
<PRE>
struct _GdkEventMotion
{
  GdkEventType type;
  GdkWindow *window;
  guint32 time;
  gdouble x;
  gdouble y;
  gdouble pressure;
  gdouble xtilt;
  gdouble ytilt;
  guint state;
  gint16 is_hint;
  GdkInputSource source;
  guint32 deviceid;
};
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>pressure</CODE> gives the pressure as a floating point number between
0 and 1. <CODE>xtilt</CODE> and <CODE>ytilt</CODE> can take on values between 
-1 and 1, corresponding to the degree of tilt in each direction.
<CODE>source</CODE> and <CODE>deviceid</CODE> specify the device for which the
event occurred in two different ways. <CODE>source</CODE> gives some simple
information about the type of device. It can take the enumeration
values:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GDK_SOURCE_MOUSE
GDK_SOURCE_PEN
GDK_SOURCE_ERASER
GDK_SOURCE_CURSOR
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>deviceid</CODE> specifies a unique numeric ID for the device. This can
be used to find out further information about the device using the
<CODE>gdk_input_list_devices()</CODE> call (see below). The special value
<CODE>GDK_CORE_POINTER</CODE> is used for the core pointer device. (Usually
the mouse.)
<P>
<H3>Enabling extended device information</H3>

<P>To let GTK know about our interest in the extended device information,
we merely have to add a single line to our program:
<P>
<BLOCKQUOTE><CODE>
<PRE>
gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR);
</PRE>
</CODE></BLOCKQUOTE>
<P>By giving the value <CODE>GDK_EXTENSION_EVENTS_CURSOR</CODE> we say that
we are interested in extension events, but only if we don't have
to draw our own cursor. See the section 
<A HREF="#sec_Further_Sophistications">Further Sophistications</A> below
for more information about drawing the cursor. We could also 
give the values <CODE>GDK_EXTENSION_EVENTS_ALL</CODE> if we were willing 
to draw our own cursor, or <CODE>GDK_EXTENSION_EVENTS_NONE</CODE> to revert
back to the default condition.
<P>This is not completely the end of the story however. By default,
no extension devices are enabled. We need a mechanism to allow
users to enable and configure their extension devices. GTK provides
the InputDialog widget to automate this process. The following
procedure manages an InputDialog widget. It creates the dialog if
it isn't present, and raises it to the top otherwise.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void
input_dialog_destroy (GtkWidget *w, gpointer data)
{
  *((GtkWidget **)data) = NULL;
}

void
create_input_dialog ()
{
  static GtkWidget *inputd = NULL;

  if (!inputd)
    {
      inputd = gtk_input_dialog_new();

      gtk_signal_connect (GTK_OBJECT(inputd), "destroy",
                          (GtkSignalFunc)input_dialog_destroy, &amp;inputd);
      gtk_signal_connect_object (GTK_OBJECT(GTK_INPUT_DIALOG(inputd)->close_button),
                                 "clicked",
                                 (GtkSignalFunc)gtk_widget_hide,
                                 GTK_OBJECT(inputd));
      gtk_widget_hide ( GTK_INPUT_DIALOG(inputd)->save_button);

      gtk_widget_show (inputd);
    }
  else
    {
      if (!GTK_WIDGET_MAPPED(inputd))
        gtk_widget_show(inputd);
      else
        gdk_window_raise(inputd->window);
    }
}
</PRE>
</CODE></BLOCKQUOTE>
<P>(You might want to take note of the way we handle this dialog.  By
connecting to the "destroy" signal, we make sure that we don't keep a
pointer to dialog around after it is destroyed - that could lead to a
segfault.)
<P>The InputDialog has two buttons "Close" and "Save", which by default
have no actions assigned to them. In the above function we make
"Close" hide the dialog, hide the "Save" button, since we don't
implement saving of XInput options in this program.
<P>
<H3>Using extended device information</H3>

<P>Once we've enabled the device, we can just use the extended 
device information in the extra fields of the event structures.
In fact, it is always safe to use this information since these
fields will have reasonable default values even when extended
events are not enabled.
<P>Once change we do have to make is to call
<CODE>gdk_input_window_get_pointer()</CODE> instead of
<CODE>gdk_window_get_pointer</CODE>. This is necessary because
<CODE>gdk_window_get_pointer</CODE> doesn't return the extended device
information.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gdk_input_window_get_pointer( GdkWindow       *window,
                                   guint32         deviceid,
                                   gdouble         *x,
                                   gdouble         *y,
                                   gdouble         *pressure,
                                   gdouble         *xtilt,
                                   gdouble         *ytilt,
                                   GdkModifierType *mask);
</PRE>
</CODE></BLOCKQUOTE>
<P>When calling this function, we need to specify the device ID as
well as the window. Usually, we'll get the device ID from the
<CODE>deviceid</CODE> field of an event structure. Again, this function
will return reasonable values when extension events are not
enabled. (In this case, <CODE>event->deviceid</CODE> will have the value
<CODE>GDK_CORE_POINTER</CODE>).
<P>So the basic structure of our button-press and motion event handlers
doesn't change much - we just need to add code to deal with the
extended information.
<P>
<BLOCKQUOTE><CODE>
<PRE>
static gint
button_press_event (GtkWidget *widget, GdkEventButton *event)
{
  print_button_press (event->deviceid);
  
  if (event->button == 1 &amp;&amp; pixmap != NULL)
    draw_brush (widget, event->source, event->x, event->y, event->pressure);

  return TRUE;
}

static gint
motion_notify_event (GtkWidget *widget, GdkEventMotion *event)
{
  gdouble x, y;
  gdouble pressure;
  GdkModifierType state;

  if (event->is_hint)
    gdk_input_window_get_pointer (event->window, event->deviceid,
                                  &amp;x, &amp;y, &amp;pressure, NULL, NULL, &amp;state);
  else
    {
      x = event->x;
      y = event->y;
      pressure = event->pressure;
      state = event->state;
    }
    
  if (state &amp; GDK_BUTTON1_MASK &amp;&amp; pixmap != NULL)
    draw_brush (widget, event->source, x, y, pressure);
  
  return TRUE;
}
</PRE>
</CODE></BLOCKQUOTE>
<P>We also need to do something with the new information. Our new
<CODE>draw_brush()</CODE> function draws with a different color for
each <CODE>event->source</CODE> and changes the brush size depending
on the pressure.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* Draw a rectangle on the screen, size depending on pressure,
   and color on the type of device */
static void
draw_brush (GtkWidget *widget, GdkInputSource source,
            gdouble x, gdouble y, gdouble pressure)
{
  GdkGC *gc;
  GdkRectangle update_rect;

  switch (source)
    {
    case GDK_SOURCE_MOUSE:
      gc = widget->style->dark_gc[GTK_WIDGET_STATE (widget)];
      break;
    case GDK_SOURCE_PEN:
      gc = widget->style->black_gc;
      break;
    case GDK_SOURCE_ERASER:
      gc = widget->style->white_gc;
      break;
    default:
      gc = widget->style->light_gc[GTK_WIDGET_STATE (widget)];
    }

  update_rect.x = x - 10 * pressure;
  update_rect.y = y - 10 * pressure;
  update_rect.width = 20 * pressure;
  update_rect.height = 20 * pressure;
  gdk_draw_rectangle (pixmap, gc, TRUE,
                      update_rect.x, update_rect.y,
                      update_rect.width, update_rect.height);
  gtk_widget_draw (widget, &amp;update_rect);
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>Finding out more about a device</H3>

<P>As an example of how to find out more about a device, our program
will print the name of the device that generates each button
press. To find out the name of a device, we call the function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GList *gdk_input_list_devices               (void);
</PRE>
</CODE></BLOCKQUOTE>
<P>which returns a GList (a linked list type from the GLib library)
of GdkDeviceInfo structures. The GdkDeviceInfo structure is defined
as:
<P>
<BLOCKQUOTE><CODE>
<PRE>
struct _GdkDeviceInfo
{
  guint32 deviceid;
  gchar *name;
  GdkInputSource source;
  GdkInputMode mode;
  gint has_cursor;
  gint num_axes;
  GdkAxisUse *axes;
  gint num_keys;
  GdkDeviceKey *keys;
};
</PRE>
</CODE></BLOCKQUOTE>
<P>Most of these fields are configuration information that you can ignore
unless you are implementing XInput configuration saving. The fieldwe
are interested in here is <CODE>name</CODE> which is simply the name that X
assigns to the device. The other field that isn't configuration
information is <CODE>has_cursor</CODE>. If <CODE>has_cursor</CODE> is false, then we
we need to draw our own cursor. But since we've specified
<CODE>GDK_EXTENSION_EVENTS_CURSOR</CODE>, we don't have to worry about this.
<P>Our <CODE>print_button_press()</CODE> function simply iterates through
the returned list until it finds a match, then prints out
the name of the device.
<P>
<BLOCKQUOTE><CODE>
<PRE>
static void
print_button_press (guint32 deviceid)
{
  GList *tmp_list;

  /* gdk_input_list_devices returns an internal list, so we shouldn't
     free it afterwards */
  tmp_list = gdk_input_list_devices();

  while (tmp_list)
    {
      GdkDeviceInfo *info = (GdkDeviceInfo *)tmp_list->data;

      if (info->deviceid == deviceid)
        {
          printf("Button press on device '%s'\n", info->name);
          return;
        }

      tmp_list = tmp_list->next;
    }
}
</PRE>
</CODE></BLOCKQUOTE>
<P>That completes the changes to "XInputize" our program.
<P>
<H3><A NAME="sec_Further_Sophistications"></A> Further sophistications </H3>

<P>Although our program now supports XInput quite well, it lacks some
features we would want in a full-featured application. First, the user
probably doesn't want to have to configure their device each time they
run the program, so we should allow them to save the device
configuration. This is done by iterating through the return of
<CODE>gdk_input_list_devices()</CODE> and writing out the configuration to a
file.
<P>To restore the state next time the program is run, GDK provides
functions to change device configuration:
<P>
<BLOCKQUOTE><CODE>
<PRE>
gdk_input_set_extension_events()
gdk_input_set_source()
gdk_input_set_mode()
gdk_input_set_axes()
gdk_input_set_key()
</PRE>
</CODE></BLOCKQUOTE>
<P>(The list returned from <CODE>gdk_input_list_devices()</CODE> should not be
modified directly.) An example of doing this can be found in the
drawing program gsumi. (Available from 
<A HREF="http://www.msc.cornell.edu/~otaylor/gsumi/">http://www.msc.cornell.edu/~otaylor/gsumi/</A>) Eventually, it
would be nice to have a standard way of doing this for all
applications. This probably belongs at a slightly higher level than
GTK, perhaps in the GNOME library.
<P>Another major omission that we have mentioned above is the lack of
cursor drawing. Platforms other than XFree86 currently do not allow
simultaneously using a device as both the core pointer and directly by
an application. See the 
<A HREF="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html">XInput-HOWTO</A> for more information about this. This means that
applications that want to support the widest audience need to draw
their own cursor.
<P>An application that draws its own cursor needs to do two things:
determine if the current device needs a cursor drawn or not, and
determine if the current device is in proximity. (If the current
device is a drawing tablet, it's a nice touch to make the cursor 
disappear when the stylus is lifted from the tablet. When the
device is touching the stylus, that is called "in proximity.")
The first is done by searching the device list, as we did
to find out the device name. The second is achieved by selecting
"proximity_out" events. An example of drawing one's own cursor is
found in the "testinput" program found in the GTK distribution.
<P>
<HR>
<A HREF="gtk_tut-24.html">Next</A>
<A HREF="gtk_tut-22.html">Previous</A>
<A HREF="gtk_tut.html#toc23">Contents</A>
</BODY>
</HTML>