<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic"
      id="tech-gdk">

  <info>
    <link type="guide" xref="tech" group="gdk"/>
    <revision pkgversion="3.0" date="2011-04-05" status="candidate"/>

    <credit type="author copyright">
      <name>Shaun McCance</name>
      <email its:translate="no">shaunm@gnome.org</email>
      <years>2011–2012</years>
    </credit>

    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <desc>Low-level abstraction for the windowing system</desc>
  </info>

<title>GDK</title>

  <p>GDK is the low-level library used by <link xref="tech-gtk">GTK+</link> to
  interact with the windowing system for graphics and input devices. Although
  you will rarely use GDK directly in application code, it contains all the
  necessary functionality to create low-level windows in the the screen and to
  interact with the user with various input devices. GDK acts as an abstraction
  over various windowing systems, so that GTK+ can be portable to all of them:
  the X Window System (X11), Microsoft Windows, Mac OS X Quartz.</p>

<p>GDK enables you to access events from keyboards, mice, and other
input devices.  Implementations of widgets in GTK+ use this functionality, and
translate the events into higher-level signals that can in turn be used from
application code.  For example, a <code>GtkButton</code> widget will track
<code>GDK_BUTTON_PRESS</code> and <code>GTK_BUTTON_RELEASE</code> events,
which come from the mouse, and translate them as appropriate into a
<code>GtkButton::clicked</code> signal when the user presses and releases
the button in the right location.</p>

<p>GDK also provides low-level routines to access drag and drop
and clipboard data from the system.  When implementing custom controls,
you may need to access these features to implement proper user interaction
behavior.</p>

<p>GDK provides other functionality which is needed to implement
a complete graphical toolkit like GTK+.  Since GDK acts as a platform
abstraction, allowing GTK+ to run under multiple environments, it
provides an API for all of the system functionality needed by GTK+.
This includes information about multi-head displays, resolution and
color depth, colormaps, and cursors.</p>

  <p>You should use GDK whenever you need low-level access to the underlying
  windowing system, including low-level access to events, windows, and the
  clipboard. Using GDK for these tasks ensures that your code is portable and
  integrates with the rest of your GTK+ code. The simple drawing routines in
  GDK should generally not be used; these are a left-over from when GDK simply
  wrapped the windowing system's drawing primitives. Instead, you should use
  the extensive functionality provided by <link xref="tech-cairo">Cairo</link>
  to draw high-quality 2D graphics.</p>

<list style="compact">
  <item><p><link href="https://developer.gnome.org/gdk3/stable/">GDK Reference Manual</link></p></item>
</list>
</page>
