Package gdk

General
GdkDisplayManager
GdkDisplay
GdkScreen
GdkSeat
GdkMonitor
GdkDevice
GdkDevicePad
Rectangles
Pixbufs
RGBA Colors
Visuals
Cursors
Windows
Frame Clock
Frame timings
GdkDrawingContext
OpenGL context
Events
Event Structures
Key Values
Selections
Drag and Drop
Properties and Atoms
Threads
Pango Interaction
Cairo Interaction
X Window System Interaction
Application launching
Deprecated

General

This section describes the GDK initialization functions and miscellaneous utility functions, as well as deprecation facilities.

GdkDisplayManager

Maintains a list of all open GdkDisplays.

GdkDisplay

Controls a set of GdkScreens and their associated input devices.

GdkScreen

Object representing a physical screen.

GdkSeat

Object representing an user seat.

GdkMonitor

Object representing an output.

GdkDevice

Object representing an input device.

GdkDevicePad

Pad device interface.

Rectangles

Simple graphical data types.

GDK provides the gdk-rectangle data type for representing sets of pixels on the screen. Together with Cairo's cairo-region-t data type, they make up the central types for representing graphical data.

Pixbufs

Functions for obtaining pixbufs.

Pixbufs are client-side images. For details on how to create and manipulate pixbufs, see the gdk-pixbuf API documentation. The functions described here allow to obtain pixbufs from gdk-window objects and Cairo surfaces.

RGBA Colors

The gdk-rgba structure is a convenient way to pass RGBA colors around. It is based on Cairo's way to deal with colors and mirrors its behavior. All values are in the range from 0.0 to 1.0 inclusive. So the color

(gdk-rgba-new :red 0.0 :green 0.0 :blue 0.0 :alpha 0.0)    

represents transparent black and

(gdk-rgba-new :red 1.0 :green 1.0 :blue 1.0 :alpha 1.0)    

is opaque white. Other values will be clamped to this range when drawing.

Visuals

Low-level display hardware information

Cursors

Standard and pixmap cursors.

Windows

Onscreen display areas in the target window system.

Frame Clock

A gdk-frame-clock object tells the application when to update and repaint a window.

Frame timings

Object holding timing information for a single frame.

GdkDrawingContext

Drawing context for GDK windows.

OpenGL context

The gdk-gl-context object is representing the platform-specific OpenGL drawing context.

Events

Functions for handling events from the window system.

In GTK applications the events are handled automatically in the gtk-main-do-event function and passed on to the appropriate widgets, so these functions are rarely needed. Though some of the fields in the event structures are useful.

Event Structures

The event structures contain data specific to each type of event in GDK.

Note

A common mistake is to forget to set the event mask of a widget so that the required events are received. See the gtk-widget-events function.

Key Values

Functions for manipulating keyboard codes.

Selections

Functions for transfering data via the X selection mechanism.

The X selection mechanism provides a way to transfer arbitrary chunks of data between programs. A selection is essentially a named clipboard, identified by a string interned as an atom of type gdk-atom. By claiming ownership of a selection, an application indicates that it will be responsible for supplying its contents. The most common selections are "PRIMARY" and "CLIPBOARD".

The contents of a selection can be represented in a number of formats, called targets. Each target is identified by an atom. A list of all possible targets supported by the selection owner can be retrieved by requesting the special target "TARGETS". When a selection is retrieved, the data is accompanied by a type (an atom), and a format (an integer), representing the number of bits per item.

The functions in this section only contain the lowlevel parts of the selection protocol. A considerably more complicated implementation is needed on top of this. GTK contains such an implementation and programmers should use those functions instead of the ones presented here. If you plan to implement selection handling directly on top of the functions here, you should refer to the X Inter-Client Communication Conventions Manual (ICCCM).

The C library has the following constants to refer to selections, targets, and selection types. In the Lisp library the corresponding strings are used. These strings are automatically converted to the corresponding gdk-atom type.

GDK_SELECTION_PRIMARY

"PRIMARY"

GDK_SELECTION_SECONDARY

"SECONDARY"

GDK_SELECTION_CLIPBOARD

"CLIPBOARD"

GDK_TARGET_BITMAP

"BITMAP"

GDK_TARGET_COLORMAP

COLORMAP"

GDK_TARGET_DRAWABLE

"DRAWABLE"

GDK_TARGET_PIXMAP

"PIXMAP"

GDK_TARGET_STRING

"STRING"

GDK_SELECTION_TYPE_ATOM

"ATOM"

GDK_SELECTION_TYPE_BITMAP

"BITMAP"

GDK_SELECTION_TYPE_COLORMAP

"COLORMAP"

GDK_SELECTION_TYPE_DRAWABLE

"DRAWABLE"

GDK_SELECTION_TYPE_INTEGER

"INTEGER"

GDK_SELECTION_TYPE_PIXMAP

"PIXMAP"

GDK_SELECTION_TYPE_WINDOW

"WINDOW"

GDK_SELECTION_TYPE_STRING

"STRING"

Drag and Drop

Functions for controlling drag and drop handling.

Properties and Atoms

An atom is a numeric index into a string table on the X server. They are used to transfer strings efficiently between clients without having to transfer the entire string.

Threads

Functions for using GDK in multi-threaded programs.

For thread safety, GDK relies on the thread primitives in GLib, and on the thread-safe GLib main loop.

GLib is completely thread safe (all global data is automatically locked), but individual data structure instances are not automatically locked for performance reasons. So e.g. you must coordinate accesses to the same GHashTable from multiple threads.

GTK, however, is not thread safe. You should only use GTK and GDK from the thread gtk_init() and gtk_main() were called on. This is usually referred to as the "main thread".

Signals on GTK and GDK types, as well as non-signal callbacks, are emitted in the main thread.

You can schedule work in the main thread safely from other threads by using the gdk-threads-add-idle and gdk-threads-add-timeout functions.

static void
worker_thread (void)
{
  ExpensiveData *expensive_data = do_expensive_computation ();


  gdk_threads_add_idle (got_value, expensive_data);
}


static gboolean
got_value (gpointer user_data)
{
  ExpensiveData *expensive_data = user_data;


  my_app->expensive_data = expensive_data;
  gtk_button_set_sensitive (my_app->button, TRUE);
  gtk_button_set_label (my_app->button, expensive_data->result_label);


  return G_SOURCE_REMOVE;
}    

You should use the gdk-threads-add-idle and gdk-threads-add-timeout functions instead of the g-idle-add and g-timeout-add functions since libraries not under your control might be using the deprecated GDK locking mechanism. If you are sure that none of the code in your application and libraries use the deprecated gdk_threads_enter() or gdk_threads_leave() methods, then you can safely use the g-idle-add and g-timeout-add functions.

For more information on this "worker thread" pattern, you should also look at GTask, which gives you high-level tools to perform expensive tasks from worker threads, and will handle thread management for you.

Pango Interaction

Pango is the text layout system used by GDK and GTK. The functions and types in this section are used to obtain clip regions for pango-layout objects, and to get pango-context objects that can be used with GDK.

Creating a pango-layout object is the first step in rendering text, and requires getting a handle to a pango-context. For GTK programs, you will usually want to use the gtk-widget-pango-context, or gtk-widget-create-pango-layout functions, rather than using the lowlevel gdk-pango-context-for-screen function. Once you have a pango-layout object, you can set the text and attributes of it with Pango functions like the pango-layout-text function and get its size with the pango-layout-size function. Note that Pango uses a fixed point system internally, so converting between Pango units and pixels using the +pango-scale+ constant or the pango-pixels function.

Rendering a Pango layout is done most simply with the pango-cairo-show-layout function. You can also draw pieces of the layout with the pango-cairo-show-layout-line function.

Example: Draw transformed text with Pango and Cairo

(defun demo-pango ()
  (within-main-loop
    (let ((window (make-instance 'gtk-window
                                 :type :toplevel
                                 :title "Demo Using Pango with Cairo"
                                 :border-width 12
                                 :default-width 400
                                 :default-height 400))
          (circle 100)
          (n-words 12)
          (font "Sans Bold 16"))
      (g-signal-connect window "destroy"
                        (lambda (widget)
                          (declare (ignore widget))
                          (leave-gtk-main)))
      ;; Signals used to handle the backing surface
      (g-signal-connect window "draw"
         (lambda (widget cr)
           (let* ((cr (pointer cr))
                  ;; Get the GdkWindow for the widget
                  (window (gtk-widget-window widget))
                  (width (gdk-window-width window))
                  (height (gdk-window-height window))
                  (radius (- (/ (min width height) 2) 20)))
             ;; Set up a transformation matrix so that the user space
             ;; coordinates for where we are drawing are [-RADIUS, RADIUS],
             ;; [-RADIUS, RADIUS] We first center, then change the scale
             (cairo-translate cr
                              (+ radius (/ (- width (* 2 radius)) 2))
                              (+ radius (/ (- height (* 2 radius)) 2)))
             (cairo-scale cr (/ radius circle) (/ radius circle))


           ;; Clear surface
           (cairo-set-source-rgb cr 1 1 1)
           (cairo-paint cr)


           ;; Create a PangoLayout, set the font and text
           (let* ((screen (gdk-window-screen window))
                  (context (gdk-pango-context-for-screen screen))
                  (layout (pango-layout-new context))
                  (desc (pango-font-description-from-string font)))
             (setf (pango-layout-text layout) "Text")
             (setf (pango-layout-font-description layout) desc)


             ;; Draw the layout n-words times in a circle
             (do* ((i 0 (+ i 1))
                   (angle 0 (/ (* 360 i) n-words))
                   ;; Gradient from red to blue
                   (red (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)
                        (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)))
                  ((>= i n-words))
               (cairo-save cr)
               (cairo-set-source-rgb cr red 0 (- 1 red))
               (cairo-rotate cr (/ (* angle pi) 180))


               ;; Inform Pango to re-layout the text with the new
               ;; transformation matrix
               (pango-cairo-update-layout cr layout)


               (multiple-value-bind (width height)
                   (pango-layout-size layout)
                 (declare (ignore height))
                 (cairo-move-to cr (- (/ width 2 +pango-scale+)) (- circle)))
               (pango-cairo-show-layout cr layout)
               (cairo-restore cr)))
           (cairo-destroy cr)
           t)))
      (gtk-widget-show-all window))))    

Cairo Interaction

Functions to support using Cairo.

Cairo is a graphics library that supports vector graphics and image compositing that can be used with GDK. GTK does all of its drawing using Cairo.

GDK does not wrap the Cairo API, instead it allows to create Cairo contexts which can be used to draw on gdk-window objects. Additional functions allow use gdk-rectangle instances with Cairo and to use gdk-color, gdk-rgba, gdk-pixbuf and gdk-window objects as sources for drawing operations.

X Window System Interaction

X backend-specific functions

Application launching

Startup notification for applications.

Deprecated