This is guile-gnome-gdk.info, produced by makeinfo version 4.8 from
guile-gnome-gdk.texi.

   This manual is for `(gnome gdk)' (version 2.15.93, updated 2
September 2007)

   GDK documentation Copyright 1997-2007 Damon Chaplin and others

     This work may be reproduced and distributed in whole or in part, in
     any medium, physical or electronic, so as long as this copyright
     notice remains intact and unchanged on all copies.  Commercial
     redistribution is permitted and encouraged, but you may not
     redistribute, in whole or in part, under terms more restrictive
     than those under which you received it. If you redistribute a
     modified or translated version of this work, you must also make
     the source code to the modified or translated version available in
     electronic form without charge.  However, mere aggregation as part
     of a larger work shall not count as a modification for this
     purpose.

     All code examples in this work are placed into the public domain,
     and may be used, modified and redistributed without restriction.

     BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
     FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
     WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
     OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
     KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     PARTICULAR PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
     THE COST OF ALL NECESSARY REPAIR OR CORRECTION.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE
     TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

   GDK-Pixbuf documentation Copyright 2000 Free Software Foundation.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts. You may obtain a copy of the GNU Free
     Documentation License from the Free Software Foundation by
     visiting their Web site or by writing to:

     The Free Software Foundation, Inc.,   59 Temple Place - Suite 330,
      Boston, MA 02111-1307,   USA

     Many of the names used by companies to distinguish their products
     and services are claimed as trademarks. Where those names appear
     in any GNOME documentation, and those trademarks are made aware to
     the members of the GNOME Documentation Project, the names have been
     printed in caps or initial caps.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile-Gdk: (guile-gnome-gdk.info).  The GIMP Drawing Kit.
END-INFO-DIR-ENTRY


File: guile-gnome-gdk.info,  Node: Top,  Next: Overview,  Up: (dir)

Guile-Gdk
*********

This manual is for `(gnome gdk)' (version 2.15.93, updated 2 September
2007)

   GDK documentation Copyright 1997-2007 Damon Chaplin and others

     This work may be reproduced and distributed in whole or in part, in
     any medium, physical or electronic, so as long as this copyright
     notice remains intact and unchanged on all copies.  Commercial
     redistribution is permitted and encouraged, but you may not
     redistribute, in whole or in part, under terms more restrictive
     than those under which you received it. If you redistribute a
     modified or translated version of this work, you must also make
     the source code to the modified or translated version available in
     electronic form without charge.  However, mere aggregation as part
     of a larger work shall not count as a modification for this
     purpose.

     All code examples in this work are placed into the public domain,
     and may be used, modified and redistributed without restriction.

     BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
     FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
     WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
     OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
     KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     PARTICULAR PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
     THE COST OF ALL NECESSARY REPAIR OR CORRECTION.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE
     TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

   GDK-Pixbuf documentation Copyright 2000 Free Software Foundation.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts. You may obtain a copy of the GNU Free
     Documentation License from the Free Software Foundation by
     visiting their Web site or by writing to:

     The Free Software Foundation, Inc.,   59 Temple Place - Suite 330,
      Boston, MA 02111-1307,   USA

     Many of the names used by companies to distinguish their products
     and services are claimed as trademarks. Where those names appear
     in any GNOME documentation, and those trademarks are made aware to
     the members of the GNOME Documentation Project, the names have been
     printed in caps or initial caps.

* Menu:

* Overview:: Overview

GDK
* General:: Library initialization and miscellaneous functions
* GdkDisplay:: Controls the keyboard/mouse pointer grabs and a set of s
* GdkDisplayManager:: Maintains a list of all open s
* GdkScreen:: Object representing a physical screen
* Points Rectangles and Regions:: Simple graphical data types
* Graphics Contexts:: Objects to encapsulate drawing properties
* Drawing Primitives:: Functions for drawing points, lines, arcs, and text
* Bitmaps and Pixmaps:: Offscreen drawables
* GdkRGB:: Renders RGB, grayscale, or indexed image data to a GdkDrawable
* Images:: A client-side area for bit-mapped graphics
* Pixbufs:: Functions for rendering pixbufs on drawables
* Colormaps and Colors:: Manipulation of colors and colormaps
* Visuals:: Low-level display hardware information
* Fonts:: Loading and manipulating fonts
* Cursors:: Standard and pixmap cursors
* Windows:: Onscreen display areas in the target window system
* Events:: Functions for handling events from the window system
* Event Structures:: Data structures specific to each type of event
* Key Values:: Functions for manipulating keyboard codes
* Selections:: Functions for transfering data via the X selection mechanism
* Drag and Drop:: Functions for controlling drag and drop handling
* Properties and Atoms:: Functions to manipulate properties on windows
* Threads:: Functions for using GDK in multi-threaded programs
* Input:: Callbacks on file descriptors
* Input Devices:: Functions for handling extended input devices
* Pango Interaction:: Using Pango in GDK
* Cairo Interaction:: Functions to support using Cairo
* X Window System Interaction:: X backend-specific functions

GDK-Pixbuf
* Initialization and Versions:: Library version numbers.
* The GdkPixbuf Structure:: Information that describes an image.
* Reference Counting and Memory Mangement:: Functions for reference counting and memory management on pixbufs.
* File Loading:: Loading a pixbuf from a file.
* File saving:: Saving a pixbuf to a file.
* Image Data in Memory:: Creating a pixbuf from image data that is already in memory.
* Inline data:: Functions for inlined pixbuf handling.
* Scaling:: Scaling pixbufs and scaling and compositing pixbufs
* Utilities:: Utility and miscellaneous convenience functions.
* Animations:: Animated images.
* GdkPixbufLoader:: Application-driven progressive image loading.
* Module Interface:: Extending gdk-pixbuf
* gdk-pixbuf Xlib initialization:: Initializing the gdk-pixbuf Xlib library.
* Xlib Rendering:: Rendering a pixbuf to an X drawable.
* X Drawables to Pixbufs:: Getting parts of an X drawable's image data into a pixbuf.
* XlibRGB:: Rendering RGB buffers to X drawables.

* Undocumented::      Undocumented functions.

* Type Index::
* Function Index::


File: guile-gnome-gdk.info,  Node: Overview,  Next: General,  Prev: Top,  Up: Top

1 Overview
**********

The GDK wrapper for Guile is a part of Guile-GNOME. Maybe write more
here at some point.


File: guile-gnome-gdk.info,  Node: General,  Next: GdkDisplay,  Prev: Overview,  Up: Top

2 General
*********

Library initialization and miscellaneous functions

2.1 Overview
============

This section describes the GDK initialization functions and
miscellaneous utility functions.

2.2 Usage
=========

 -- Function: gdk-get-display-arg-name =>  (ret `mchars')
     Gets the display name specified in the command line arguments
     passed to `gdk-init' or `gdk-parse-args', if any.

    RET
          the display name, if specified explicitely, otherwise ``#f''
          this string is owned by GTK+ and must not be modified or
          freed.


     Since 2.2


 -- Function: gdk-set-locale =>  (ret `mchars')
     Initializes the support for internationalization by calling the
     ``setlocale'' system call. This function is called by
     `gtk-set-locale' and so GTK+ applications should use that instead.

     The locale to use is determined by the `LANG' environment
     variable, so to run an application in a certain locale you can do
     something like this:


            export LANG="fr"
            ... run application ...

     If the locale is not supported by X then it is reset to the
     standard "C" locale.

    RET
          the resulting locale.



 -- Function: gdk-set-sm-client-id (sm_client_id `mchars')
     Sets the `SM_CLIENT_ID' property on the application's leader
     window so that the window manager can save the application's state
     using the X11R6 ICCCM session management protocol.

     See the X Session Management Library documentation for more
     information on session management and the Inter-Client
     Communication Conventions Manual (ICCCM) for information on the
     `WM_CLIENT_LEADER' property. (Both documents are part of the X
     Window System distribution.)

    SM-CLIENT-ID
          the client id assigned by the session manager when the
          connection was opened, or ``#f'' to remove the property.



 -- Function: gdk-notify-startup-complete
     Indicates to the GUI environment that the application has finished
     loading. If the applications opens windows, this function is
     normally called after opening the application's initial set of
     windows.

     GTK+ will call this function automatically after opening the first
     `<gtk-window>' unless `gtk-window-set-auto-startup-notification' is
     called to disable that feature.

     Since 2.2


 -- Function: gdk-get-program-class =>  (ret `mchars')
     Gets the program class. Unless the program class has explicitly
     been set with `gdk-set-program-class' or with the option, the
     default value is the program name (determined with
     `g-get-prgname') with the first character converted to uppercase.

    RET
          the program class.



 -- Function: gdk-set-program-class (program_class `mchars')
     Sets the program class. The X11 backend uses the program class to
     set the class name part of the `WM_CLASS' property on toplevel
     windows; see the ICCCM.

    PROGRAM-CLASS
          a string.



 -- Function: gdk-get-display =>  (ret `mchars')
     Gets the name of the display, which usually comes from the
     `DISPLAY' environment variable or the
    RET
          the name of the display.



 -- Function: gdk-flush
     Flushes the X output buffer and waits until all requests have been
     processed by the server. This is rarely needed by applications.
     It's main use is for trapping X errors with `gdk-error-trap-push'
     and `gdk-error-trap-pop'.


 -- Function: gdk-screen-width =>  (ret `int')
     Returns the width of the default screen in pixels.

    RET
          the width of the default screen in pixels.



 -- Function: gdk-screen-height =>  (ret `int')
     Returns the height of the default screen in pixels.

    RET
          the height of the default screen in pixels.



 -- Function: gdk-screen-width-mm =>  (ret `int')
     Returns the width of the default screen in millimeters. Note that
     on many X servers this value will not be correct.

    RET
          the width of the default screen in millimeters, though it is
          not always correct.



 -- Function: gdk-screen-height-mm =>  (ret `int')
     Returns the height of the default screen in millimeters. Note that
     on many X servers this value will not be correct.

    RET
          the height of the default screen in millimeters, though it is
          not always correct.



 -- Function: gdk-pointer-grab (window `<gdk-window>')
          (owner_events `bool') (event_mask `<gdk-event-mask>')
          (confine_to `<gdk-window>') (cursor `<gdk-cursor>')
          (time_ `unsigned-int32') =>  (ret `<gdk-grab-status>')
     Grabs the pointer (usually a mouse) so that all events are passed
     to this application until the pointer is ungrabbed with
     `gdk-pointer-ungrab', or the grab window becomes unviewable. This
     overrides any previous pointer grab by this client.

     Pointer grabs are used for operations which need complete control
     over mouse events, even if the mouse leaves the application. For
     example in GTK+ it is used for Drag and Drop, for dragging the
     handle in the `<gtk-hpaned>' and `<gtk-vpaned>' widgets, and for
     resizing columns in `<gtk-clist>' widgets.

     Note that if the event mask of an X window has selected both
     button press and button release events, then a button press event
     will cause an automatic pointer grab until the button is released.
     X does this automatically since most applications expect to
     receive button press and release events in pairs. It is equivalent
     to a pointer grab on the window with OWNER-EVENTS set to ``#t''.

     If you set up anything at the time you take the grab that needs to
     be cleaned up when the grab ends, you should handle the
     `<gdk-event-grab-broken>' events that are emitted when the grab
     ends unvoluntarily.

    WINDOW
          the `<gdk-window>' which will own the grab (the grab window).

    OWNER-EVENTS
          if ``#f'' then all pointer events are reported with respect to
          WINDOW and are only reported if selected by EVENT-MASK. If
          ``#t'' then pointer events for this application are reported
          as normal, but pointer events outside this application are
          reported with respect to WINDOW and only if selected by
          EVENT-MASK. In either mode, unreported events are discarded.

    EVENT-MASK
          specifies the event mask, which is used in accordance with
          OWNER-EVENTS.  Note that only pointer events (i.e. button and
          motion events) may be selected.

    CONFINE-TO
          If non-``#f'', the pointer will be confined to this window
          during the grab. If the pointer is outside CONFINE-TO, it
          will automatically be moved to the closest edge of CONFINE-TO
          and enter and leave events will be generated as necessary.

    CURSOR
          the cursor to display while the grab is active. If this is
          ``#f'' then the normal cursors are used for WINDOW and its
          descendants, and the cursor for WINDOW is used for all other
          windows.

    TIME
          the timestamp of the event which led to this pointer grab.
          This usually comes from a `<gdk-event-button>' struct, though
          `GDK_CURRENT_TIME' can be used if the time isn't known.

    RET
          `GDK_GRAB_SUCCESS' if the grab was successful.



 -- Function: gdk-pointer-ungrab (time_ `unsigned-int32')
     Ungrabs the pointer, if it is grabbed by this application.

    TIME
          a timestamp from a `<gdk-event>', or `GDK_CURRENT_TIME' if no
          timestamp is available.



 -- Function: gdk-pointer-is-grabbed =>  (ret `bool')
     Returns ``#t'' if the pointer is currently grabbed by this
     application.

     Note that this does not take the inmplicit pointer grab on button
     presses into account.

    RET
          ``#t'' if the pointer is currently grabbed by this
          application.*



 -- Function: gdk-set-double-click-time (msec `unsigned-int')
     Set the double click time for the default display. See
     `gdk-display-set-double-click-time'. See also
     `gdk-display-set-double-click-distance'. Applications should _not_
     set this, it is a global user-configured setting.

    MSEC
          double click time in milliseconds (thousandths of a second)



 -- Function: gdk-keyboard-grab (window `<gdk-window>')
          (owner_events `bool') (time_ `unsigned-int32') => 
          (ret `<gdk-grab-status>')
     Grabs the keyboard so that all events are passed to this
     application until the keyboard is ungrabbed with
     `gdk-keyboard-ungrab'. This overrides any previous keyboard grab
     by this client.

     If you set up anything at the time you take the grab that needs to
     be cleaned up when the grab ends, you should handle the
     `<gdk-event-grab-broken>' events that are emitted when the grab
     ends unvoluntarily.

    WINDOW
          the `<gdk-window>' which will own the grab (the grab window).

    OWNER-EVENTS
          if ``#f'' then all keyboard events are reported with respect
          to WINDOW. If ``#t'' then keyboard events for this
          application are reported as normal, but keyboard events
          outside this application are reported with respect to WINDOW.
          Both key press and key release events are always reported,
          independant of the event mask set by the application.

    TIME
          a timestamp from a `<gdk-event>', or `GDK_CURRENT_TIME' if no
          timestamp is available.

    RET
          `GDK_GRAB_SUCCESS' if the grab was successful.



 -- Function: gdk-keyboard-ungrab (time_ `unsigned-int32')
     Ungrabs the keyboard, if it is grabbed by this application.

    TIME
          a timestamp from a `<gdk-event>', or `GDK_CURRENT_TIME' if no
          timestamp is available.



 -- Function: gdk-beep
     Emits a short beep on the default display.


 -- Function: gdk-get-use-xshm =>  (ret `bool')
     `gdk_get_use_xshm' is deprecated and should not be used in
     newly-written code.

     Returns ``#t'' if GDK will attempt to use the MIT-SHM shared memory
     extension.

     The shared memory extension is used for `<gdk-image>', and
     consequently for GdkRGB. It enables much faster drawing by
     communicating with the X server through SYSV shared memory calls.
     However, it can only be used if the X client and server are on the
     same machine and the server supports it.

    RET
          ``#t'' if use of the MIT shared memory extension will be
          attempted.



 -- Function: gdk-set-use-xshm (use_xshm `bool')
     `gdk_set_use_xshm' is deprecated and should not be used in
     newly-written code.

     Sets whether the use of the MIT shared memory extension should be
     attempted.  This function is mainly for internal use. It is only
     safe for an application to set this to ``#f'', since if it is set
     to ``#t'' and the server does not support the extension it may
     cause warning messages to be output.

    USE-XSHM
          ``#t'' if use of the MIT shared memory extension should be
          attempted.



 -- Function: gdk-error-trap-push
     This function allows X errors to be trapped instead of the normal
     behavior of exiting the application. It should only be used if it
     is not possible to avoid the X error in any other way.


            gdk_error_trap_push ();

            /* ... Call the X function which may cause an error here ... */

            /* Flush the X queue to catch errors now. */
            gdk_flush ();

            if (gdk_error_trap_pop ())
              {
                /* ... Handle the error here ... */
              }


 -- Function: gdk-error-trap-pop =>  (ret `int')
     Removes the X error trap installed with `gdk-error-trap-push'.

    RET
          the X error code, or 0 if no error occurred.




File: guile-gnome-gdk.info,  Node: GdkDisplay,  Next: GdkDisplayManager,  Prev: General,  Up: Top

3 GdkDisplay
************

Controls the keyboard/mouse pointer grabs and a set of s

3.1 Overview
============

`<gdk-display>' objects purpose are two fold:

   To grab/ungrab keyboard focus and mouse pointer

   To manage and provide information about the `<gdk-screen>'(s)
available for this `<gdk-display>'

   `<gdk-display>' objects are the GDK representation of the X Display
which can be described as _a workstation consisting of a keyboard a
pointing device (such as a mouse) and one or more screens_. It is used
to open and keep track of various `<gdk-screen>' objects currently
instanciated by the application. It is also used to grab and release
the keyboard and the mouse pointer.

3.2 Usage
=========

 -- Class: <gdk-display>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Signal on <gdk-display>: closed (arg0 `<gboolean>')
     The ::closed signal is emitted when the connection to the
     windowing system for DISPLAY is closed.

     Since 2.2


 -- Function: gdk-display-open (display_name `mchars') => 
          (ret `<gdk-display>')
     Opens a display.

    DISPLAY-NAME
          the name of the display to open

    RET
          a `<gdk-display>', or ``#f'' if the display could not be
          opened.


     Since 2.2


 -- Function: gdk-display-get-default =>  (ret `<gdk-display>')
     Gets the default `<gdk-display>'. This is a convenience function
     for:


            gdk_display_manager_get_default_display (gdk_display_manager_get ())

    RET
          a `<gdk-display>', or ``#f'' if there is no default display.


     Since 2.2


 -- Function: gdk-display-get-name (self `<gdk-display>') => 
          (ret `mchars')
 -- Method: get-name
     Gets the name of the display.

    DISPLAY
          a `<gdk-display>'

    RET
          a string representing the display name. This string is owned
          by GDK and should not be modified or freed.


     Since 2.2


 -- Function: gdk-display-get-n-screens (self `<gdk-display>') => 
          (ret `int')
 -- Method: get-n-screens
     Gets the number of screen managed by the DISPLAY.

    DISPLAY
          a `<gdk-display>'

    RET
          number of screens.


     Since 2.2


 -- Function: gdk-display-get-screen (self `<gdk-display>')
          (screen_num `int') =>  (ret `<gdk-screen>')
 -- Method: get-screen
     Returns a screen object for one of the screens of the display.

    DISPLAY
          a `<gdk-display>'

    SCREEN-NUM
          the screen number

    RET
          the `<gdk-screen>' object


     Since 2.2


 -- Function: gdk-display-get-default-screen (self `<gdk-display>') => 
          (ret `<gdk-screen>')
 -- Method: get-default-screen
     Get the default `<gdk-screen>' for DISPLAY.

    DISPLAY
          a `<gdk-display>'

    RET
          the default `<gdk-screen>' object for DISPLAY


     Since 2.2


 -- Function: gdk-display-pointer-ungrab (self `<gdk-display>')
          (time_ `unsigned-int32')
 -- Method: pointer-ungrab
     Release any pointer grab.

    DISPLAY
          a `<gdk-display>'.

    TIME
          a timestap (e.g. `GDK_CURRENT_TIME').


     Since 2.2


 -- Function: gdk-display-keyboard-ungrab (self `<gdk-display>')
          (time_ `unsigned-int32')
 -- Method: keyboard-ungrab
     Release any keyboard grab

    DISPLAY
          a `<gdk-display>'.

    TIME
          a timestap (e.g `<gdk-current-time>').


     Since 2.2


 -- Function: gdk-display-pointer-is-grabbed (self `<gdk-display>') => 
          (ret `bool')
 -- Method: pointer-is-grabbed
     Test if the pointer is grabbed.

    DISPLAY
          a `<gdk-display>'

    RET
          ``#t'' if an active X pointer grab is in effect


     Since 2.2


 -- Function: gdk-display-beep (self `<gdk-display>')
 -- Method: beep
     Emits a short beep on DISPLAY

    DISPLAY
          a `<gdk-display>'


     Since 2.2


 -- Function: gdk-display-sync (self `<gdk-display>')
 -- Method: sync
     Flushes any requests queued for the windowing system and waits
     until all requests have been handled. This is often used for
     making sure that the display is synchronized with the current
     state of the program. Calling `gdk-display-sync' before
     `gdk-error-trap-pop' makes sure that any errors generated from
     earlier requests are handled before the error trap is removed.

     This is most useful for X11. On windowing systems where requests
     are handled synchronously, this function will do nothing.

    DISPLAY
          a `<gdk-display>'


     Since 2.2


 -- Function: gdk-display-flush (self `<gdk-display>')
 -- Method: flush
     Flushes any requests queued for the windowing system; this happens
     automatically when the main loop blocks waiting for new events,
     but if your application is drawing without returning control to
     the main loop, you may need to call this function explicitely. A
     common case where this function needs to be called is when an
     application is executing drawing commands from a thread other than
     the thread where the main loop is running.

     This is most useful for X11. On windowing systems where requests
     are handled synchronously, this function will do nothing.

    DISPLAY
          a `<gdk-display>'


     Since 2.4


 -- Function: gdk-display-close (self `<gdk-display>')
 -- Method: close
     Closes the connection to the windowing system for the given
     display, and cleans up associated resources.

    DISPLAY
          a `<gdk-display>'


     Since 2.2


 -- Function: gdk-display-list-devices (self `<gdk-display>') => 
          (ret `glist-of')
 -- Method: list-devices
     Returns the list of available input devices attached to DISPLAY.
     The list is statically allocated and should not be freed.

    DISPLAY
          a `<gdk-display>'

    RET
          a list of `<gdk-device>'


     Since 2.2


 -- Function: gdk-display-get-event (self `<gdk-display>') => 
          (ret `<gdk-event>')
 -- Method: get-event
     Gets the next `<gdk-event>' to be processed for DISPLAY, fetching
     events from the windowing system if necessary.

    DISPLAY
          a `<gdk-display>'

    RET
          the next `<gdk-event>' to be processed, or ``#f'' if no events
          are pending. The returned `<gdk-event>' should be freed with
          `gdk-event-free'.


     Since 2.2


 -- Function: gdk-display-peek-event (self `<gdk-display>') => 
          (ret `<gdk-event>')
 -- Method: peek-event
     Gets a copy of the first `<gdk-event>' in the DISPLAY's event
     queue, without removing the event from the queue. (Note that this
     function will not get more events from the windowing system. It
     only checks the events that have already been moved to the GDK
     event queue.)

    DISPLAY
          a `<gdk-display>'

    RET
          a copy of the first `<gdk-event>' on the event queue, or
          ``#f'' if no events are in the queue. The returned
          `<gdk-event>' should be freed with `gdk-event-free'.


     Since 2.2


 -- Function: gdk-display-put-event (self `<gdk-display>')
          (event `<gdk-event>')
 -- Method: put-event
     Appends a copy of the given event onto the front of the event
     queue for DISPLAY.

    DISPLAY
          a `<gdk-display>'

    EVENT
          a `<gdk-event>'.


     Since 2.2


 -- Function: gdk-display-set-double-click-time (self `<gdk-display>')
          (msec `unsigned-int')
 -- Method: set-double-click-time
     Sets the double click time (two clicks within this time interval
     count as a double click and result in a `<gdk-2button-press>'
     event). Applications should _not_ set this, it is a global
     user-configured setting.

    DISPLAY
          a `<gdk-display>'

    MSEC
          double click time in milliseconds (thousandths of a second)


     Since 2.2


 -- Function: gdk-display-get-window-at-pointer (self `<gdk-display>')
          =>  (ret `<gdk-window>') (win_x `int') (win_y `int')
 -- Method: get-window-at-pointer
     Obtains the window underneath the mouse pointer, returning the
     location of that window in WIN-X, WIN-Y for SCREEN. Returns ``#f''
     if the window under the mouse pointer is not known to GDK (for
     example, belongs to another application).

    DISPLAY
          a `<gdk-display>'

    WIN-X
          return location for origin of the window under the pointer

    WIN-Y
          return location for origin of the window under the pointer

    RET
          the window under the mouse pointer, or ``#f''


     Since 2.2


 -- Function: gdk-display-warp-pointer (self `<gdk-display>')
          (screen `<gdk-screen>') (x `int') (y `int')
 -- Method: warp-pointer
     Warps the pointer of DISPLAY to the point X,Y on the screen
     SCREEN, unless the pointer is confined to a window by a grab, in
     which case it will be moved as far as allowed by the grab. Warping
     the pointer creates events as if the user had moved the mouse
     instantaneously to the destination.

     Note that the pointer should normally be under the control of the
     user. This function was added to cover some rare use cases like
     keyboard navigation support for the color picker in the
     `<gtk-color-selection-dialog>'.

    DISPLAY
          a `<gdk-display>'

    SCREEN
          the screen of DISPLAY to warp the pointer to

    X
          the x coordinate of the destination

    Y
          the y coordinate of the destination


     Since 2.8


 -- Function: gdk-display-supports-cursor-color (self `<gdk-display>')
          =>  (ret `bool')
 -- Method: supports-cursor-color
     Returns ``#t'' if multicolored cursors are supported on DISPLAY.
     Otherwise, cursors have only a forground and a background color.

    DISPLAY
          a `<gdk-display>'

    RET
          whether cursors can have multiple colors.


     Since 2.4


 -- Function: gdk-display-supports-cursor-alpha (self `<gdk-display>')
          =>  (ret `bool')
 -- Method: supports-cursor-alpha
     Returns ``#t'' if cursors can use an 8bit alpha channel on
     DISPLAY. Otherwise, cursors are restricted to bilevel alpha (i.e.
     a mask).

    DISPLAY
          a `<gdk-display>'

    RET
          whether cursors can have alpha channels.


     Since 2.4


 -- Function: gdk-display-get-default-cursor-size
          (self `<gdk-display>') =>  (ret `unsigned-int')
 -- Method: get-default-cursor-size
     Returns the default size to use for cursors on DISPLAY.

    DISPLAY
          a `<gdk-display>'

    RET
          the default cursor size.


     Since 2.4


 -- Function: gdk-display-get-maximal-cursor-size
          (self `<gdk-display>') =>  (width `unsigned-int')
          (height `unsigned-int')
 -- Method: get-maximal-cursor-size
     Gets the maximal size to use for cursors on DISPLAY.

    DISPLAY
          a `<gdk-display>'

    WIDTH
          the return location for the maximal cursor width

    HEIGHT
          the return location for the maximal cursor height


     Since 2.4


 -- Function: gdk-display-get-default-group (self `<gdk-display>') => 
          (ret `<gdk-window>')
 -- Method: get-default-group
     Returns the default group leader window for all toplevel windows on
     DISPLAY. This window is implicitly created by GDK. See
     `gdk-window-set-group'.

    DISPLAY
          a `<gdk-display>'

    RET
          The default group leader window for DISPLAY


     Since 2.4


 -- Function: gdk-display-supports-shapes (self `<gdk-display>') => 
          (ret `bool')
 -- Method: supports-shapes
     Returns ``#t'' if `gdk-window-shape-combine-mask' can be used to
     create shaped windows on DISPLAY.

    DISPLAY
          a `<gdk-display>'

    RET
          ``#t'' if shaped windows are supported


     Since 2.10


 -- Function: gdk-display-supports-input-shapes (self `<gdk-display>')
          =>  (ret `bool')
 -- Method: supports-input-shapes
     Returns ``#t'' if `gdk-window-input-shape-combine-mask' can be
     used to modify the input shape of windows on DISPLAY.

    DISPLAY
          a `<gdk-display>'

    RET
          ``#t'' if windows with modified input shape are supported


     Since 2.10



File: guile-gnome-gdk.info,  Node: GdkDisplayManager,  Next: GdkScreen,  Prev: GdkDisplay,  Up: Top

4 GdkDisplayManager
*******************

Maintains a list of all open s

4.1 Overview
============

The purpose of the `<gdk-display-manager>' singleton object is to offer
notification when displays appear or disappear or the default display
changes.

4.2 Usage
=========

 -- Class: <gdk-display-manager>
     Derives from `<gobject>'.

     This class defines the following properties:

    `default-display'
          The default display for GDK



 -- Signal on <gdk-display-manager>: display-opened
          (arg0 `<gdk-display>')
     The ::display_opened signal is emitted when a display is opened.

     Since 2.2


 -- Function: gdk-display-manager-get =>  (ret `<gdk-display-manager>')
     Returns the global `<gdk-display-manager>' singleton;
     `gdk-parse-pargs', `gdk-init', or `gdk-init-check' must have been
     called first.

    RET
          the singleton `<gdk-display-manager>' object.


     Since 2.2


 -- Function: gdk-display-manager-list-displays
          (self `<gdk-display-manager>') =>  (ret `gslist-of')
 -- Method: list-displays
     List all currently open displays.

    DISPLAY-MANAGER
          a `<gdk-display-manager>'

    RET
          a newly allocated `<gs-list>' of `<gdk-display>' objects.
          Free this list with `g-slist-free' when you are done with it.


     Since 2.2


 -- Function: gdk-display-get-core-pointer (self `<gdk-display>') => 
          (ret `<gdk-device>')
 -- Method: get-core-pointer
     Returns the core pointer device for the given display

    DISPLAY
          a `<gdk-display>'

    RET
          the core pointer device; this is owned by the display and
          should not be freed.


     Since 2.2



File: guile-gnome-gdk.info,  Node: GdkScreen,  Next: Points Rectangles and Regions,  Prev: GdkDisplayManager,  Up: Top

5 GdkScreen
***********

Object representing a physical screen

5.1 Overview
============

`<gdk-screen>' objects are the GDK representation of a physical screen.
It is used throughout GDK and GTK+ to specify which screen the top
level windows are to be displayed on. It is also used to query the
screen specification and default settings such as the default colormap
(`gdk-screen-get-default-colormap'), the screen width
(`gdk-screen-get-width'), etc.

   Note that a screen may consist of multiple monitors which are merged
to form a large screen area.

5.2 Usage
=========

 -- Class: <gdk-screen>
     Derives from `<gobject>'.

     This class defines the following properties:

    `font-options'
          The default font options for the screen

    `resolution'
          The resolution for fonts on the screen



 -- Signal on <gdk-screen>: size-changed
     The ::size_changed signal is emitted when the pixel width or
     height of a screen changes.

     Since 2.2


 -- Signal on <gdk-screen>: composited-changed
     The ::composited_changed signal is emitted when the composited
     status of the screen changes

     Since 2.10


 -- Function: gdk-screen-get-default =>  (ret `<gdk-screen>')
     Gets the default screen for the default display. (See
     `gdk-display-get-default').

    RET
          a `<gdk-screen>', or ``#f'' if there is no default display.


     Since 2.2


 -- Function: gdk-screen-get-default-colormap (self `<gdk-screen>') => 
          (ret `<gdk-colormap>')
 -- Method: get-default-colormap
     Gets the default colormap for SCREEN.

    SCREEN
          a `<gdk-screen>'

    RET
          the default `<gdk-colormap>'.


     Since 2.2


 -- Function: gdk-screen-set-default-colormap (self `<gdk-screen>')
          (colormap `<gdk-colormap>')
 -- Method: set-default-colormap
     Sets the default COLORMAP for SCREEN.

    SCREEN
          a `<gdk-screen>'

    COLORMAP
          a `<gdk-colormap>'


     Since 2.2


 -- Function: gdk-screen-get-system-colormap (self `<gdk-screen>') => 
          (ret `<gdk-colormap>')
 -- Method: get-system-colormap
     Gets the system's default colormap for SCREEN

    SCREEN
          a `<gdk-screen>'

    RET
          the default colormap for SCREEN.


     Since 2.2


 -- Function: gdk-screen-get-system-visual (self `<gdk-screen>') => 
          (ret `<gdk-visual>')
 -- Method: get-system-visual
     Get the system's default visual for SCREEN. This is the visual for
     the root window of the display. The return value should not be
     freed.

    SCREEN
          a `<gdk-screen>'.

    RET
          the system visual


     Since 2.2


 -- Function: gdk-screen-get-rgb-colormap (self `<gdk-screen>') => 
          (ret `<gdk-colormap>')
 -- Method: get-rgb-colormap
     Gets the preferred colormap for rendering image data on SCREEN.
     Not a very useful function; historically, GDK could only render
     RGB image data to one colormap and visual, but in the current
     version it can render to any colormap and visual. So there's no
     need to call this function.

    SCREEN
          a `<gdk-screen>'.

    RET
          the preferred colormap


     Since 2.2


 -- Function: gdk-screen-get-rgb-visual (self `<gdk-screen>') => 
          (ret `<gdk-visual>')
 -- Method: get-rgb-visual
     Gets a "preferred visual" chosen by GdkRGB for rendering image
     data on SCREEN. In previous versions of GDK, this was the only
     visual GdkRGB could use for rendering. In current versions, it's
     simply the visual GdkRGB would have chosen as the optimal one in
     those previous versions. GdkRGB can now render to drawables with
     any visual.

    SCREEN
          a `<gdk-screen>'

    RET
          The `<gdk-visual>' chosen by GdkRGB.


     Since 2.2


 -- Function: gdk-screen-get-rgba-colormap (self `<gdk-screen>') => 
          (ret `<gdk-colormap>')
 -- Method: get-rgba-colormap
     Gets a colormap to use for creating windows or pixmaps with an
     alpha channel.  The windowing system on which GTK+ is running may
     not support this capability, in which case ``#f'' will be
     returned. Even if a non-``#f'' value is returned, its possible
     that the window's alpha channel won't be honored when displaying
     the window on the screen: in particular, for X an appropriate
     windowing manager and compositing manager must be running to
     provide appropriate display.

    SCREEN
          a `<gdk-screen>'.

    RET
          a colormap to use for windows with an alpha channel or ``#f''
          if the capability is not available.


     Since 2.8


 -- Function: gdk-screen-get-rgba-visual (self `<gdk-screen>') => 
          (ret `<gdk-visual>')
 -- Method: get-rgba-visual
     Gets a visual to use for creating windows or pixmaps with an alpha
     channel. See the docs for `gdk-screen-get-rgba-colormap' for
     caveats.

    SCREEN
          a `<gdk-screen>'

    RET
          a visual to use for windows with an alpha channel or ``#f''
          if the capability is not available.


     Since 2.8


 -- Function: gdk-screen-is-composited (self `<gdk-screen>') => 
          (ret `bool')
 -- Method: is-composited
     Returns whether windows with an RGBA visual can reasonably be
     expected to have their alpha channel drawn correctly on the screen.

     On X11 this function returns whether a compositing manager is
     compositing SCREEN.

    SCREEN
          a `<gdk-screen>'

    RET
          Whether windows with RGBA visuals can reasonably be expected
          to have their alpha channels drawn correctly on the screen.


     Since 2.10


 -- Function: gdk-screen-get-root-window (self `<gdk-screen>') => 
          (ret `<gdk-window>')
 -- Method: get-root-window
     Gets the root window of SCREEN.

    SCREEN
          a `<gdk-screen>'

    RET
          the root window


     Since 2.2


 -- Function: gdk-screen-get-display (self `<gdk-screen>') => 
          (ret `<gdk-display>')
 -- Method: get-display
     Gets the display to which the SCREEN belongs.

    SCREEN
          a `<gdk-screen>'

    RET
          the display to which SCREEN belongs


     Since 2.2


 -- Function: gdk-screen-get-number (self `<gdk-screen>') => 
          (ret `int')
 -- Method: get-number
     Gets the index of SCREEN among the screens in the display to which
     it belongs. (See `gdk-screen-get-display')

    SCREEN
          a `<gdk-screen>'

    RET
          the index


     Since 2.2


 -- Function: gdk-screen-get-width (self `<gdk-screen>') =>  (ret `int')
 -- Method: get-width
     Gets the width of SCREEN in pixels

    SCREEN
          a `<gdk-screen>'

    RET
          the width of SCREEN in pixels.


     Since 2.2


 -- Function: gdk-screen-get-height (self `<gdk-screen>') => 
          (ret `int')
 -- Method: get-height
     Gets the height of SCREEN in pixels

    SCREEN
          a `<gdk-screen>'

    RET
          the height of SCREEN in pixels.


     Since 2.2


 -- Function: gdk-screen-get-width-mm (self `<gdk-screen>') => 
          (ret `int')
 -- Method: get-width-mm
     Gets the width of SCREEN in millimeters. Note that on some X
     servers this value will not be correct.

    SCREEN
          a `<gdk-screen>'

    RET
          the width of SCREEN in millimeters.


     Since 2.2


 -- Function: gdk-screen-get-height-mm (self `<gdk-screen>') => 
          (ret `int')
 -- Method: get-height-mm
     Returns the height of SCREEN in millimeters. Note that on some X
     servers this value will not be correct.

    SCREEN
          a `<gdk-screen>'

    RET
          the heigth of SCREEN in millimeters.


     Since 2.2


 -- Function: gdk-screen-list-visuals (self `<gdk-screen>') => 
          (ret `glist-of')
 -- Method: list-visuals
     Lists the available visuals for the specified SCREEN. A visual
     describes a hardware image data format. For example, a visual
     might support 24-bit color, or 8-bit color, and might expect
     pixels to be in a certain format.

     Call `g-list-free' on the return value when you're finished with
     it.

    SCREEN
          the relevant `<gdk-screen>'.

    RET
          a list of visuals; the list must be freed, but not its
          contents


     Since 2.2


 -- Function: gdk-screen-get-toplevel-windows (self `<gdk-screen>') => 
          (ret `glist-of')
 -- Method: get-toplevel-windows
     Obtains a list of all toplevel windows known to GDK on the screen
     SCREEN.  A toplevel window is a child of the root window (see
     `gdk-get-default-root-window').

     The returned list should be freed with `g-list-free', but its
     elements need not be freed.

    SCREEN
          The `<gdk-screen>' where the toplevels are located.

    RET
          list of toplevel windows, free with `g-list-free'


     Since 2.2


 -- Function: gdk-screen-make-display-name (self `<gdk-screen>') => 
          (ret `mchars')
 -- Method: make-display-name
     Determines the name to pass to `gdk-display-open' to get a
     `<gdk-display>' with this screen as the default screen.

    SCREEN
          a `<gdk-screen>'

    RET
          a newly allocated string, free with `g-free'


     Since 2.2


 -- Function: gdk-screen-get-n-monitors (self `<gdk-screen>') => 
          (ret `int')
 -- Method: get-n-monitors
     Returns the number of monitors which SCREEN consists of.

    SCREEN
          a `<gdk-screen>'.

    RET
          number of monitors which SCREEN consists of.


     Since 2.2


 -- Function: gdk-screen-get-monitor-geometry (self `<gdk-screen>')
          (monitor_num `int') (dest `<gdk-rectangle>')
 -- Method: get-monitor-geometry
     Retrieves the `<gdk-rectangle>' representing the size and position
     of the individual monitor within the entire screen area.

     Note that the size of the entire screen area can be retrieved via
     `gdk-screen-get-width' and `gdk-screen-get-height'.

    SCREEN
          a `<gdk-screen>'.

    MONITOR-NUM
          the monitor number.

    DEST
          a `<gdk-rectangle>' to be filled with the monitor geometry


     Since 2.2


 -- Function: gdk-screen-get-monitor-at-point (self `<gdk-screen>')
          (x `int') (y `int') =>  (ret `int')
 -- Method: get-monitor-at-point
     Returns the monitor number in which the point (X,Y) is located.

    SCREEN
          a `<gdk-screen>'.

    X
          the x coordinate in the virtual screen.

    Y
          the y coordinate in the virtual screen.

    RET
          the monitor number in which the point (X,Y) lies, or a
          monitor close to (X,Y) if the point is not in any monitor.


     Since 2.2


 -- Function: gdk-screen-get-monitor-at-window (self `<gdk-screen>')
          (window `<gdk-window>') =>  (ret `int')
 -- Method: get-monitor-at-window
     Returns the number of the monitor in which the largest area of the
     bounding rectangle of WINDOW resides.

    SCREEN
          a `<gdk-screen>'.

    WINDOW
          a `<gdk-window>'

    RET
          the monitor number in which most of WINDOW is located, or if
          WINDOW does not intersect any monitors, a monitor, close to
          WINDOW.


     Since 2.2


 -- Function: gdk-screen-broadcast-client-message (self `<gdk-screen>')
          (event `<gdk-event>')
 -- Method: broadcast-client-message
     On X11, sends an X ClientMessage event to all toplevel windows on
     SCREEN.

     Toplevel windows are determined by checking for the WM_STATE
     property, as described in the Inter-Client Communication
     Conventions Manual (ICCCM). If no windows are found with the
     WM_STATE property set, the message is sent to all children of the
     root window.

     On Windows, broadcasts a message registered with the name
     GDK_WIN32_CLIENT_MESSAGE to all top-level windows. The amount of
     data is limited to one long, i.e. four bytes.

    SCREEN
          the `<gdk-screen>' where the event will be broadcasted.

    EVENT
          the `<gdk-event>'.


     Since 2.2


 -- Function: gdk-screen-get-setting (self `<gdk-screen>')
          (name `mchars') (value `<gvalue>') =>  (ret `bool')
 -- Method: get-setting
     Retrieves a desktop-wide setting such as double-click time for the
     `<gdk-screen>'SCREEN.

     FIXME needs a list of valid settings here, or a link to more
     information.

    SCREEN
          the `<gdk-screen>' where the setting is located

    NAME
          the name of the setting

    VALUE
          location to store the value of the setting

    RET
          ``#t'' if the setting existed and a value was stored in VALUE,
          ``#f'' otherwise.


     Since 2.2


 -- Function: gdk-screen-get-font-options (self `<gdk-screen>') => 
          (ret `cairo-font-options-t')
 -- Method: get-font-options
     Gets any options previously set with `gdk-screen-set-font-options'.

    SCREEN
          a `<gdk-screen>'

    RET
          the current font options, or ``#f'' if no default font
          options have been set.


     Since 2.10


 -- Function: gdk-screen-set-font-options (self `<gdk-screen>')
          (options `cairo-font-options-t')
 -- Method: set-font-options
     Sets the default font options for the screen. These options will
     be set on any `<pango-context>''s newly created with
     `gdk-pango-context-get-for-screen'. Changing the default set of
     font options does not affect contexts that have already been
     created.

    SCREEN
          a `<gdk-screen>'

    OPTIONS
          a `<cairo-font-options-t>', or ``#f'' to unset any previously
          set default font options.


     Since 2.10


 -- Function: gdk-screen-get-resolution (self `<gdk-screen>') => 
          (ret `double')
 -- Method: get-resolution
     Gets the resolution for font handling on the screen; see
     `gdk-screen-set-resolution' for full details.

    SCREEN
          a `<gdk-screen>'

    RET
          the current resolution, or -1 if no resolution has been set.


     Since 2.10


 -- Function: gdk-screen-set-resolution (self `<gdk-screen>')
          (dpi `double')
 -- Method: set-resolution
     Sets the resolution for font handling on the screen. This is a
     scale factor between points specified in a
     `<pango-font-description>' and cairo units.  The default value is
     96, meaning that a 10 point font will be 13 units high. (10 * 96.
     / 72. = 13.3).

    SCREEN
          a `<gdk-screen>'

    DPI
          the resolution in "dots per inch". (Physical inches aren't
          actually involved; the terminology is conventional.)


     Since 2.10


 -- Function: gdk-screen-get-active-window (self `<gdk-screen>') => 
          (ret `<gdk-window>')
 -- Method: get-active-window
     Returns the screen's currently active window.

     On X11, this is done by inspecting the _NET_ACTIVE_WINDOW property
     on the root window, as described in the Extended Window Manager
     Hints (http://www.freedesktop.org/Standards/wm-spec). If there is
     no currently currently active window, or the window manager does
     not support the _NET_ACTIVE_WINDOW hint, this function returns
     ``#f''.

     On other platforms, this function may return ``#f'', depending on
     whether it is implementable on that platform.

     The returned window should be unrefed using `g-object-unref' when
     no longer needed.

    SCREEN
          a `<gdk-screen>'

    RET
          the currently active window, or ``#f''.


     Since 2.10


 -- Function: gdk-screen-get-window-stack (self `<gdk-screen>') => 
          (ret `glist-of')
 -- Method: get-window-stack
     Returns a `<g-list>' of `<gdk-window>'s representing the current
     window stack.

     On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING
     property on the root window, as described in the Extended Window
     Manager Hints (http://www.freedesktop.org/Standards/wm-spec). If
     the window manager does not support the _NET_CLIENT_LIST_STACKING
     hint, this function returns ``#f''.

     On other platforms, this function may return ``#f'', depending on
     whether it is implementable on that platform.

     The returned list is newly allocated and owns references to the
     windows it contains, so it should be freed using `g-list-free' and
     its windows unrefed using `g-object-unref' when no longer needed.

    SCREEN
          a `<gdk-screen>'

    RET
          a list of `<gdk-window>'s for the current window stack, or
          ``#f''.


     Since 2.10


 -- Function: gdk-spawn-command-line-on-screen (screen `<gdk-screen>')
          (command_line `mchars') =>  (ret `bool')
     Like `g-spawn-command-line-async', except the child process is
     spawned in such an environment that on calling `gdk-display-open'
     it would be returned a `<gdk-display>' with SCREEN as the default
     screen.

     This is useful for applications which wish to launch an
     application on a specific screen.

    SCREEN
          a `<gdk-screen>'

    COMMAND-LINE
          a command line

    ERROR
          return location for errors

    RET
          ``#t'' on success, ``#f'' if error is set.


     Since 2.4



File: guile-gnome-gdk.info,  Node: Points Rectangles and Regions,  Next: Graphics Contexts,  Prev: GdkScreen,  Up: Top

6 Points, Rectangles and Regions
********************************

Simple graphical data types

6.1 Overview
============

GDK provides the `<gdk-point>', `<gdk-rectangle>', `<gdk-region>' and
`<gdk-span>' data types for representing pixels and sets of pixels on
the screen.

   `<gdk-point>' is a simple structure containing an x and y coordinate
of a point.

   `<gdk-rectangle>' is a structure holding the position and size of a
rectangle. The intersection of two rectangles can be computed with
`gdk-rectangle-intersect'. To find the union of two rectangles use
`gdk-rectangle-union'.

   `<gdk-region>' is an opaque data type holding a set of arbitrary
pixels, and is usually used for clipping graphical operations (see
`gdk-gc-set-clip-region').

   `<gdk-span>' is a structure holding a spanline. A spanline is a
horizontal line that is one pixel wide. It is mainly used when
rasterizing other graphics primitives. It can be intersected to regions
by using `gdk-region-spans-intersect-foreach'.

6.2 Usage
=========

 -- Class: <gdk-rectangle>
     Derives from `<gboxed>'.


 -- Class: <gdk-region>
     Opaque pointer.


 -- Function: gdk-region-new =>  (ret `<gdk-region>')
     Creates a new empty `<gdk-region>'.

    RET
          a new empty `<gdk-region>'



 -- Function: gdk-region-copy (self `<gdk-region>') => 
          (ret `<gdk-region>')
     Copies REGION, creating an identical new region.

    REGION
          a `<gdk-region>'

    RET
          a new region identical to REGION



 -- Function: gdk-region-rectangle (rectangle `<gdk-rectangle>') => 
          (ret `<gdk-region>')
     Creates a new region containing the area RECTANGLE.

    RECTANGLE
          a `<gdk-rectangle>'

    RET
          a new region



 -- Function: gdk-region-destroy (self `<gdk-region>')
     Destroys a `<gdk-region>'.

    REGION
          a `<gdk-region>'



 -- Function: gdk-region-empty (self `<gdk-region>') =>  (ret `bool')
     Finds out if the `<gdk-region>' is empty.

    REGION
          a `<gdk-region>'

    RET
          ``#t'' if REGION is empty.



 -- Function: gdk-region-equal (self `<gdk-region>')
          (region2 `<gdk-region>') =>  (ret `bool')
     Finds out if the two regions are the same.

    REGION1
          a `<gdk-region>'

    REGION2
          a `<gdk-region>'

    RET
          ``#t'' if REGION1 and REGION2 are equal.



 -- Function: gdk-region-point-in (self `<gdk-region>') (x `int')
          (y `int') =>  (ret `bool')
     Finds out if a point is in a region.

    REGION
          a `<gdk-region>'

    X
          the x coordinate of a point

    Y
          the y coordinate of a point

    RET
          ``#t'' if the point is in REGION.



 -- Function: gdk-region-rect-in (self `<gdk-region>')
          (rectangle `<gdk-rectangle>') =>  (ret `<gdk-overlap-type>')
     Tests whether a rectangle is within a region.

    REGION
          a `<gdk-region>'.

    RECTANGLE
          a `<gdk-rectangle>'.

    RET
          `GDK_OVERLAP_RECTANGLE_IN', `GDK_OVERLAP_RECTANGLE_OUT', or
          `GDK_OVERLAP_RECTANGLE_PART', depending on whether the
          rectangle is inside, outside, or partly inside the
          `<gdk-region>', respectively.



 -- Function: gdk-region-offset (self `<gdk-region>') (dx `int')
          (dy `int')
     Moves a region the specified distance.

    REGION
          a `<gdk-region>'

    DX
          the distance to move the region horizontally

    DY
          the distance to move the region vertically



 -- Function: gdk-region-shrink (self `<gdk-region>') (dx `int')
          (dy `int')
     Resizes a region by the specified amount. Positive values shrink
     the region.  Negative values expand it.

    REGION
          a `<gdk-region>'

    DX
          the number of pixels to shrink the region horizontally

    DY
          the number of pixels to shrink the region vertically



 -- Function: gdk-region-union-with-rect (self `<gdk-region>')
          (rect `<gdk-rectangle>')
     Sets the area of REGION to the union of the areas of REGION and
     RECT. The resulting area is the set of pixels contained in either
     REGION or RECT.

    REGION
          a `<gdk-region>'.

    RECT
          a `<gdk-rectangle>'.



 -- Function: gdk-region-intersect (self `<gdk-region>')
          (source2 `<gdk-region>')
     Sets the area of SOURCE1 to the intersection of the areas of
     SOURCE1 and SOURCE2. The resulting area is the set of pixels
     contained in both SOURCE1 and SOURCE2.

    SOURCE1
          a `<gdk-region>'

    SOURCE2
          another `<gdk-region>'



 -- Function: gdk-region-union (self `<gdk-region>')
          (source2 `<gdk-region>')
     Sets the area of SOURCE1 to the union of the areas of SOURCE1 and
     SOURCE2. The resulting area is the set of pixels contained in
     either SOURCE1 or SOURCE2.

    SOURCE1
          a `<gdk-region>'

    SOURCE2
          a `<gdk-region>'



 -- Function: gdk-region-subtract (self `<gdk-region>')
          (source2 `<gdk-region>')
     Subtracts the area of SOURCE2 from the area SOURCE1. The resulting
     area is the set of pixels contained in SOURCE1 but not in SOURCE2.

    SOURCE1
          a `<gdk-region>'

    SOURCE2
          another `<gdk-region>'



 -- Function: gdk-region-xor (self `<gdk-region>')
          (source2 `<gdk-region>')
     Sets the area of SOURCE1 to the exclusive-OR of the areas of
     SOURCE1 and SOURCE2. The resulting area is the set of pixels
     contained in one or the other of the two sources but not in both.

    SOURCE1
          a `<gdk-region>'

    SOURCE2
          another `<gdk-region>'




File: guile-gnome-gdk.info,  Node: Graphics Contexts,  Next: Drawing Primitives,  Prev: Points Rectangles and Regions,  Up: Top

7 Graphics Contexts
*******************

Objects to encapsulate drawing properties

7.1 Overview
============

All drawing operations in GDK take a "graphics context" (GC) argument. A
graphics context encapsulates information about the way things are
drawn, such as the foreground color or line width. By using graphics
contexts, the number of arguments to each drawing call is greatly
reduced, and communication overhead is minimized, since identical
arguments do not need to be passed repeatedly.

   Most values of a graphics context can be set at creation time by
using `gdk-gc-new-with-values', or can be set one-by-one using
functions such as `gdk-gc-set-foreground'. A few of the values in the
GC, such as the dash pattern, can only be set by the latter method.

7.2 Usage
=========

 -- Class: <gdk-gc>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-gc-new (drawable `<gdk-drawable>') => 
          (ret `<gdk-gc>')
     Create a new graphics context with default values.

    DRAWABLE
          a `<gdk-drawable>'. The created GC must always be used with
          drawables of the same depth as this one.

    RET
          the new graphics context.



 -- Function: gdk-gc-get-screen (self `<gdk-gc>') => 
          (ret `<gdk-screen>')
 -- Method: get-screen
     Gets the `<gdk-screen>' for which GC was created

    GC
          a `<gdk-gc>'.

    RET
          the `<gdk-screen>' for GC.


     Since 2.2


 -- Function: gdk-gc-set-foreground (self `<gdk-gc>')
          (color `<gdk-color>')
 -- Method: set-foreground
     Sets the foreground color for a graphics context. Note that this
     function uses COLOR->PIXEL, use `gdk-gc-set-rgb-fg-color' to
     specify the foreground color as red, green, blue components.

    GC
          a `<gdk-gc>'.

    COLOR
          the new foreground color.



 -- Function: gdk-gc-set-background (self `<gdk-gc>')
          (color `<gdk-color>')
 -- Method: set-background
     Sets the background color for a graphics context. Note that this
     function uses COLOR->PIXEL, use `gdk-gc-set-rgb-bg-color' to
     specify the background color as red, green, blue components.

    GC
          a `<gdk-gc>'.

    COLOR
          the new background color.



 -- Function: gdk-gc-set-rgb-fg-color (self `<gdk-gc>')
          (color `<gdk-color>')
 -- Method: set-rgb-fg-color
     Set the foreground color of a GC using an unallocated color. The
     pixel value for the color will be determined using GdkRGB. If the
     colormap for the GC has not previously been initialized for
     GdkRGB, then for pseudo-color colormaps (colormaps with a small
     modifiable number of colors), a colorcube will be allocated in the
     colormap.

     Calling this function for a GC without a colormap is an error.

    GC
          a `<gdk-gc>'

    COLOR
          an unallocated `<gdk-color>'.



 -- Function: gdk-gc-set-rgb-bg-color (self `<gdk-gc>')
          (color `<gdk-color>')
 -- Method: set-rgb-bg-color
     Set the background color of a GC using an unallocated color. The
     pixel value for the color will be determined using GdkRGB. If the
     colormap for the GC has not previously been initialized for
     GdkRGB, then for pseudo-color colormaps (colormaps with a small
     modifiable number of colors), a colorcube will be allocated in the
     colormap.

     Calling this function for a GC without a colormap is an error.

    GC
          a `<gdk-gc>'

    COLOR
          an unallocated `<gdk-color>'.



 -- Function: gdk-gc-set-font (self `<gdk-gc>') (font `<gdk-font>')
 -- Method: set-font
     `gdk_gc_set_font' is deprecated and should not be used in
     newly-written code.

     Sets the font for a graphics context. (Note that all text-drawing
     functions in GDK take a FONT argument; the value set here is used
     when that argument is ``#f''.)

    GC
          a `<gdk-gc>'.

    FONT
          the new font.



 -- Function: gdk-gc-set-function (self `<gdk-gc>')
          (function `<gdk-function>')
 -- Method: set-function
     Determines how the current pixel values and the pixel values being
     drawn are combined to produce the final pixel values.

    GC
          a `<gdk-gc>'.

    FUNCTION
          the `<gdk-function>' to use



 -- Function: gdk-gc-set-fill (self `<gdk-gc>') (fill `<gdk-fill>')
 -- Method: set-fill
     Set the fill mode for a graphics context.

    GC
          a `<gdk-gc>'.

    FILL
          the new fill mode.



 -- Function: gdk-gc-set-tile (self `<gdk-gc>') (tile `<gdk-pixmap>')
 -- Method: set-tile
     Set a tile pixmap for a graphics context. This will only be used
     if the fill mode is `GDK_TILED'.

    GC
          a `<gdk-gc>'.

    TILE
          the new tile pixmap.



 -- Function: gdk-gc-set-stipple (self `<gdk-gc>')
          (stipple `<gdk-pixmap>')
 -- Method: set-stipple
     Set the stipple bitmap for a graphics context. The stipple will
     only be used if the fill mode is `GDK_STIPPLED' or
     `GDK_OPAQUE_STIPPLED'.

    GC
          a `<gdk-gc>'.

    STIPPLE
          the new stipple bitmap.



 -- Function: gdk-gc-set-ts-origin (self `<gdk-gc>') (x `int') (y `int')
 -- Method: set-ts-origin
     Set the origin when using tiles or stipples with the GC. The tile
     or stipple will be aligned such that the upper left corner of the
     tile or stipple will coincide with this point.

    GC
          a `<gdk-gc>'.

    X
          the x-coordinate of the origin.

    Y
          the y-coordinate of the origin.



 -- Function: gdk-gc-set-clip-origin (self `<gdk-gc>') (x `int')
          (y `int')
 -- Method: set-clip-origin
     Sets the origin of the clip mask. The coordinates are interpreted
     relative to the upper-left corner of the destination drawable of
     the current operation.

    GC
          a `<gdk-gc>'.

    X
          the x-coordinate of the origin.

    Y
          the y-coordinate of the origin.



 -- Function: gdk-gc-set-clip-mask (self `<gdk-gc>')
          (mask `<gdk-drawable>')
 -- Method: set-clip-mask
     Sets the clip mask for a graphics context from a bitmap. The clip
     mask is interpreted relative to the clip origin. (See
     `gdk-gc-set-clip-origin').

    GC
          the `<gdk-gc>'.

    MASK
          a bitmap.



 -- Function: gdk-gc-set-clip-rectangle (self `<gdk-gc>')
          (rectangle `<gdk-rectangle>')
 -- Method: set-clip-rectangle
     Sets the clip mask for a graphics context from a rectangle. The
     clip mask is interpreted relative to the clip origin. (See
     `gdk-gc-set-clip-origin').

    GC
          a `<gdk-gc>'.

    RECTANGLE
          the rectangle to clip to.



 -- Function: gdk-gc-set-clip-region (self `<gdk-gc>')
          (region `<gdk-region>')
 -- Method: set-clip-region
     Sets the clip mask for a graphics context from a region structure.
     The clip mask is interpreted relative to the clip origin. (See
     `gdk-gc-set-clip-origin').

    GC
          a `<gdk-gc>'.

    REGION
          the `<gdk-region>'.



 -- Function: gdk-gc-set-subwindow (self `<gdk-gc>')
          (mode `<gdk-subwindow-mode>')
 -- Method: set-subwindow
     Sets how drawing with this GC on a window will affect child
     windows of that window.

    GC
          a `<gdk-gc>'.

    MODE
          the subwindow mode.



 -- Function: gdk-gc-set-exposures (self `<gdk-gc>') (exposures `bool')
 -- Method: set-exposures
     Sets whether copying non-visible portions of a drawable using this
     graphics context generate exposure events for the corresponding
     regions of the destination drawable. (See `gdk-draw-drawable').

    GC
          a `<gdk-gc>'.

    EXPOSURES
          if ``#t'', exposure events will be generated.



 -- Function: gdk-gc-set-line-attributes (self `<gdk-gc>')
          (line_width `int') (line_style `<gdk-line-style>')
          (cap_style `<gdk-cap-style>') (join_style `<gdk-join-style>')
 -- Method: set-line-attributes
     Sets various attributes of how lines are drawn. See the
     corresponding members of `<gdk-gc-values>' for full explanations
     of the arguments.

    GC
          a `<gdk-gc>'.

    LINE-WIDTH
          the width of lines.

    LINE-STYLE
          the dash-style for lines.

    CAP-STYLE
          the manner in which the ends of lines are drawn.

    JOIN-STYLE
          the in which lines are joined together.



 -- Function: gdk-gc-copy (self `<gdk-gc>') (src_gc `<gdk-gc>')
 -- Method: copy
     Copy the set of values from one graphics context onto another
     graphics context.

    DST-GC
          the destination graphics context.

    SRC-GC
          the source graphics context.



 -- Function: gdk-gc-set-colormap (self `<gdk-gc>')
          (colormap `<gdk-colormap>')
 -- Method: set-colormap
     Sets the colormap for the GC to the given colormap. The depth of
     the colormap's visual must match the depth of the drawable for
     which the GC was created.

    GC
          a `<gdk-gc>'

    COLORMAP
          a `<gdk-colormap>'



 -- Function: gdk-gc-get-colormap (self `<gdk-gc>') => 
          (ret `<gdk-colormap>')
 -- Method: get-colormap
     Retrieves the colormap for a given GC, if it exists. A GC will
     have a colormap if the drawable for which it was created has a
     colormap, or if a colormap was set explicitely with
     gdk_gc_set_colormap.

    GC
          a `<gdk-gc>'

    RET
          the colormap of GC, or ``#f'' if GC doesn't have one.



 -- Function: gdk-gc-offset (self `<gdk-gc>') (x_offset `int')
          (y_offset `int')
 -- Method: offset
     Offset attributes such as the clip and tile-stipple origins of the
     GC so that drawing at x - x_offset, y - y_offset with the offset
     GC has the same effect as drawing at x, y with the original GC.

    GC
          a `<gdk-gc>'

    X-OFFSET
          amount by which to offset the GC in the X direction

    Y-OFFSET
          amount by which to offset the GC in the Y direction




File: guile-gnome-gdk.info,  Node: Drawing Primitives,  Next: Bitmaps and Pixmaps,  Prev: Graphics Contexts,  Up: Top

8 Drawing Primitives
********************

Functions for drawing points, lines, arcs, and text

8.1 Overview
============

These functions provide support for drawing points, lines, arcs and
text onto what are called 'drawables'. Drawables, as the name suggests,
are things which support drawing onto them, and are either
`<gdk-window>' or `<gdk-pixmap>' objects.

   Many of the drawing operations take a `<gdk-gc>' argument, which
represents a graphics context. This `<gdk-gc>' contains a number of
drawing attributes such as foreground color, background color and line
width, and is used to reduce the number of arguments needed for each
drawing operation. See the Graphics Contexts section for more
information.

   Some of the drawing operations take Pango data structures like
`<pango-context>', `<pango-layout>' or `<pango-layout-line>' as
arguments. If you're using GTK+, the ususal way to obtain these
structures is via `gtk-widget-create-pango-context' or
`gtk-widget-create-pango-layout'.

8.2 Usage
=========

 -- Class: <gdk-drawable>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-drawable-get-display (self `<gdk-drawable>') => 
          (ret `<gdk-display>')
 -- Method: get-display
     Gets the `<gdk-display>' associated with a `<gdk-drawable>'.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          the `<gdk-display>' associated with DRAWABLE


     Since 2.2


 -- Function: gdk-drawable-get-screen (self `<gdk-drawable>') => 
          (ret `<gdk-screen>')
 -- Method: get-screen
     Gets the `<gdk-screen>' associated with a `<gdk-drawable>'.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          the `<gdk-screen>' associated with DRAWABLE


     Since 2.2


 -- Function: gdk-drawable-get-visual (self `<gdk-drawable>') => 
          (ret `<gdk-visual>')
 -- Method: get-visual
     Gets the `<gdk-visual>' describing the pixel format of DRAWABLE.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          a `<gdk-visual>'



 -- Function: gdk-drawable-set-colormap (self `<gdk-drawable>')
          (colormap `<gdk-colormap>')
 -- Method: set-colormap
     Sets the colormap associated with DRAWABLE. Normally this will
     happen automatically when the drawable is created; you only need
     to use this function if the drawable-creating function did not
     have a way to determine the colormap, and you then use drawable
     operations that require a colormap. The colormap for all drawables
     and graphics contexts you intend to use together should match.
     i.e. when using a `<gdk-gc>' to draw to a drawable, or copying one
     drawable to another, the colormaps should match.

    DRAWABLE
          a `<gdk-drawable>'

    COLORMAP
          a `<gdk-colormap>'



 -- Function: gdk-drawable-get-colormap (self `<gdk-drawable>') => 
          (ret `<gdk-colormap>')
 -- Method: get-colormap
     Gets the colormap for DRAWABLE, if one is set; returns ``#f''
     otherwise.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          the colormap, or ``#f''



 -- Function: gdk-drawable-get-depth (self `<gdk-drawable>') => 
          (ret `int')
 -- Method: get-depth
     Obtains the bit depth of the drawable, that is, the number of bits
     that make up a pixel in the drawable's visual. Examples are 8 bits
     per pixel, 24 bits per pixel, etc.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          number of bits per pixel



 -- Function: gdk-drawable-get-size (self `<gdk-drawable>') => 
          (width `int') (height `int')
 -- Method: get-size
     Fills *WIDTH and *HEIGHT with the size of DRAWABLE.  WIDTH or
     HEIGHT can be ``#f'' if you only want the other one.

     On the X11 platform, if DRAWABLE is a `<gdk-window>', the returned
     size is the size reported in the most-recently-processed configure
     event, rather than the current size on the X server.

    DRAWABLE
          a `<gdk-drawable>'

    WIDTH
          location to store drawable's width, or ``#f''

    HEIGHT
          location to store drawable's height, or ``#f''



 -- Function: gdk-drawable-get-clip-region (self `<gdk-drawable>') => 
          (ret `<gdk-region>')
 -- Method: get-clip-region
     Computes the region of a drawable that potentially can be written
     to by drawing primitives. This region will not take into account
     the clip region for the GC, and may also not take into account
     other factors such as if the window is obscured by other windows,
     but no area outside of this region will be affected by drawing
     primitives.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          a `<gdk-region>'. This must be freed with
          `gdk-region-destroy' when you are done.



 -- Function: gdk-drawable-get-visible-region (self `<gdk-drawable>')
          =>  (ret `<gdk-region>')
 -- Method: get-visible-region
     Computes the region of a drawable that is potentially visible.
     This does not necessarily take into account if the window is
     obscured by other windows, but no area outside of this region is
     visible.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          a `<gdk-region>'. This must be freed with
          `gdk-region-destroy' when you are done.



 -- Function: gdk-draw-point (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int')
     Draws a point, using the foreground color and other attributes of
     the `<gdk-gc>'.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    GC
          a `<gdk-gc>'.

    X
          the x coordinate of the point.

    Y
          the y coordinate of the point.



 -- Function: gdk-draw-line (drawable `<gdk-drawable>') (gc `<gdk-gc>')
          (x1_ `int') (y1_ `int') (x2_ `int') (y2_ `int')
     Draws a line, using the foreground color and other attributes of
     the `<gdk-gc>'.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    GC
          a `<gdk-gc>'.

    X1
          the x coordinate of the start point.

    Y1
          the y coordinate of the start point.

    X2
          the x coordinate of the end point.

    Y2
          the y coordinate of the end point.



 -- Function: gdk-draw-pixbuf (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (pixbuf `<gdk-pixbuf>') (src_x `int')
          (src_y `int') (dest_x `int') (dest_y `int') (width `int')
          (height `int') (dither `<gdk-rgb-dither>') (x_dither `int')
          (y_dither `int')
     Renders a rectangular portion of a pixbuf to a drawable. The
     destination drawable must have a colormap. All windows have a
     colormap, however, pixmaps only have colormap by default if they
     were created with a non-``#f'' window argument. Otherwise a
     colormap must be set on them with `gdk-drawable-set-colormap'.

     On older X servers, rendering pixbufs with an alpha channel
     involves round trips to the X server, and may be somewhat slow.

     The clip mask of GC is ignored, but clip rectangles and clip
     regions work fine.

    DRAWABLE
          Destination drawable.

    GC
          a `<gdk-gc>', used for clipping, or ``#f''

    PIXBUF
          a `<gdk-pixbuf>'

    SRC-X
          Source X coordinate within pixbuf.

    SRC-Y
          Source Y coordinates within pixbuf.

    DEST-X
          Destination X coordinate within drawable.

    DEST-Y
          Destination Y coordinate within drawable.

    WIDTH
          Width of region to render, in pixels, or -1 to use pixbuf
          width.

    HEIGHT
          Height of region to render, in pixels, or -1 to use pixbuf
          height.

    DITHER
          Dithering mode for `<gdk-rgb>'.

    X-DITHER
          X offset for dither.

    Y-DITHER
          Y offset for dither.


     Since 2.2


 -- Function: gdk-draw-rectangle (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (filled `bool') (x `int') (y `int')
          (width `int') (height `int')
     Draws a rectangular outline or filled rectangle, using the
     foreground color and other attributes of the `<gdk-gc>'.

     A rectangle drawn filled is 1 pixel smaller in both dimensions
     than a rectangle outlined. Calling `gdk_draw_rectangle (window,
     gc, TRUE, 0, 0, 20, 20)' results in a filled rectangle 20 pixels
     wide and 20 pixels high. Calling `gdk_draw_rectangle (window, gc,
     FALSE, 0, 0, 20, 20)' results in an outlined rectangle with
     corners at (0, 0), (0, 20), (20, 20), and (20, 0), which makes it
     21 pixels wide and 21 pixels high.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    GC
          a `<gdk-gc>'.

    FILLED
          ``#t'' if the rectangle should be filled.

    X
          the x coordinate of the left edge of the rectangle.

    Y
          the y coordinate of the top edge of the rectangle.

    WIDTH
          the width of the rectangle.

    HEIGHT
          the height of the rectangle.



 -- Function: gdk-draw-arc (drawable `<gdk-drawable>') (gc `<gdk-gc>')
          (filled `bool') (x `int') (y `int') (width `int')
          (height `int') (angle1 `int') (angle2 `int')
     Draws an arc or a filled 'pie slice'. The arc is defined by the
     bounding rectangle of the entire ellipse, and the start and end
     angles of the part of the ellipse to be drawn.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    GC
          a `<gdk-gc>'.

    FILLED
          ``#t'' if the arc should be filled, producing a 'pie slice'.

    X
          the x coordinate of the left edge of the bounding rectangle.

    Y
          the y coordinate of the top edge of the bounding rectangle.

    WIDTH
          the width of the bounding rectangle.

    HEIGHT
          the height of the bounding rectangle.

    ANGLE1
          the start angle of the arc, relative to the 3 o'clock
          position, counter-clockwise, in 1/64ths of a degree.

    ANGLE2
          the end angle of the arc, relative to ANGLE1, in 1/64ths of a
          degree.



 -- Function: gdk-draw-glyphs (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (font `<pango-font>') (x `int') (y `int')
          (glyphs `<pango-glyph-string>')
     This is a low-level function; 99% of text rendering should be done
     using `gdk-draw-layout' instead.

     A glyph is a single image in a font. This function draws a
     sequence of glyphs.  To obtain a sequence of glyphs you have to
     understand a lot about internationalized text handling, which you
     don't want to understand; thus, use `gdk-draw-layout' instead of
     this function, `gdk-draw-layout' handles the details.

    DRAWABLE
          a `<gdk-drawable>'

    GC
          a `<gdk-gc>'

    FONT
          font to be used

    X
          X coordinate of baseline origin

    Y
          Y coordinate of baseline origin

    GLYPHS
          the glyph string to draw



 -- Function: gdk-draw-glyphs-transformed (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (matrix `<pango-matrix>')
          (font `<pango-font>') (x `int') (y `int')
          (glyphs `<pango-glyph-string>')
     Renders a `<pango-glyph-string>' onto a drawable, possibly
     transforming the layed-out coordinates through a transformation
     matrix. Note that the transformation matrix for FONT is not
     changed, so to produce correct rendering results, the FONT must
     have been loaded using a `<pango-context>' with an identical
     transformation matrix to that passed in to this function.

     See also `gdk-draw-glyphs', `gdk-draw-layout'.

    DRAWABLE
          a `<gdk-drawable>'

    GC
          a `<gdk-gc>'

    MATRIX
          a `<pango-matrix>', or ``#f'' to use an identity
          transformation

    FONT
          the font in which to draw the string

    X
          the x position of the start of the string (in Pango units in
          user space coordinates)

    Y
          the y position of the baseline (in Pango units in user space
          coordinates)

    GLYPHS
          the glyph string to draw


     Since 2.6


 -- Function: gdk-draw-layout-line (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int')
          (line `<pango-layout-line>')
     Render a `<pango-layout-line>' onto an GDK drawable

     If the layout's `<pango-context>' has a transformation matrix set,
     then X and Y specify the position of the left edge of the baseline
     (left is in before-tranform user coordinates) in after-transform
     device coordinates.

    DRAWABLE
          the drawable on which to draw the line

    GC
          base graphics to use

    X
          the x position of start of string (in pixels)

    Y
          the y position of baseline (in pixels)

    LINE
          a `<pango-layout-line>'



 -- Function: gdk-draw-layout-line-with-colors
          (drawable `<gdk-drawable>') (gc `<gdk-gc>') (x `int')
          (y `int') (line `<pango-layout-line>')
          (foreground `<gdk-color>') (background `<gdk-color>')
     Render a `<pango-layout-line>' onto a `<gdk-drawable>', overriding
     the layout's normal colors with FOREGROUND and/or BACKGROUND.
     FOREGROUND and BACKGROUND need not be allocated.

     If the layout's `<pango-context>' has a transformation matrix set,
     then X and Y specify the position of the left edge of the baseline
     (left is in before-tranform user coordinates) in after-transform
     device coordinates.

    DRAWABLE
          the drawable on which to draw the line

    GC
          base graphics to use

    X
          the x position of start of string (in pixels)

    Y
          the y position of baseline (in pixels)

    LINE
          a `<pango-layout-line>'

    FOREGROUND
          foreground override color, or ``#f'' for none

    BACKGROUND
          background override color, or ``#f'' for none



 -- Function: gdk-draw-layout (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (layout `<pango-layout>')
     Render a `<pango-layout>' onto a GDK drawable

     If the layout's `<pango-context>' has a transformation matrix set,
     then X and Y specify the position of the top left corner of the
     bounding box (in device space) of the transformed layout.

     If you're using GTK+, the usual way to obtain a `<pango-layout>' is
     `gtk-widget-create-pango-layout'.

    DRAWABLE
          the drawable on which to draw string

    GC
          base graphics context to use

    X
          the X position of the left of the layout (in pixels)

    Y
          the Y position of the top of the layout (in pixels)

    LAYOUT
          a `<pango-layout>'



 -- Function: gdk-draw-layout-with-colors (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (layout `<pango-layout>')
          (foreground `<gdk-color>') (background `<gdk-color>')
     Render a `<pango-layout>' onto a `<gdk-drawable>', overriding the
     layout's normal colors with FOREGROUND and/or BACKGROUND.
     FOREGROUND and BACKGROUND need not be allocated.

     If the layout's `<pango-context>' has a transformation matrix set,
     then X and Y specify the position of the top left corner of the
     bounding box (in device space) of the transformed layout.

     If you're using GTK+, the ususal way to obtain a `<pango-layout>'
     is `gtk-widget-create-pango-layout'.

    DRAWABLE
          the drawable on which to draw string

    GC
          base graphics context to use

    X
          the X position of the left of the layout (in pixels)

    Y
          the Y position of the top of the layout (in pixels)

    LAYOUT
          a `<pango-layout>'

    FOREGROUND
          foreground override color, or ``#f'' for none

    BACKGROUND
          background override color, or ``#f'' for none



 -- Function: gdk-draw-string (drawable `<gdk-drawable>')
          (font `<gdk-font>') (gc `<gdk-gc>') (x `int') (y `int')
          (string `mchars')
     `gdk_draw_string' is deprecated and should not be used in
     newly-written code. Use `gdk-draw-layout' instead.

     Draws a string of characters in the given font or fontset.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    FONT
          a `<gdk-font>'.

    GC
          a `<gdk-gc>'.

    X
          the x coordinate of the left edge of the text.

    Y
          the y coordinate of the baseline of the text.

    STRING
          the string of characters to draw.



 -- Function: gdk-draw-drawable (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (src `<gdk-drawable>') (xsrc `int')
          (ysrc `int') (xdest `int') (ydest `int') (width `int')
          (height `int')
     Copies the WIDTH x HEIGHT region of SRC at coordinates (XSRC,
     YSRC) to coordinates (XDEST, YDEST) in DRAWABLE. WIDTH and/or
     HEIGHT may be given as -1, in which case the entire SRC drawable
     will be copied.

     Most fields in GC are not used for this operation, but notably the
     clip mask or clip region will be honored.

     The source and destination drawables must have the same visual and
     colormap, or errors will result. (On X11, failure to match
     visual/colormap results in a BadMatch error from the X server.) A
     common cause of this problem is an attempt to draw a bitmap to a
     color drawable. The way to draw a bitmap is to set the bitmap as
     the stipple on the `<gdk-gc>', set the fill mode to
     `GDK_STIPPLED', and then draw the rectangle.

    DRAWABLE
          a `<gdk-drawable>'

    GC
          a `<gdk-gc>' sharing the drawable's visual and colormap

    SRC
          the source `<gdk-drawable>', which may be the same as DRAWABLE

    XSRC
          X position in SRC of rectangle to draw

    YSRC
          Y position in SRC of rectangle to draw

    XDEST
          X position in DRAWABLE where the rectangle should be drawn

    YDEST
          Y position in DRAWABLE where the rectangle should be drawn

    WIDTH
          width of rectangle to draw, or -1 for entire SRC width

    HEIGHT
          height of rectangle to draw, or -1 for entire SRC height



 -- Function: gdk-draw-image (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (image `<gdk-image>') (xsrc `int')
          (ysrc `int') (xdest `int') (ydest `int') (width `int')
          (height `int')
     Draws a `<gdk-image>' onto a drawable. The depth of the
     `<gdk-image>' must match the depth of the `<gdk-drawable>'.

    DRAWABLE
          a `<gdk-drawable>' (a `<gdk-window>' or a `<gdk-pixmap>').

    GC
          a `<gdk-gc>'.

    IMAGE
          the `<gdk-image>' to draw.

    XSRC
          the left edge of the source rectangle within IMAGE.

    YSRC
          the top of the source rectangle within IMAGE.

    XDEST
          the x coordinate of the destination within DRAWABLE.

    YDEST
          the y coordinate of the destination within DRAWABLE.

    WIDTH
          the width of the area to be copied, or -1 to make the area
          extend to the right edge of IMAGE.

    HEIGHT
          the height of the area to be copied, or -1 to make the area
          extend to the bottom edge of IMAGE.



 -- Function: gdk-drawable-get-image (self `<gdk-drawable>') (x `int')
          (y `int') (width `int') (height `int') =>  (ret `<gdk-image>')
 -- Method: get-image
     A `<gdk-image>' stores client-side image data (pixels). In
     contrast, `<gdk-pixmap>' and `<gdk-window>' are server-side
     objects.  `gdk-drawable-get-image' obtains the pixels from a
     server-side drawable as a client-side `<gdk-image>'. The format of
     a `<gdk-image>' depends on the `<gdk-visual>' of the current
     display, which makes manipulating `<gdk-image>' extremely
     difficult; therefore, in most cases you should use
     `gdk-pixbuf-get-from-drawable' instead of this lower-level
     function. A `<gdk-pixbuf>' contains image data in a canonicalized
     RGB format, rather than a display-dependent format. Of course,
     there's a convenience vs. speed tradeoff here, so you'll want to
     think about what makes sense for your application.

     X, Y, WIDTH, and HEIGHT define the region of DRAWABLE to obtain as
     an image.

     You would usually copy image data to the client side if you intend
     to examine the values of individual pixels, for example to darken
     an image or add a red tint. It would be prohibitively slow to make
     a round-trip request to the windowing system for each pixel, so
     instead you get all of them at once, modify them, then copy them
     all back at once.

     If the X server or other windowing system backend is on the local
     machine, this function may use shared memory to avoid copying the
     image data.

     If the source drawable is a `<gdk-window>' and partially offscreen
     or obscured, then the obscured portions of the returned image will
     contain undefined data.

    DRAWABLE
          a `<gdk-drawable>'

    X
          x coordinate on DRAWABLE

    Y
          y coordinate on DRAWABLE

    WIDTH
          width of region to get

    HEIGHT
          height or region to get

    RET
          a `<gdk-image>' containing the contents of DRAWABLE



 -- Function: gdk-drawable-copy-to-image (self `<gdk-drawable>')
          (image `<gdk-image>') (src_x `int') (src_y `int')
          (dest_x `int') (dest_y `int') (width `int') (height `int')
          =>  (ret `<gdk-image>')
 -- Method: copy-to-image
     Copies a portion of DRAWABLE into the client side image structure
     IMAGE. If IMAGE is ``#f'', creates a new image of size WIDTH x
     HEIGHT and copies into that. See `gdk-drawable-get-image' for
     further details.

    DRAWABLE
          a `<gdk-drawable>'

    IMAGE
          a `<gdk-drawable>', or ``#f'' if a new IMAGE should be
          created.

    SRC-X
          x coordinate on DRAWABLE

    SRC-Y
          y coordinate on DRAWABLE

    DEST-X
          x coordinate within IMAGE. Must be 0 if IMAGE is ``#f''

    DEST-Y
          y coordinate within IMAGE. Must be 0 if IMAGE is ``#f''

    WIDTH
          width of region to get

    HEIGHT
          height or region to get

    RET
          IMAGE, or a new a `<gdk-image>' containing the contents of
          DRAWABLE


     Since 2.4



File: guile-gnome-gdk.info,  Node: Bitmaps and Pixmaps,  Next: GdkRGB,  Prev: Drawing Primitives,  Up: Top

9 Bitmaps and Pixmaps
*********************

Offscreen drawables

9.1 Overview
============

Pixmaps are offscreen drawables. They can be drawn upon with the
standard drawing primitives, then copied to another drawable (such as a
`<gdk-window>') with `gdk-pixmap-draw'. The depth of a pixmap is the
number of bits per pixels. Bitmaps are simply pixmaps with a depth of
1. (That is, they are monochrome bitmaps - each pixel can be either on
or off).

9.2 Usage
=========

 -- Function: gdk-pixmap-new (drawable `<gdk-drawable>') (width `int')
          (height `int') (depth `int') =>  (ret `<gdk-pixmap>')
     Create a new pixmap with a given size and depth.

    DRAWABLE
          A `<gdk-drawable>', used to determine default values for the
          new pixmap.  Can be ``#f'' if DEPTH is specified,

    WIDTH
          The width of the new pixmap in pixels.

    HEIGHT
          The height of the new pixmap in pixels.

    DEPTH
          The depth (number of bits per pixel) of the new pixmap. If
          -1, and DRAWABLE is not ``#f'', the depth of the new pixmap
          will be equal to that of DRAWABLE.

    RET
          the `<gdk-pixmap>'



 -- Function: gdk-bitmap-create-from-data (drawable `<gdk-drawable>')
          (data `mchars') (width `int') (height `int') => 
          (ret `<gdk-drawable>')
     Creates a new bitmap from data in XBM format.

    DRAWABLE
          a `<gdk-drawable>', used to determine default values for the
          new pixmap.  Can be ``#f'', in which case the root window is
          used.

    DATA
          a pointer to the XBM data.

    WIDTH
          the width of the new pixmap in pixels.

    HEIGHT
          the height of the new pixmap in pixels.

    RET
          the `<gdk-bitmap>'



 -- Function: gdk-pixmap-create-from-data (drawable `<gdk-drawable>')
          (data `mchars') (width `int') (height `int') (depth `int')
          (fg `<gdk-color>') (bg `<gdk-color>') =>  (ret `<gdk-pixmap>')
     Create a two-color pixmap from data in XBM data.

    DRAWABLE
          a `<gdk-drawable>', used to determine default values for the
          new pixmap.  Can be ``#f'', if the depth is given.

    DATA
          a pointer to the data.

    WIDTH
          the width of the new pixmap in pixels.

    HEIGHT
          the height of the new pixmap in pixels.

    DEPTH
          the depth (number of bits per pixel) of the new pixmap.

    FG
          the foreground color.

    BG
          the background color.

    RET
          the `<gdk-pixmap>'




File: guile-gnome-gdk.info,  Node: GdkRGB,  Next: Images,  Prev: Bitmaps and Pixmaps,  Up: Top

10 GdkRGB
*********

Renders RGB, grayscale, or indexed image data to a GdkDrawable

10.1 Overview
=============

GdkRGB is a low-level module which renders RGB, grayscale, and indexed
colormap images to a `<gdk-drawable>'. It does this as efficiently as
possible, handling issues such as colormaps, visuals, dithering,
temporary buffers, and so on. Most code should use the higher-level
`<gdk-pixbuf>' features in place of this module; for example,
`gdk-pixbuf-render-to-drawable' uses GdkRGB in its implementation.

   GdkRGB allocates a color cube to use when rendering images. You can
set the threshold for installing colormaps with
`gdk-rgb-set-min-colors'. The default is 5x5x5 (125). If a colorcube of
this size or larger can be allocated in the default colormap, then
that's done. Otherwise, GdkRGB creates its own private colormap.
Setting it to 0 means that it always tries to use the default colormap,
and setting it to 216 means that it always creates a private one if it
cannot allocate the 6x6x6 colormap in the default. If you always want a
private colormap (to avoid consuming too many colormap entries for
other apps, say), you can use `gdk_rgb_set_install(TRUE)'. Setting the
value greater than 216 exercises a bug in older versions of GdkRGB.
Note, however, that setting it to 0 doesn't let you get away with
ignoring the colormap and visual - a colormap is always created in
grayscale and direct color modes, and the visual is changed in cases
where a "better" visual than the default is available.


     &#x0023;include <gtk/gtk.h>

     &#x0023;define IMAGE_WIDTH	256
     &#x0023;define IMAGE_HEIGHT	256

     guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];

     gboolean on_darea_expose (GtkWidget *widget,
     			  GdkEventExpose *event,
     			  gpointer user_data);

     int
     main (int argc, char *argv[])
     {
       GtkWidget *window, *darea;
       gint x, y;
       guchar *pos;

       gtk_init (&argc, &argv);

       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       darea = gtk_drawing_area_new ();
       gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
       gtk_container_add (GTK_CONTAINER (window), darea);
       gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
                           GTK_SIGNAL_FUNC (on_darea_expose), NULL);
       gtk_widget_show_all (window);

       /* Set up the RGB buffer. */
       pos = rgbbuf;
       for (y = 0; y < IMAGE_HEIGHT; y++)
         {
           for (x = 0; x < IMAGE_WIDTH; x++)
     	{
     	  *pos++ = x - x % 32;			/* Red. */
     	  *pos++ = (x / 32) * 4 + y - y % 32;	/* Green. */
     	  *pos++ = y - y % 32;			/* Blue. */
     	}
         }

       gtk_main ();
       return 0;
     }


     gboolean
     on_darea_expose (GtkWidget *widget,
     		 GdkEventExpose *event,
     		 gpointer user_data)
     {
       gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
     		      0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
     		      GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);

       return TRUE;
     }

10.2 Usage
==========

 -- Function: gdk-rgb-init
     `gdk_rgb_init' is deprecated and should not be used in
     newly-written code.

     This function no longer does anything at all. It's completely
     useless (and harmless).


 -- Function: gdk-rgb-gc-set-foreground (gc `<gdk-gc>')
          (rgb `unsigned-int32')
     `gdk_rgb_gc_set_foreground' is deprecated and should not be used in
     newly-written code.

     Sets the foreground color in GC to the specified color (or the
     closest approximation, in the case of limited visuals).

    GC
          The `<gdk-gc>' to modify.

    RGB
          The color, represented as a 0xRRGGBB integer value.



 -- Function: gdk-rgb-gc-set-background (gc `<gdk-gc>')
          (rgb `unsigned-int32')
     `gdk_rgb_gc_set_background' is deprecated and should not be used in
     newly-written code.

     Sets the background color in GC to the specified color (or the
     closest approximation, in the case of limited visuals).

    GC
          The `<gdk-gc>' to modify.

    RGB
          The color, represented as a 0xRRGGBB integer value.



 -- Function: gdk-rgb-xpixel-from-rgb (rgb `unsigned-int32') => 
          (ret `unsigned-long')
     `gdk_rgb_xpixel_from_rgb' is deprecated and should not be used in
     newly-written code.

     Finds the X pixel closest in color to the RGB color specified.
     This value may be used to set the struct.

    RGB
          The color, represented as a 0xRRGGBB integer value.

    RET
          The X pixel value.



 -- Function: gdk-rgb-set-install (install `bool')
     If INSTALL is ``#t'', directs GdkRGB to always install a new
     "private" colormap rather than trying to find a best fit with the
     colors already allocated. Ordinarily, GdkRGB will install a
     colormap only if a sufficient cube cannot be allocated.

     A private colormap has more colors, leading to better quality
     display, but also leads to the dreaded "colormap flashing" effect.

    INSTALL
          ``#t'' to set install mode.



 -- Function: gdk-rgb-set-min-colors (min_colors `int')
     Sets the minimum number of colors for the color cube. Generally,
     GdkRGB tries to allocate the largest color cube it can. If it
     can't allocate a color cube at least as large as MIN-COLORS, it
     installs a private colormap.

    MIN-COLORS
          The minimum number of colors accepted.



 -- Function: gdk-rgb-get-visual =>  (ret `<gdk-visual>')
     Gets a "preferred visual" chosen by GdkRGB for rendering image
     data on the default screen. In previous versions of GDK, this was
     the only visual GdkRGB could use for rendering. In current
     versions, it's simply the visual GdkRGB would have chosen as the
     optimal one in those previous versions. GdkRGB can now render to
     drawables with any visual.

    RET
          The `<gdk-visual>' chosen by GdkRGB.



 -- Function: gdk-rgb-get-colormap =>  (ret `<gdk-colormap>')
     Get the preferred colormap for rendering image data. Not a very
     useful function; historically, GDK could only render RGB image
     data to one colormap and visual, but in the current version it can
     render to any colormap and visual. So there's no need to call this
     function.

    RET
          the preferred colormap



 -- Function: gdk-rgb-ditherable =>  (ret `bool')
     Determines whether the preferred visual is ditherable. This
     function may be useful for presenting a user interface choice to
     the user about which dither mode is desired; if the display is not
     ditherable, it may make sense to gray out or hide the
     corresponding UI widget.

    RET
          ``#t'' if the preferred visual is ditherable.



 -- Function: gdk-rgb-colormap-ditherable (cmap `<gdk-colormap>') => 
          (ret `bool')
     Determines whether the visual associated with CMAP is ditherable.
     This function may be useful for presenting a user interface choice
     to the user about which dither mode is desired; if the display is
     not ditherable, it may make sense to gray out or hide the
     corresponding UI widget.

    CMAP
          a `<gdk-colormap>'

    RET
          ``#t'' if the visual associated with CMAP is ditherable.



 -- Function: gdk-rgb-set-verbose (verbose `bool')
     Sets the "verbose" flag. This is generally only useful for
     debugging.

    VERBOSE
          ``#t'' if verbose messages are desired.




File: guile-gnome-gdk.info,  Node: Images,  Next: Pixbufs,  Prev: GdkRGB,  Up: Top

11 Images
*********

A client-side area for bit-mapped graphics

11.1 Overview
=============

The `<gdk-image>' type represents an area for drawing graphics. It has
now been superceded to a large extent by the much more flexible GdkRGB
functions.

   To create an empty `<gdk-image>' use `gdk-image-new'. To create a
`<gdk-image>' from bitmap data use `gdk-image-new-bitmap'. To create an
image from part of a `<gdk-window>' use `gdk-drawable-get-image'.

   The image can be manipulated with `gdk-image-get-pixel' and
`gdk-image-put-pixel', or alternatively by changing the actual pixel
data.  Though manipulating the pixel data requires complicated code to
cope with the different formats that may be used.

   To draw a `<gdk-image>' in a `<gdk-window>' or `<gdk-pixmap>' use
`gdk-draw-image'.

   To destroy a `<gdk-image>' use `gdk-image-destroy'.

11.2 Usage
==========

 -- Class: <gdk-image>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-image-new (type `<gdk-image-type>')
          (visual `<gdk-visual>') (width `int') (height `int') => 
          (ret `<gdk-image>')
     Creates a new `<gdk-image>'.

    TYPE
          the type of the `<gdk-image>', one of `GDK_IMAGE_NORMAL',
          `GDK_IMAGE_SHARED' and `GDK_IMAGE_FASTEST'.
          `GDK_IMAGE_FASTEST' is probably the best choice, since it
          will try creating a `GDK_IMAGE_SHARED' image first and if
          that fails it will then use `GDK_IMAGE_NORMAL'.

    VISUAL
          the `<gdk-visual>' to use for the image.

    WIDTH
          the width of the image in pixels.

    HEIGHT
          the height of the image in pixels.

    RET
          a new `<gdk-image>', or ``#f'' if the image could not be
          created.



 -- Function: gdk-image-get (drawable `<gdk-drawable>') (x `int')
          (y `int') (width `int') (height `int') =>  (ret `<gdk-image>')
     `gdk_image_get' is deprecated and should not be used in
     newly-written code.

     This is a deprecated wrapper for `gdk-drawable-get-image';
     `gdk-drawable-get-image' should be used instead. Or even better:
     in most cases `gdk-pixbuf-get-from-drawable' is the most
     convenient choice.

    DRAWABLE
          a `<gdk-drawable>'

    X
          x coordinate in WINDOW

    Y
          y coordinate in WINDOW

    WIDTH
          width of area in WINDOW

    HEIGHT
          height of area in WINDOW

    RET
          a new `<gdk-image>' or ``#f''



 -- Function: gdk-image-get-colormap (self `<gdk-image>') => 
          (ret `<gdk-colormap>')
 -- Method: get-colormap
     Retrieves the colormap for a given image, if it exists. An image
     will have a colormap if the drawable from which it was created has
     a colormap, or if a colormap was set explicitely with
     `gdk-image-set-colormap'.

    IMAGE
          a `<gdk-image>'

    RET
          colormap for the image



 -- Function: gdk-image-set-colormap (self `<gdk-image>')
          (colormap `<gdk-colormap>')
 -- Method: set-colormap
     Sets the colormap for the image to the given colormap. Normally
     there's no need to use this function, images are created with the
     correct colormap if you get the image from a drawable. If you
     create the image from scratch, use the colormap of the drawable
     you intend to render the image to.

    IMAGE
          a `<gdk-image>'

    COLORMAP
          a `<gdk-colormap>'



 -- Function: gdk-image-put-pixel (self `<gdk-image>') (x `int')
          (y `int') (pixel `unsigned-int32')
 -- Method: put-pixel
     Sets a pixel in a `<gdk-image>' to a given pixel value.

    IMAGE
          a `<gdk-image>'.

    X
          the x coordinate of the pixel to set.

    Y
          the y coordinate of the pixel to set.

    PIXEL
          the pixel value to set.



 -- Function: gdk-image-get-pixel (self `<gdk-image>') (x `int')
          (y `int') =>  (ret `unsigned-int32')
 -- Method: get-pixel
     Gets a pixel value at a specified position in a `<gdk-image>'.

    IMAGE
          a `<gdk-image>'.

    X
          the x coordinate of the pixel to get.

    Y
          the y coordinate of the pixel to get.

    RET
          the pixel value at the given position.




File: guile-gnome-gdk.info,  Node: Pixbufs,  Next: Colormaps and Colors,  Prev: Images,  Up: Top

12 Pixbufs
**********

Functions for rendering pixbufs on drawables

12.1 Overview
=============

These functions allow to render pixbufs on drawables. Pixbufs are
client-side images. For details on how to create and manipulate
pixbufs, see the `<gdk-pixbuf>' API documentation.

12.2 Usage
==========

 -- Function: gdk-pixbuf-render-threshold-alpha (self `<gdk-pixbuf>')
          (bitmap `<gdk-drawable>') (src_x `int') (src_y `int')
          (dest_x `int') (dest_y `int') (width `int') (height `int')
          (alpha_threshold `int')
 -- Method: render-threshold-alpha
     Takes the opacity values in a rectangular portion of a pixbuf and
     thresholds them to produce a bi-level alpha mask that can be used
     as a clipping mask for a drawable.

    PIXBUF
          A pixbuf.

    BITMAP
          Bitmap where the bilevel mask will be painted to.

    SRC-X
          Source X coordinate.

    SRC-Y
          source Y coordinate.

    DEST-X
          Destination X coordinate.

    DEST-Y
          Destination Y coordinate.

    WIDTH
          Width of region to threshold, or -1 to use pixbuf width

    HEIGHT
          Height of region to threshold, or -1 to use pixbuf height

    ALPHA-THRESHOLD
          Opacity values below this will be painted as zero; all other
          values will be painted as one.



 -- Function: gdk-pixbuf-render-to-drawable (self `<gdk-pixbuf>')
          (drawable `<gdk-drawable>') (gc `<gdk-gc>') (src_x `int')
          (src_y `int') (dest_x `int') (dest_y `int') (width `int')
          (height `int') (dither `<gdk-rgb-dither>') (x_dither `int')
          (y_dither `int')
 -- Method: render-to-drawable
     `gdk_pixbuf_render_to_drawable' has been deprecated since version
     2.4 and should not be used in newly-written code. This function is
     obsolete. Use `gdk-draw-pixbuf' instead.

     Renders a rectangular portion of a pixbuf to a drawable while
     using the specified GC. This is done using GdkRGB, so the
     specified drawable must have the GdkRGB visual and colormap. Note
     that this function will ignore the opacity information for images
     with an alpha channel; the GC must already have the clipping mask
     set if you want transparent regions to show through.

     For an explanation of dither offsets, see the GdkRGB
     documentation. In brief, the dither offset is important when
     re-rendering partial regions of an image to a rendered version of
     the full image, or for when the offsets to a base position change,
     as in scrolling. The dither matrix has to be shifted for consistent
     visual results. If you do not have any of these cases, the dither
     offsets can be both zero.

    PIXBUF
          A pixbuf.

    DRAWABLE
          Destination drawable.

    GC
          GC used for rendering.

    SRC-X
          Source X coordinate within pixbuf.

    SRC-Y
          Source Y coordinate within pixbuf.

    DEST-X
          Destination X coordinate within drawable.

    DEST-Y
          Destination Y coordinate within drawable.

    WIDTH
          Width of region to render, in pixels, or -1 to use pixbuf
          width

    HEIGHT
          Height of region to render, in pixels, or -1 to use pixbuf
          height

    DITHER
          Dithering mode for GdkRGB.

    X-DITHER
          X offset for dither.

    Y-DITHER
          Y offset for dither.



 -- Function: gdk-pixbuf-render-to-drawable-alpha (self `<gdk-pixbuf>')
          (drawable `<gdk-drawable>') (src_x `int') (src_y `int')
          (dest_x `int') (dest_y `int') (width `int') (height `int')
          (alpha_mode `<gdk-pixbuf-alpha-mode>')
          (alpha_threshold `int') (dither `<gdk-rgb-dither>')
          (x_dither `int') (y_dither `int')
 -- Method: render-to-drawable-alpha
     `gdk_pixbuf_render_to_drawable_alpha' has been deprecated since
     version 2.4 and should not be used in newly-written code. This
     function is obsolete. Use `gdk-draw-pixbuf' instead.

     Renders a rectangular portion of a pixbuf to a drawable. The
     destination drawable must have a colormap. All windows have a
     colormap, however, pixmaps only have colormap by default if they
     were created with a non-``#f'' window argument. Otherwise a
     colormap must be set on them with gdk_drawable_set_colormap.

     On older X servers, rendering pixbufs with an alpha channel
     involves round trips to the X server, and may be somewhat slow.

    PIXBUF
          A pixbuf.

    DRAWABLE
          Destination drawable.

    SRC-X
          Source X coordinate within pixbuf.

    SRC-Y
          Source Y coordinates within pixbuf.

    DEST-X
          Destination X coordinate within drawable.

    DEST-Y
          Destination Y coordinate within drawable.

    WIDTH
          Width of region to render, in pixels, or -1 to use pixbuf
          width.

    HEIGHT
          Height of region to render, in pixels, or -1 to use pixbuf
          height.

    ALPHA-MODE
          Ignored. Present for backwards compatibility.

    ALPHA-THRESHOLD
          Ignored. Present for backwards compatibility

    DITHER
          Dithering mode for GdkRGB.

    X-DITHER
          X offset for dither.

    Y-DITHER
          Y offset for dither.



 -- Function: gdk-pixbuf-get-from-drawable (self `<gdk-pixbuf>')
          (src `<gdk-drawable>') (cmap `<gdk-colormap>') (src_x `int')
          (src_y `int') (dest_x `int') (dest_y `int') (width `int')
          (height `int') =>  (ret `<gdk-pixbuf>')
 -- Method: get-from-drawable
     Transfers image data from a `<gdk-drawable>' and converts it to an
     RGB(A) representation inside a `<gdk-pixbuf>'. In other words,
     copies image data from a server-side drawable to a client-side
     RGB(A) buffer. This allows you to efficiently read individual
     pixels on the client side.

     If the drawable SRC has no colormap (`gdk-drawable-get-colormap'
     returns ``#f''), then a suitable colormap must be specified.
     Typically a `<gdk-window>' or a pixmap created by passing a
     `<gdk-window>' to `gdk-pixmap-new' will already have a colormap
     associated with it. If the drawable has a colormap, the CMAP
     argument will be ignored. If the drawable is a bitmap (1 bit per
     pixel pixmap), then a colormap is not required; pixels with a
     value of 1 are assumed to be white, and pixels with a value of 0
     are assumed to be black. For taking screenshots,
     `gdk-colormap-get-system' returns the correct colormap to use.

     If the specified destination pixbuf DEST is ``#f'', then this
     function will create an RGB pixbuf with 8 bits per channel and no
     alpha, with the same size specified by the WIDTH and HEIGHT
     arguments. In this case, the DEST-X and DEST-Y arguments must be
     specified as 0. If the specified destination pixbuf is not ``#f''
     and it contains alpha information, then the filled pixels will be
     set to full opacity (alpha = 255).

     If the specified drawable is a pixmap, then the requested source
     rectangle must be completely contained within the pixmap,
     otherwise the function will return ``#f''. For pixmaps only (not
     for windows) passing -1 for width or height is allowed to mean the
     full width or height of the pixmap.

     If the specified drawable is a window, and the window is off the
     screen, then there is no image data in the obscured/offscreen
     regions to be placed in the pixbuf. The contents of portions of
     the pixbuf corresponding to the offscreen region are undefined.

     If the window you're obtaining data from is partially obscured by
     other windows, then the contents of the pixbuf areas corresponding
     to the obscured regions are undefined.

     If the target drawable is not mapped (typically because it's
     iconified/minimized or not on the current workspace), then ``#f''
     will be returned.

     If memory can't be allocated for the return value, ``#f'' will be
     returned instead.

     (In short, there are several ways this function can fail, and if
     it fails it returns ``#f''; so check the return value.)

     This function calls `gdk-drawable-get-image' internally and
     converts the resulting image to a `<gdk-pixbuf>', so the
     documentation for `gdk-drawable-get-image' may also be relevant.

    DEST
          Destination pixbuf, or ``#f'' if a new pixbuf should be
          created.

    SRC
          Source drawable.

    CMAP
          A colormap if SRC doesn't have one set.

    SRC-X
          Source X coordinate within drawable.

    SRC-Y
          Source Y coordinate within drawable.

    DEST-X
          Destination X coordinate in pixbuf, or 0 if DEST is NULL.

    DEST-Y
          Destination Y coordinate in pixbuf, or 0 if DEST is NULL.

    WIDTH
          Width in pixels of region to get.

    HEIGHT
          Height in pixels of region to get.

    RET
          The same pixbuf as DEST if it was non-``#f'', or a
          newly-created pixbuf with a reference count of 1 if no
          destination pixbuf was specified, or ``#f'' on error



 -- Function: gdk-pixbuf-get-from-image (self `<gdk-pixbuf>')
          (src `<gdk-image>') (cmap `<gdk-colormap>') (src_x `int')
          (src_y `int') (dest_x `int') (dest_y `int') (width `int')
          (height `int') =>  (ret `<gdk-pixbuf>')
 -- Method: get-from-image
     Same as `gdk-pixbuf-get-from-drawable' but gets the pixbuf from an
     image.

    DEST
          Destination pixbuf, or ``#f'' if a new pixbuf should be
          created.

    SRC
          Source `<gdk-image>'.

    CMAP
          A colormap, or ``#f'' to use the one for SRC

    SRC-X
          Source X coordinate within drawable.

    SRC-Y
          Source Y coordinate within drawable.

    DEST-X
          Destination X coordinate in pixbuf, or 0 if DEST is NULL.

    DEST-Y
          Destination Y coordinate in pixbuf, or 0 if DEST is NULL.

    WIDTH
          Width in pixels of region to get.

    HEIGHT
          Height in pixels of region to get.

    RET
          DEST, newly-created pixbuf if DEST was ``#f'', ``#f'' on error




File: guile-gnome-gdk.info,  Node: Colormaps and Colors,  Next: Visuals,  Prev: Pixbufs,  Up: Top

13 Colormaps and Colors
***********************

Manipulation of colors and colormaps

13.1 Overview
=============

These functions are used to modify colormaps. A colormap is an object
that contains the mapping between the color values stored in memory and
the RGB values that are used to display color values. In general,
colormaps only contain significant information for pseudo-color
visuals, but even for other visual types, a colormap object is required
in some circumstances.

   There are a couple of special colormaps that can be retrieved. The
system colormap (retrieved with `gdk-colormap-get-system') is the
default colormap of the system. If you are using GdkRGB, there is
another colormap that is important - the colormap in which GdkRGB
works, retrieved with `gdk-rgb-get-cmap'. However, when using GdkRGB,
it is not generally necessary to allocate colors directly.

   In previous revisions of this interface, a number of functions that
take a `<gdk-colormap>' parameter were replaced with functions whose
names began with "gdk_colormap_". This process will probably be
extended somewhat in the future - `gdk-color-white', `gdk-color-black',
and `gdk-color-change' will probably become aliases.

13.2 Usage
==========

 -- Class: <gdk-color>
     Derives from `<gboxed>'.


 -- Class: <gdk-colormap>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-color-copy (self `<gdk-color>') => 
          (ret `<gdk-color>')
     Makes a copy of a color structure. The result must be freed using
     `gdk-color-free'.

    COLOR
          a `<gdk-color>'.

    RET
          a copy of COLOR.



 -- Function: gdk-color-white (colormap `<gdk-colormap>')
          (color `<gdk-color>') =>  (ret `int')
     `gdk_color_white' is deprecated and should not be used in
     newly-written code.

     Returns the white color for a given colormap. The resulting value
     has already allocated been allocated.

    COLORMAP
          a `<gdk-colormap>'.

    COLOR
          the location to store the color.

    RET
          ``#t'' if the allocation succeeded.



 -- Function: gdk-color-black (colormap `<gdk-colormap>')
          (color `<gdk-color>') =>  (ret `int')
     `gdk_color_black' is deprecated and should not be used in
     newly-written code.

     Returns the black color for a given colormap. The resulting value
     has already benn allocated.

    COLORMAP
          a `<gdk-colormap>'.

    COLOR
          the location to store the color.

    RET
          ``#t'' if the allocation succeeded.



 -- Function: gdk-color-parse (spec `mchars') (color `<gdk-color>') => 
          (ret `bool')
     Parses a textual specification of a color and fill in the ,
     `<gdk-color>' structure. The color is _not_ allocated, you must
     call `gdk-colormap-alloc-color' yourself. The text string can be
     in any of the forms accepted by `x-parse-color'; these include
     name for a color from `rgb.txt', such as `DarkSlateGray', or a hex
     specification such as `&#x0023;3050b2' or `&#x0023;35b'.

    SPEC
          the string specifying the color.

    COLOR
          the `<gdk-color>' to fill in

    RET
          ``#t'' if the parsing succeeded.



 -- Function: gdk-color-alloc (colormap `<gdk-colormap>')
          (color `<gdk-color>') =>  (ret `int')
     `gdk_color_alloc' is deprecated and should not be used in
     newly-written code. Use `gdk-colormap-alloc-color' instead.

     Allocates a single color from a colormap.

    COLORMAP
          a `<gdk-colormap>'.

    COLOR
          The color to allocate. On return, the filled in.

    RET
          ``#t'' if the allocation succeeded.



 -- Function: gdk-color-change (colormap `<gdk-colormap>')
          (color `<gdk-color>') =>  (ret `int')
     `gdk_color_change' is deprecated and should not be used in
     newly-written code.

     Changes the value of a color that has already been allocated. If
     COLORMAP is not a private colormap, then the color must have been
     allocated using `gdk-colormap-alloc-colors' with the WRITEABLE set
     to ``#t''.

    COLORMAP
          a `<gdk-colormap>'.

    COLOR
          a `<gdk-color>', with the color to change in the field, and
          the new value in the remaining fields.

    RET
          ``#t'' if the color was successfully changed.




File: guile-gnome-gdk.info,  Node: Visuals,  Next: Fonts,  Prev: Colormaps and Colors,  Up: Top

14 Visuals
**********

Low-level display hardware information

14.1 Overview
=============

A `<gdk-visual>' describes a particular video hardware display format.
It includes information about the number of bits used for each color,
the way the bits are translated into an RGB value for display, and the
way the bits are stored in memory. For example, a piece of display
hardware might support 24-bit color, 16-bit color, or 8-bit color;
meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can be
in different formats; for example the "red" element of an RGB pixel may
be in the top 8 bits of the pixel, or may be in the lower 4 bits.

   Usually you can avoid thinking about visuals in GTK+. Visuals are
useful to interpret the contents of a `<gdk-image>', but you should
avoid `<gdk-image>' precisely because its contents depend on the display
hardware; use `<gdk-pixbuf>' instead, for all but the most low-level
purposes. Also, anytime you provide a `<gdk-colormap>', the visual is
implied as part of the colormap (`gdk-colormap-get-visual'), so you
won't have to provide a visual in addition.

   There are several standard visuals. The visual returned by
`gdk-visual-get-system' is the system's default visual.
`gdk-rgb-get-visual' return the visual most suited to displaying
full-color image data. If you use the calls in `<gdk-rgb>', you should
create your windows using this visual (and the colormap returned by
`gdk-rgb-get-colormap').

   A number of functions are provided for determining the "best"
available visual.  For the purposes of making this determination,
higher bit depths are considered better, and for visuals of the same
bit depth, `GDK_VISUAL_PSEUDO_COLOR' is preferred at 8bpp, otherwise,
the visual types are ranked in the order of (highest to lowest)
`GDK_VISUAL_DIRECT_COLOR', `GDK_VISUAL_TRUE_COLOR',
`GDK_VISUAL_PSEUDO_COLOR', `GDK_VISUAL_STATIC_COLOR',
`GDK_VISUAL_GRAYSCALE', then `GDK_VISUAL_STATIC_GRAY'.

14.2 Usage
==========

 -- Class: <gdk-visual>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-list-visuals =>  (ret `glist-of')
     Lists the available visuals for the default screen. (See
     `gdk-screen-list-visuals') A visual describes a hardware image
     data format.  For example, a visual might support 24-bit color, or
     8-bit color, and might expect pixels to be in a certain format.

     Call `g-list-free' on the return value when you're finished with
     it.

    RET
          a list of visuals; the list must be freed, but not its
          contents



 -- Function: gdk-visual-get-best-depth =>  (ret `int')
     Get the best available depth for the default GDK screen. "Best"
     means "largest," i.e. 32 preferred over 24 preferred over 8 bits
     per pixel.

    RET
          best available depth



 -- Function: gdk-visual-get-best-type =>  (ret `<gdk-visual-type>')
     Return the best available visual type for the default GDK screen.

    RET
          best visual type



 -- Function: gdk-visual-get-system =>  (ret `<gdk-visual>')
     Get the system'sdefault visual for the default GDK screen. This is
     the visual for the root window of the display. The return value
     should not be freed.

    RET
          system visual



 -- Function: gdk-visual-get-best =>  (ret `<gdk-visual>')
     Get the visual with the most available colors for the default GDK
     screen. The return value should not be freed.

    RET
          best visual



 -- Function: gdk-visual-get-best-with-depth (depth `int') => 
          (ret `<gdk-visual>')
     Get the best visual with depth DEPTH for the default GDK screen.
     Color visuals and visuals with mutable colormaps are preferred
     over grayscale or fixed-colormap visuals. The return value should
     not be freed. ``#f'' may be returned if no visual supports DEPTH.

    DEPTH
          a bit depth

    RET
          best visual for the given depth



 -- Function: gdk-visual-get-best-with-type
          (visual_type `<gdk-visual-type>') =>  (ret `<gdk-visual>')
     Get the best visual of the given VISUAL-TYPE for the default GDK
     screen.  Visuals with higher color depths are considered better.
     The return value should not be freed. ``#f'' may be returned if no
     visual has type VISUAL-TYPE.

    VISUAL-TYPE
          a visual type

    RET
          best visual of the given type



 -- Function: gdk-visual-get-best-with-both (depth `int')
          (visual_type `<gdk-visual-type>') =>  (ret `<gdk-visual>')
     Combines `gdk-visual-get-best-with-depth' and
     `gdk-visual-get-best-with-type'.

    DEPTH
          a bit depth

    VISUAL-TYPE
          a visual type

    RET
          best visual with both DEPTH and VISUAL-TYPE, or ``#f'' if none



 -- Function: gdk-visual-get-screen (self `<gdk-visual>') => 
          (ret `<gdk-screen>')
 -- Method: get-screen
     Gets the screen to which this visual belongs

    VISUAL
          a `<gdk-visual>'

    RET
          the screen to which this visual belongs.


     Since 2.2



File: guile-gnome-gdk.info,  Node: Fonts,  Next: Cursors,  Prev: Visuals,  Up: Top

15 Fonts
********

Loading and manipulating fonts

15.1 Overview
=============

The `<gdk-font>' data type represents a font for drawing on the screen.
These functions provide support for loading fonts, and also for
determining the dimensions of characters and strings when drawn with a
particular font.

   Fonts in X are specified by a "X Logical Font Description". The
following description is considerably simplified. For definitive
information about XLFD's see the X reference documentation. A X Logical
Font Description (XLFD) consists of a sequence of fields separated (and
surrounded by) '-' characters. For example, Adobe Helvetica Bold 12 pt,
has the full description:


     "-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"

   The fields in the XLFD are:

   When specifying a font via a X logical Font Description, '*' can be
used as a wildcard to match any portion of the XLFD. For instance, the
above example could also be specified as It is generally a good idea to
use wildcards for any portion of the XLFD that your program does not
care about specifically, since that will improve the chances of finding
a matching font.


     "-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"

   A "fontset" is a list of fonts that is used for drawing
international text that may contain characters from a number of
different character sets. It is represented by a list of XLFD's.

   The font for a given character set is determined by going through
the list of XLFD's in order. For each one, if the registry and and
encoding fields match the desired character set, then that font is
used, otherwise if the XLFD contains wild-cards for the registry and
encoding fields, the registry and encoding for the desired character
set are substituted in and a lookup is done. If a match is found that
font is used. Otherwise, processing continues on to the next font in
the list.

   The functions for determining the metrics of a string come in
several varieties that can take a number of forms of string input:

16-BIT STRING

MULTIBYTE STRING

WIDE CHARACTER STRING

   When using functions like `gdk-string-width' that take a `<gchar *>',
if the font is of type `GDK_FONT_FONT' and is an 8-bit font, then each
`<gchar>' indexes the glyphs in the font directly.

   For functions taking a `<gchar *>', if the font is of type
`GDK_FONT_FONT', and is a 16-bit font, then the `<gchar *>' argument is
interpreted as a `<guint16 *>' cast to a `<gchar *>' and each
`<guint16>' indexes the glyphs in the font directly.

   For functions taking a `<gchar *>', if the font is of type
`GDK_FONT_FONTSET', then the input string is interpreted as a
"multibyte" encoded according to the current locale. (A multibyte
string is one in which each character may consist of one or more bytes,
with different lengths for different characters in the string). They
can be converted to and from wide character strings (see below) using
`gdk-wcstombs' and `gdk-mbstowcs'.) The string will be rendered using
one or more different fonts from the fontset.

   For a number of the text-measuring functions, GDK provides a variant
(such as `gdk-text-width-wc') which takes a `<gdk-wchar *>' instead of a
`<gchar *>'. The input is then taken to be a wide character string in
the encoding of the current locale. (A wide character string is a
string in which each character consists of several bytes, and the width
of each character in the string is constant.)

   GDK provides functions to determine a number of different
measurements (metrics) for a given string. (Need diagram here).

DESCENT

LEFT BEARING

RIGHT BEARING

WIDTH BEARING

   The vertical distance from the origin of the drawing opereration to
the top of the drawn character.

   The vertical distance from the origin of the drawing opereration to
the bottom of the drawn character.

   The horizontal distance from the origin of the drawing operation to
the left-most part of the drawn character.

   The horizontal distance from the origin of the drawing operation to
the right-most part of the drawn character.

   The horizontal distance from the origin of the drawing operation to
the correct origin for drawing another string to follow the current
one. Depending on the font, this could be greater than or less than the
right bearing.

15.2 Usage
==========

 -- Class: <gdk-font>
     Derives from `<gboxed>'.


 -- Function: gdk-font-load (font_name `mchars') =>  (ret `<gdk-font>')
     `gdk_font_load' is deprecated and should not be used in
     newly-written code.

     Loads a font.

     The font may be newly loaded or looked up the font in a cache. You
     should make no assumptions about the initial reference count.

    FONT-NAME
          a XLFD describing the font to load.

    RET
          a `<gdk-font>', or ``#f'' if the font could not be loaded.



 -- Function: gdk-fontset-load (fontset_name `mchars') => 
          (ret `<gdk-font>')
     `gdk_fontset_load' is deprecated and should not be used in
     newly-written code.

     Loads a fontset.

     The fontset may be newly loaded or looked up in a cache. You
     should make no assumptions about the initial reference count.

    FONTSET-NAME
          a comma-separated list of XLFDs describing the component
          fonts of the fontset to load.

    RET
          a `<gdk-font>', or ``#f'' if the fontset could not be loaded.



 -- Function: gdk-font-from-description
          (font_desc `<pango-font-description>') =>  (ret `<gdk-font>')
     `gdk_font_from_description' is deprecated and should not be used in
     newly-written code.

     Load a `<gdk-font>' based on a Pango font description. This font
     will only be an approximation of the Pango font, and
     internationalization will not be handled correctly. This function
     should only be used for legacy code that cannot be easily
     converted to use Pango. Using Pango directly will produce better
     results.

    FONT-DESC
          a `<pango-font-description>'.

    RET
          the newly loaded font, or ``#f'' if the font cannot be loaded.



 -- Function: gdk-font-id (self `<gdk-font>') =>  (ret `int')
     `gdk_font_id' is deprecated and should not be used in
     newly-written code.

     Returns the X Font ID for the given font.

    FONT
          a `<gdk-font>'.

    RET
          the numeric X Font ID



 -- Function: gdk-string-extents (font `<gdk-font>') (string `mchars')
          =>  (lbearing `int') (rbearing `int') (width `int')
          (ascent `int') (descent `int')
     `gdk_string_extents' is deprecated and should not be used in
     newly-written code.

     Gets the metrics of a nul-terminated string.

    FONT
          a `<gdk-font>'.

    STRING
          the nul-terminated string to measure.

    LBEARING
          the left bearing of the string.

    RBEARING
          the right bearing of the string.

    WIDTH
          the width of the string.

    ASCENT
          the ascent of the string.

    DESCENT
          the descent of the string.



 -- Function: gdk-string-width (font `<gdk-font>') (string `mchars')
          =>  (ret `int')
     `gdk_string_width' is deprecated and should not be used in
     newly-written code.

     Determines the width of a nul-terminated string. (The distance
     from the origin of the string to the point where the next string
     in a sequence of strings should be drawn)

    FONT
          a `<gdk-font>'

    STRING
          the nul-terminated string to measure

    RET
          the width of the string in pixels.



 -- Function: gdk-text-width (font `<gdk-font>') (text `mchars')
          (text_length `int') =>  (ret `int')
     `gdk_text_width' is deprecated and should not be used in
     newly-written code.

     Determines the width of a given string.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure.

    TEXT-LENGTH
          the length of the text in bytes.

    RET
          the width of the string in pixels.



 -- Function: gdk-char-width (font `<gdk-font>') (character `char') => 
          (ret `int')
     `gdk_char_width' is deprecated and should not be used in
     newly-written code. Use `gdk-text-extents' instead.

     Determines the width of a given character.

    FONT
          a `<gdk-font>'

    CHARACTER
          the character to measure.

    RET
          the width of the character in pixels.



 -- Function: gdk-char-width-wc (font `<gdk-font>')
          (character `unsigned-int32') =>  (ret `int')
     `gdk_char_width_wc' is deprecated and should not be used in
     newly-written code.

     Determines the width of a given wide character. (Encoded in the
     wide-character encoding of the current locale).

    FONT
          a `<gdk-font>'

    CHARACTER
          the character to measure.

    RET
          the width of the character in pixels.



 -- Function: gdk-string-measure (font `<gdk-font>') (string `mchars')
          =>  (ret `int')
     `gdk_string_measure' is deprecated and should not be used in
     newly-written code.

     Determines the distance from the origin to the rightmost portion
     of a nul-terminated string when drawn. This is not the correct
     value for determining the origin of the next portion when drawing
     text in multiple pieces. See `gdk-string-width'.

    FONT
          a `<gdk-font>'

    STRING
          the nul-terminated string to measure.

    RET
          the right bearing of the string in pixels.



 -- Function: gdk-text-measure (font `<gdk-font>') (text `mchars')
          (text_length `int') =>  (ret `int')
     `gdk_text_measure' is deprecated and should not be used in
     newly-written code.

     Determines the distance from the origin to the rightmost portion
     of a string when drawn. This is not the correct value for
     determining the origin of the next portion when drawing text in
     multiple pieces. See `gdk-text-width'.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure.

    TEXT-LENGTH
          the length of the text in bytes.

    RET
          the right bearing of the string in pixels.



 -- Function: gdk-char-measure (font `<gdk-font>') (character `char')
          =>  (ret `int')
     `gdk_char_measure' is deprecated and should not be used in
     newly-written code.

     Determines the distance from the origin to the rightmost portion
     of a character when drawn. This is not the correct value for
     determining the origin of the next portion when drawing text in
     multiple pieces.

    FONT
          a `<gdk-font>'

    CHARACTER
          the character to measure.

    RET
          the right bearing of the character in pixels.



 -- Function: gdk-string-height (font `<gdk-font>') (string `mchars')
          =>  (ret `int')
     `gdk_string_height' is deprecated and should not be used in
     newly-written code.

     Determines the total height of a given nul-terminated string. This
     value is not generally useful, because you cannot determine how
     this total height will be drawn in relation to the baseline. See
     `gdk-string-extents'.

    FONT
          a `<gdk-font>'

    STRING
          the nul-terminated string to measure.

    RET
          the height of the string in pixels.



 -- Function: gdk-text-height (font `<gdk-font>') (text `mchars')
          (text_length `int') =>  (ret `int')
     `gdk_text_height' is deprecated and should not be used in
     newly-written code.

     Determines the total height of a given string. This value is not
     generally useful, because you cannot determine how this total
     height will be drawn in relation to the baseline. See
     `gdk-text-extents'.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure.

    TEXT-LENGTH
          the length of the text in bytes.

    RET
          the height of the string in pixels.



 -- Function: gdk-char-height (font `<gdk-font>') (character `char')
          =>  (ret `int')
     `gdk_char_height' is deprecated and should not be used in
     newly-written code. Use `gdk-text-extents' instead.

     Determines the total height of a given character. This value is
     not generally useful, because you cannot determine how this total
     height will be drawn in relation to the baseline. See
     `gdk-text-extents'.

    FONT
          a `<gdk-font>'

    CHARACTER
          the character to measure.

    RET
          the height of the character in pixels.




File: guile-gnome-gdk.info,  Node: Cursors,  Next: Windows,  Prev: Fonts,  Up: Top

16 Cursors
**********

Standard and pixmap cursors

16.1 Overview
=============

These functions are used to create and destroy cursors. There is a
number of standard cursors, but it is also possible to construct new
cursors from pixmaps and pixbufs. There may be limitations as to what
kinds of cursors can be constructed on a given display, see
`gdk-display-supports-cursor-alpha',
`gdk-display-supports-cursor-color',
`gdk-display-get-default-cursor-size' and
`gdk-display-get-maximal-cursor-size'.

   Cursors by themselves are not very interesting, they must be be
bound to a window for users to see them. This is done with
`gdk-window-set-cursor' or by setting the cursor member of the
`<gdk-window-attr>' struct passed to `gdk-window-new'.

16.2 Usage
==========

 -- Class: <gdk-cursor>
     Derives from `<gboxed>'.


 -- Function: gdk-cursor-new (cursor_type `<gdk-cursor-type>') => 
          (ret `<gdk-cursor>')
     Creates a new cursor from the set of builtin cursors for the
     default display.  See `gdk-cursor-new-for-display'.

     To make the cursor invisible, use `gdk-cursor-new-from-pixmap' to
     create a cursor with no pixels in it.

    CURSOR-TYPE
          cursor to create

    RET
          a new `<gdk-cursor>'



 -- Function: gdk-cursor-new-from-pixmap (source `<gdk-pixmap>')
          (mask `<gdk-pixmap>') (fg `<gdk-color>') (bg `<gdk-color>')
          (x `int') (y `int') =>  (ret `<gdk-cursor>')
     Creates a new cursor from a given pixmap and mask. Both the pixmap
     and mask must have a depth of 1 (i.e. each pixel has only 2 values
     - on or off). The standard cursor size is 16 by 16 pixels. You can
     create a bitmap from inline data as in the below example.


          /* This data is in X bitmap format, and can be created with the 'bitmap'
             utility. */
          &#x0023;define cursor1_width 16
          &#x0023;define cursor1_height 16
          static unsigned char cursor1_bits[] = {
            0x80, 0x01, 0x40, 0x02, 0x20, 0x04, 0x10, 0x08, 0x08, 0x10, 0x04, 0x20,
            0x82, 0x41, 0x41, 0x82, 0x41, 0x82, 0x82, 0x41, 0x04, 0x20, 0x08, 0x10,
            0x10, 0x08, 0x20, 0x04, 0x40, 0x02, 0x80, 0x01};

          static unsigned char cursor1mask_bits[] = {
            0x80, 0x01, 0xc0, 0x03, 0x60, 0x06, 0x30, 0x0c, 0x18, 0x18, 0x8c, 0x31,
            0xc6, 0x63, 0x63, 0xc6, 0x63, 0xc6, 0xc6, 0x63, 0x8c, 0x31, 0x18, 0x18,
            0x30, 0x0c, 0x60, 0x06, 0xc0, 0x03, 0x80, 0x01};


           GdkCursor *cursor;
           GdkPixmap *source, *mask;
           GdkColor fg = { 0, 65535, 0, 0 }; /* Red. */
           GdkColor bg = { 0, 0, 0, 65535 }; /* Blue. */


           source = gdk_bitmap_create_from_data (NULL, cursor1_bits,
                                                 cursor1_width, cursor1_height);
           mask = gdk_bitmap_create_from_data (NULL, cursor1mask_bits,
                                               cursor1_width, cursor1_height);
           cursor = gdk_cursor_new_from_pixmap (source, mask, &fg, &bg, 8, 8);
           gdk_pixmap_unref (source);
           gdk_pixmap_unref (mask);


           gdk_window_set_cursor (widget->window, cursor);

    SOURCE
          the pixmap specifying the cursor.

    MASK
          the pixmap specifying the mask, which must be the same size
          as SOURCE.

    FG
          the foreground color, used for the bits in the source which
          are 1. The color does not have to be allocated first.

    BG
          the background color, used for the bits in the source which
          are 0. The color does not have to be allocated first.

    X
          the horizontal offset of the 'hotspot' of the cursor.

    Y
          the vertical offset of the 'hotspot' of the cursor.

    RET
          a new `<gdk-cursor>'.



 -- Function: gdk-cursor-new-from-pixbuf (display `<gdk-display>')
          (pixbuf `<gdk-pixbuf>') (x `int') (y `int') => 
          (ret `<gdk-cursor>')
     Creates a new cursor from a pixbuf.

     Not all GDK backends support RGBA cursors. If they are not
     supported, a monochrome approximation will be displayed. The
     functions `gdk-display-supports-cursor-alpha' and
     `gdk-display-supports-cursor-color' can be used to determine
     whether RGBA cursors are supported;
     `gdk-display-get-default-cursor-size' and
     `gdk-display-get-maximal-cursor-size' give information about
     cursor sizes.

     On the X backend, support for RGBA cursors requires a sufficently
     new version of the X Render extension.

    DISPLAY
          the `<gdk-display>' for which the cursor will be created

    PIXBUF
          the `<gdk-pixbuf>' containing the cursor image

    X
          the horizontal offset of the 'hotspot' of the cursor.

    Y
          the vertical offset of the 'hotspot' of the cursor.

    RET
          a new `<gdk-cursor>'.


     Since 2.4


 -- Function: gdk-cursor-new-from-name (display `<gdk-display>')
          (name `mchars') =>  (ret `<gdk-cursor>')
     Creates a new cursor by looking up NAME in the current cursor
     theme.

    DISPLAY
          the `<gdk-display>' for which the cursor will be created

    NAME
          the name of the cursor

    RET
          a new `<gdk-cursor>', or ``#f'' if there is no cursor with the
          given name


     Since 2.8


 -- Function: gdk-cursor-new-for-display (display `<gdk-display>')
          (cursor_type `<gdk-cursor-type>') =>  (ret `<gdk-cursor>')
     Creates a new cursor from the set of builtin cursors. Some useful
     ones are:

        *        *        *        *        *        *        *        *        *        *        *        *        *        *        *        *        *
     `<gdk-right-ptr>' (right-facing arrow)

     `<gdk-crosshair>' (crosshair)

     (I-beam)

     (busy)

     (for moving objects)

     (a right-pointing hand)

     (a left-pointing hand)

     `<gdk-left-side>' (resize left side)

     `<gdk-right-side>' (resize right side)

     `<gdk-top-left-corner>' (resize northwest corner)

     `<gdk-top-right-corner>' (resize northeast corner)

     `<gdk-bottom-left-corner>' (resize southwest corner)

     `<gdk-bottom-right-corner>' (resize southeast corner)

     `<gdk-top-side>' (resize top side)

     `<gdk-bottom-side>' (resize bottom side)

     `<gdk-sb-h-double-arrow>' (move vertical splitter)

     `<gdk-sb-v-double-arrow>' (move horizontal splitter)

     To make the cursor invisible, use `gdk-cursor-new-from-pixmap' to
     create a cursor with no pixels in it.

    DISPLAY
          the `<gdk-display>' for which the cursor will be created

    CURSOR-TYPE
          cursor to create

    RET
          a new `<gdk-cursor>'


     Since 2.2


 -- Function: gdk-cursor-get-display (self `<gdk-cursor>') => 
          (ret `<gdk-display>')
     Returns the display on which the `<gdk-cursor>' is defined.

    CURSOR
          a `<gdk-cursor>'.

    RET
          the `<gdk-display>' associated to CURSOR


     Since 2.2


 -- Function: gdk-cursor-get-image (self `<gdk-cursor>') => 
          (ret `<gdk-pixbuf>')
     Returns a `<gdk-pixbuf>' with the image used to display the cursor.

     Note that depending on the capabilities of the windowing system
     and on the cursor, GDK may not be able to obtain the image data.
     In this case, ``#f'' is returned.

    CURSOR
          a `<gdk-cursor>'

    RET
          a `<gdk-pixbuf>' representing CURSOR, or ``#f''


     Since 2.8



File: guile-gnome-gdk.info,  Node: Windows,  Next: Events,  Prev: Cursors,  Up: Top

17 Windows
**********

Onscreen display areas in the target window system

17.1 Overview
=============

A `<gdk-window>' is a rectangular region on the screen. It's a low-level
object, used to implement high-level objects such as `<gtk-widget>' and
`<gtk-window>' on the GTK+ level. A `<gtk-window>' is a toplevel
window, the thing a user might think of as a "window" with a titlebar
and so on; a `<gtk-window>' may contain many `<gdk-window>'. For
example, each `<gtk-button>' has a `<gdk-window>' associated with it.

17.2 Usage
==========

 -- Function: gdk-window-destroy (self `<gdk-window>')
 -- Method: destroy
     Destroys the window system resources associated with WINDOW and
     decrements WINDOW's reference count. The window system resources
     for all children of WINDOW are also destroyed, but the children's
     reference counts are not decremented.

     Note that a window will not be destroyed automatically when its
     reference count reaches zero. You must call this function yourself
     before that happens.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-get-window-type (self `<gdk-window>') => 
          (ret `<gdk-window-type>')
 -- Method: get-window-type
     Gets the type of the window. See `<gdk-window-type>'.

    WINDOW
          a `<gdk-window>'

    RET
          type of window



 -- Function: gdk-window-at-pointer =>  (ret `<gdk-window>')
          (win_x `int') (win_y `int')
     Obtains the window underneath the mouse pointer, returning the
     location of that window in WIN-X, WIN-Y. Returns ``#f'' if the
     window under the mouse pointer is not known to GDK (if the window
     belongs to another application and a `<gdk-window>' hasn't been
     created for it with `gdk-window-foreign-new')

     NOTE: For multihead-aware widgets or applications use
     `gdk-display-get-window-at-pointer' instead.

    WIN-X
          return location for origin of the window under the pointer

    WIN-Y
          return location for origin of the window under the pointer

    RET
          window under the mouse pointer



 -- Function: gdk-window-show (self `<gdk-window>')
 -- Method: show
     Like `gdk-window-show-unraised', but also raises the window to the
     top of the window stack (moves the window to the front of the
     Z-order).

     This function maps a window so it's visible onscreen. Its opposite
     is `gdk-window-hide'.

     When implementing a `<gtk-widget>', you should call this function
     on the widget's `<gdk-window>' as part of the "map" method.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-show-unraised (self `<gdk-window>')
 -- Method: show-unraised
     Shows a `<gdk-window>' onscreen, but does not modify its stacking
     order. In contrast, `gdk-window-show' will raise the window to the
     top of the window stack.

     On the X11 platform, in Xlib terms, this function calls
     `x-map-window' (it also updates some internal GDK state, which
     means that you can't really use `x-map-window' directly on a GDK
     window).

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-hide (self `<gdk-window>')
 -- Method: hide
     For toplevel windows, withdraws them, so they will no longer be
     known to the window manager; for all windows, unmaps them, so they
     won't be displayed.  Normally done automatically as part of
     `gtk-widget-hide'.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-is-visible (self `<gdk-window>') => 
          (ret `bool')
 -- Method: is-visible
     Checks whether the window has been mapped (with `gdk-window-show'
     or `gdk-window-show-unraised').

    WINDOW
          a `<gdk-window>'

    RET
          ``#t'' if the window is mapped



 -- Function: gdk-window-is-viewable (self `<gdk-window>') => 
          (ret `bool')
 -- Method: is-viewable
     Check if the window and all ancestors of the window are mapped.
     (This is not necessarily "viewable" in the X sense, since we only
     check as far as we have GDK window parents, not to the root
     window.)

    WINDOW
          a `<gdk-window>'

    RET
          ``#t'' if the window is viewable



 -- Function: gdk-window-get-state (self `<gdk-window>') => 
          (ret `<gdk-window-state>')
 -- Method: get-state
     Gets the bitwise OR of the currently active window state flags,
     from the `<gdk-window-state>' enumeration.

    WINDOW
          a `<gdk-window>'

    RET
          window state bitfield



 -- Function: gdk-window-withdraw (self `<gdk-window>')
 -- Method: withdraw
     Withdraws a window (unmaps it and asks the window manager to
     forget about it).  This function is not really useful as
     `gdk-window-hide' automatically withdraws toplevel windows before
     hiding them.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-iconify (self `<gdk-window>')
 -- Method: iconify
     Asks to iconify (minimize) WINDOW. The window manager may choose
     to ignore the request, but normally will honor it. Using
     `gtk-window-iconify' is preferred, if you have a `<gtk-window>'
     widget.

     This function only makes sense when WINDOW is a toplevel window.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-deiconify (self `<gdk-window>')
 -- Method: deiconify
     Attempt to deiconify (unminimize) WINDOW. On X11 the window
     manager may choose to ignore the request to deiconify. When using
     GTK+, use `gtk-window-deiconify' instead of the `<gdk-window>'
     variant. Or better yet, you probably want to use
     `gtk-window-present', which raises the window, focuses it,
     unminimizes it, and puts it on the current desktop.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-stick (self `<gdk-window>')
 -- Method: stick
     "Pins" a window such that it's on all workspaces and does not
     scroll with viewports, for window managers that have scrollable
     viewports. (When using `<gtk-window>', `gtk-window-stick' may be
     more useful.)

     On the X11 platform, this function depends on window manager
     support, so may have no effect with many window managers. However,
     GDK will do the best it can to convince the window manager to
     stick the window. For window managers that don't support this
     operation, there's nothing you can do to force it to happen.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-unstick (self `<gdk-window>')
 -- Method: unstick
     Reverse operation for `gdk-window-stick'; see `gdk-window-stick',
     and `gtk-window-unstick'.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-maximize (self `<gdk-window>')
 -- Method: maximize
     Maximizes the window. If the window was already maximized, then
     this function does nothing.

     On X11, asks the window manager to maximize WINDOW, if the window
     manager supports this operation. Not all window managers support
     this, and some deliberately ignore it or don't have a concept of
     "maximized"; so you can't rely on the maximization actually
     happening. But it will happen with most standard window managers,
     and GDK makes a best effort to get it to happen.

     On Windows, reliably maximizes the window.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-unmaximize (self `<gdk-window>')
 -- Method: unmaximize
     Unmaximizes the window. If the window wasn't maximized, then this
     function does nothing.

     On X11, asks the window manager to unmaximize WINDOW, if the window
     manager supports this operation. Not all window managers support
     this, and some deliberately ignore it or don't have a concept of
     "maximized"; so you can't rely on the unmaximization actually
     happening. But it will happen with most standard window managers,
     and GDK makes a best effort to get it to happen.

     On Windows, reliably unmaximizes the window.

    WINDOW
          a toplevel `<gdk-window>'



 -- Function: gdk-window-fullscreen (self `<gdk-window>')
 -- Method: fullscreen
     Moves the window into fullscreen mode. This means the window
     covers the entire screen and is above any panels or task bars.

     If the window was already fullscreen, then this function does
     nothing.

     On X11, asks the window manager to put WINDOW in a fullscreen
     state, if the window manager supports this operation. Not all
     window managers support this, and some deliberately ignore it or
     don't have a concept of "fullscreen"; so you can't rely on the
     fullscreenification actually happening. But it will happen with
     most standard window managers, and GDK makes a best effort to get
     it to happen.

    WINDOW
          a toplevel `<gdk-window>'


     Since 2.2


 -- Function: gdk-window-unfullscreen (self `<gdk-window>')
 -- Method: unfullscreen
     Moves the window out of fullscreen mode. If the window was not
     fullscreen, does nothing.

     On X11, asks the window manager to move WINDOW out of the
     fullscreen state, if the window manager supports this operation.
     Not all window managers support this, and some deliberately ignore
     it or don't have a concept of "fullscreen"; so you can't rely on
     the unfullscreenification actually happening.  But it will happen
     with most standard window managers, and GDK makes a best effort to
     get it to happen.

    WINDOW
          a toplevel `<gdk-window>'


     Since 2.2


 -- Function: gdk-window-set-keep-above (self `<gdk-window>')
          (setting `bool')
 -- Method: set-keep-above
     Set if WINDOW must be kept above other windows. If the window was
     already above, then this function does nothing.

     On X11, asks the window manager to keep WINDOW above, if the window
     manager supports this operation. Not all window managers support
     this, and some deliberately ignore it or don't have a concept of
     "keep above"; so you can't rely on the window being kept above.
     But it will happen with most standard window managers, and GDK
     makes a best effort to get it to happen.

    WINDOW
          a toplevel `<gdk-window>'

    SETTING
          whether to keep WINDOW above other windows


     Since 2.4


 -- Function: gdk-window-set-keep-below (self `<gdk-window>')
          (setting `bool')
 -- Method: set-keep-below
     Set if WINDOW must be kept below other windows. If the window was
     already below, then this function does nothing.

     On X11, asks the window manager to keep WINDOW below, if the window
     manager supports this operation. Not all window managers support
     this, and some deliberately ignore it or don't have a concept of
     "keep below"; so you can't rely on the window being kept below.
     But it will happen with most standard window managers, and GDK
     makes a best effort to get it to happen.

    WINDOW
          a toplevel `<gdk-window>'

    SETTING
          whether to keep WINDOW below other windows


     Since 2.4


 -- Function: gdk-window-move (self `<gdk-window>') (x `int') (y `int')
 -- Method: move
     Repositions a window relative to its parent window. For toplevel
     windows, window managers may ignore or modify the move; you should
     probably use `gtk-window-move' on a `<gtk-window>' widget anyway,
     instead of using GDK functions. For child windows, the move will
     reliably succeed.

     If you're also planning to resize the window, use
     `gdk-window-move-resize' to both move and resize simultaneously,
     for a nicer visual effect.

    WINDOW
          a `<gdk-window>'

    X
          X coordinate relative to window's parent

    Y
          Y coordinate relative to window's parent



 -- Function: gdk-window-resize (self `<gdk-window>') (width `int')
          (height `int')
 -- Method: resize
     Resizes WINDOW; for toplevel windows, asks the window manager to
     resize the window. The window manager may not allow the resize.
     When using GTK+, use `gtk-window-resize' instead of this low-level
     GDK function.

     Windows may not be resized below 1x1.

     If you're also planning to move the window, use
     `gdk-window-move-resize' to both move and resize simultaneously,
     for a nicer visual effect.

    WINDOW
          a `<gdk-window>'

    WIDTH
          new width of the window

    HEIGHT
          new height of the window



 -- Function: gdk-window-move-resize (self `<gdk-window>') (x `int')
          (y `int') (width `int') (height `int')
 -- Method: move-resize
     Equivalent to calling `gdk-window-move' and `gdk-window-resize',
     except that both operations are performed at once, avoiding
     strange visual effects. (i.e. the user may be able to see the
     window first move, then resize, if you don't use
     `gdk-window-move-resize'.)

    WINDOW
          a `<gdk-window>'

    X
          new X position relative to window's parent

    Y
          new Y position relative to window's parent

    WIDTH
          new width

    HEIGHT
          new height



 -- Function: gdk-window-scroll (self `<gdk-window>') (dx `int')
          (dy `int')
 -- Method: scroll
     Scroll the contents of WINDOW, both pixels and children, by the
     given amount. WINDOW itself does not move. Portions of the window
     that the scroll operation brings in from offscreen areas are
     invalidated. The invalidated region may be bigger than what would
     strictly be necessary. (For X11, a minimum area will be
     invalidated if the window has no subwindows, or if the edges of the
     window's parent do not extend beyond the edges of the window. In
     other cases, a multi-step process is used to scroll the window
     which may produce temporary visual artifacts and unnecessary
     invalidations.)

    WINDOW
          a `<gdk-window>'

    DX
          Amount to scroll in the X direction

    DY
          Amount to scroll in the Y direction



 -- Function: gdk-window-move-region (self `<gdk-window>')
          (region `<gdk-region>') (dx `int') (dy `int')
 -- Method: move-region
     Move the part of WINDOW indicated by REGION by DY pixels in the Y
     direction and DX pixels in the X direction. The portions of REGION
     that not covered by the new position of REGION are invalidated.

     Child windows are not moved.

    WINDOW
          a `<gdk-window>'

    REGION
          The `<gdk-region>' to move

    DX
          Amount to move in the X direction

    DY
          Amount to move in the Y direction


     Since 2.8


 -- Function: gdk-window-reparent (self `<gdk-window>')
          (new_parent `<gdk-window>') (x `int') (y `int')
 -- Method: reparent
     Reparents WINDOW into the given NEW-PARENT. The window being
     reparented will be unmapped as a side effect.

    WINDOW
          a `<gdk-window>'

    NEW-PARENT
          new parent to move WINDOW into

    X
          X location inside the new parent

    Y
          Y location inside the new parent



 -- Function: gdk-window-clear (self `<gdk-window>')
 -- Method: clear
     Clears an entire WINDOW to the background color or background
     pixmap.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-clear-area (self `<gdk-window>') (x `int')
          (y `int') (width `int') (height `int')
 -- Method: clear-area
     Clears an area of WINDOW to the background color or background
     pixmap.

    WINDOW
          a `<gdk-window>'

    X
          x coordinate of rectangle to clear

    Y
          y coordinate of rectangle to clear

    WIDTH
          width of rectangle to clear

    HEIGHT
          height of rectangle to clear



 -- Function: gdk-window-clear-area-e (self `<gdk-window>') (x `int')
          (y `int') (width `int') (height `int')
 -- Method: clear-area-e
     Like `gdk-window-clear-area', but also generates an expose event
     for the cleared area.

     This function has a stupid name because it dates back to the mists
     time, pre-GDK-1.0.

    WINDOW
          a `<gdk-window>'

    X
          x coordinate of rectangle to clear

    Y
          y coordinate of rectangle to clear

    WIDTH
          width of rectangle to clear

    HEIGHT
          height of rectangle to clear



 -- Function: gdk-window-raise (self `<gdk-window>')
 -- Method: raise
     Raises WINDOW to the top of the Z-order (stacking order), so that
     other windows with the same parent window appear below WINDOW.
     This is true whether or not the windows are visible.

     If WINDOW is a toplevel, the window manager may choose to deny the
     request to move the window in the Z-order, `gdk-window-raise' only
     requests the restack, does not guarantee it.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-lower (self `<gdk-window>')
 -- Method: lower
     Lowers WINDOW to the bottom of the Z-order (stacking order), so
     that other windows with the same parent window appear above
     WINDOW. This is true whether or not the other windows are visible.

     If WINDOW is a toplevel, the window manager may choose to deny the
     request to move the window in the Z-order, `gdk-window-lower' only
     requests the restack, does not guarantee it.

     Note that `gdk-window-show' raises the window again, so don't call
     this function before `gdk-window-show'. (Try
     `gdk-window-show-unraised'.)

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-focus (self `<gdk-window>')
          (timestamp `unsigned-int32')
 -- Method: focus
     Sets keyboard focus to WINDOW. In most cases, `gtk-window-present'
     should be used on a `<gtk-window>', rather than calling this
     function.

    WINDOW
          a `<gdk-window>'

    TIMESTAMP
          timestamp of the event triggering the window focus



 -- Function: gdk-window-register-dnd (self `<gdk-window>')
 -- Method: register-dnd
     Registers a window as a potential drop destination.

    WINDOW
          a `<gdk-window>'.



 -- Function: gdk-window-begin-resize-drag (self `<gdk-window>')
          (edge `<gdk-window-edge>') (button `int') (root_x `int')
          (root_y `int') (timestamp `unsigned-int32')
 -- Method: begin-resize-drag
     Begins a window resize operation (for a toplevel window). You
     might use this function to implement a "window resize grip," for
     example; in fact `<gtk-statusbar>' uses it. The function works
     best with window managers that support the Extended Window Manager
     Hints (http://www.freedesktop.org/Standards/wm-spec), but has a
     fallback implementation for other window managers.

    WINDOW
          a toplevel `<gdk-window>'

    EDGE
          the edge or corner from which the drag is started

    BUTTON
          the button being used to drag

    ROOT-X
          root window X coordinate of mouse click that began the drag

    ROOT-Y
          root window Y coordinate of mouse click that began the drag

    TIMESTAMP
          timestamp of mouse click that began the drag (use
          `gdk-event-get-time')



 -- Function: gdk-window-begin-move-drag (self `<gdk-window>')
          (button `int') (root_x `int') (root_y `int')
          (timestamp `unsigned-int32')
 -- Method: begin-move-drag
     Begins a window move operation (for a toplevel window). You might
     use this function to implement a "window move grip," for example.
     The function works best with window managers that support the
     Extended Window Manager Hints
     (http://www.freedesktop.org/Standards/wm-spec), but has a fallback
     implementation for other window managers.

    WINDOW
          a toplevel `<gdk-window>'

    BUTTON
          the button being used to drag

    ROOT-X
          root window X coordinate of mouse click that began the drag

    ROOT-Y
          root window Y coordinate of mouse click that began the drag

    TIMESTAMP
          timestamp of mouse click that began the drag



 -- Function: gdk-window-begin-paint-rect (self `<gdk-window>')
          (rectangle `<gdk-rectangle>')
 -- Method: begin-paint-rect
     A convenience wrapper around `gdk-window-begin-paint-region' which
     creates a rectangular region for you. See
     `gdk-window-begin-paint-region' for details.

    WINDOW
          a `<gdk-window>'

    RECTANGLE
          rectangle you intend to draw to



 -- Function: gdk-window-begin-paint-region (self `<gdk-window>')
          (region `<gdk-region>')
 -- Method: begin-paint-region
     Indicates that you are beginning the process of redrawing REGION. A
     backing store (offscreen buffer) large enough to contain REGION
     will be created. The backing store will be initialized with the
     background color or background pixmap for WINDOW. Then, all
     drawing operations performed on WINDOW will be diverted to the
     backing store. When you call `gdk-window-end-paint', the backing
     store will be copied to WINDOW, making it visible onscreen. Only
     the part of WINDOW contained in REGION will be modified; that is,
     drawing operations are clipped to REGION.

     The net result of all this is to remove flicker, because the user
     sees the finished product appear all at once when you call
     `gdk-window-end-paint'.  If you draw to WINDOW directly without
     calling `gdk-window-begin-paint-region', the user may see flicker
     as individual drawing operations are performed in sequence. The
     clipping and background-initializing features of
     `gdk-window-begin-paint-region' are conveniences for the
     programmer, so you can avoid doing that work yourself.

     When using GTK+, the widget system automatically places calls to
     `gdk-window-begin-paint-region' and `gdk-window-end-paint' around
     emissions of the expose_event signal. That is, if you're writing
     an expose event handler, you can assume that the exposed area in
     `<gdk-event-expose>' has already been cleared to the window
     background, is already set as the clip region, and already has a
     backing store. Therefore in most cases, application code need not
     call `gdk-window-begin-paint-region'. (You can disable the
     automatic calls around expose events on a widget-by-widget basis
     by calling `gtk-widget-set-double-buffered'.)

     If you call this function multiple times before calling the
     matching `gdk-window-end-paint', the backing stores are pushed
     onto a stack.  `gdk-window-end-paint' copies the topmost backing
     store onscreen, subtracts the topmost region from all other
     regions in the stack, and pops the stack. All drawing operations
     affect only the topmost backing store in the stack. One matching
     call to `gdk-window-end-paint' is required for each call to
     `gdk-window-begin-paint-region'.

    WINDOW
          a `<gdk-window>'

    REGION
          region you intend to draw to



 -- Function: gdk-window-end-paint (self `<gdk-window>')
 -- Method: end-paint
     Indicates that the backing store created by the most recent call to
     `gdk-window-begin-paint-region' should be copied onscreen and
     deleted, leaving the next-most-recent backing store or no backing
     store at all as the active paint region. See
     `gdk-window-begin-paint-region' for full details.  It is an error
     to call this function without a matching
     `gdk-window-begin-paint-region' first.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-invalidate-rect (self `<gdk-window>')
          (rect `<gdk-rectangle>') (invalidate_children `bool')
 -- Method: invalidate-rect
     A convenience wrapper around `gdk-window-invalidate-region' which
     invalidates a rectangular region. See
     `gdk-window-invalidate-region' for details.

    WINDOW
          a `<gdk-window>'

    RECT
          rectangle to invalidate

    INVALIDATE-CHILDREN
          whether to also invalidate child windows



 -- Function: gdk-window-invalidate-region (self `<gdk-window>')
          (region `<gdk-region>') (invalidate_children `bool')
 -- Method: invalidate-region
     Adds REGION to the update area for WINDOW. The update area is the
     region that needs to be redrawn, or "dirty region." The call
     `gdk-window-process-updates' sends one or more expose events to
     the window, which together cover the entire update area. An
     application would normally redraw the contents of WINDOW in
     response to those expose events.

     GDK will call `gdk-window-process-all-updates' on your behalf
     whenever your program returns to the main loop and becomes idle,
     so normally there's no need to do that manually, you just need to
     invalidate regions that you know should be redrawn.

     The INVALIDATE-CHILDREN parameter controls whether the region of
     each child window that intersects REGION will also be invalidated.
     If ``#f'', then the update area for child windows will remain
     unaffected.  See gdk_window_invalidate_maybe_recurse if you need
     fine grained control over which children are invalidated.

    WINDOW
          a `<gdk-window>'

    REGION
          a `<gdk-region>'

    INVALIDATE-CHILDREN
          ``#t'' to also invalidate child windows



 -- Function: gdk-window-get-update-area (self `<gdk-window>') => 
          (ret `<gdk-region>')
 -- Method: get-update-area
     Transfers ownership of the update area from WINDOW to the caller
     of the function. That is, after calling this function, WINDOW will
     no longer have an invalid/dirty region; the update area is removed
     from WINDOW and handed to you. If a window has no update area,
     `gdk-window-get-update-area' returns ``#f''. You are responsible
     for calling `gdk-region-destroy' on the returned region if it's
     non-``#f''.

    WINDOW
          a `<gdk-window>'

    RET
          the update area for WINDOW



 -- Function: gdk-window-freeze-updates (self `<gdk-window>')
 -- Method: freeze-updates
     Temporarily freezes a window such that it won't receive expose
     events. The window will begin receiving expose events again when
     `gdk-window-thaw-updates' is called. If `gdk-window-freeze-updates'
     has been called more than once, `gdk-window-thaw-updates' must be
     called an equal number of times to begin processing exposes.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-thaw-updates (self `<gdk-window>')
 -- Method: thaw-updates
     Thaws a window frozen with `gdk-window-freeze-updates'.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-process-all-updates
     Calls `gdk-window-process-updates' for all windows (see
     `<gdk-window>') in the application.


 -- Function: gdk-window-process-updates (self `<gdk-window>')
          (update_children `bool')
 -- Method: process-updates
     Sends one or more expose events to WINDOW. The areas in each
     expose event will cover the entire update area for the window (see
     `gdk-window-invalidate-region' for details). Normally GDK calls
     `gdk-window-process-all-updates' on your behalf, so there's no
     need to call this function unless you want to force expose events
     to be delivered immediately and synchronously (vs. the usual case,
     where GDK delivers them in an idle handler). Occasionally this is
     useful to produce nicer scrolling behavior, for example.

    WINDOW
          a `<gdk-window>'

    UPDATE-CHILDREN
          whether to also process updates for child windows



 -- Function: gdk-window-set-debug-updates (setting `bool')
     With update debugging enabled, calls to
     `gdk-window-invalidate-region' clear the invalidated region of the
     screen to a noticeable color, and GDK pauses for a short time
     before sending exposes to windows during
     `gdk-window-process-updates'. The net effect is that you can see
     the invalid region for each window and watch redraws as they
     occur. This allows you to diagnose inefficiencies in your
     application.

     In essence, because the GDK rendering model prevents all flicker,
     if you are redrawing the same region 400 times you may never
     notice, aside from noticing a speed problem. Enabling update
     debugging causes GTK to flicker slowly and noticeably, so you can
     see exactly what's being redrawn when, in what order.

     The -gtk-debug=updates command line option passed to GTK+ programs
     enables this debug option at application startup time. That's
     usually more useful than calling `gdk-window-set-debug-updates'
     yourself, though you might want to use this function to enable
     updates sometime after application startup time.

    SETTING
          ``#t'' to turn on update debugging



 -- Function: gdk-window-configure-finished (self `<gdk-window>')
 -- Method: configure-finished
     Signal to the window system that the application has finished
     handling Configure events it has received. Window Managers can use
     this to better synchronize the frame repaint with the application.
     GTK+ applications will automatically call this function when
     appropriate.

     This function can only be called if
     `gdk-window-enable-synchronized-configure' was called previously.

    WINDOW
          a toplevel `<gdk-window>'


     Since 2.6


 -- Function: gdk-window-set-override-redirect (self `<gdk-window>')
          (override_redirect `bool')
 -- Method: set-override-redirect
     An override redirect window is not under the control of the window
     manager. This means it won't have a titlebar, won't be
     minimizable, etc. - it will be entirely under the control of the
     application. The window manager can't see the override redirect
     window at all.

     Override redirect should only be used for short-lived temporary
     windows, such as popup menus. `<gtk-menu>' uses an override
     redirect window in its implementation, for example.

    WINDOW
          a toplevel `<gdk-window>'

    OVERRIDE-REDIRECT
          ``#t'' if window should be override redirect



 -- Function: gdk-window-set-accept-focus (self `<gdk-window>')
          (accept_focus `bool')
 -- Method: set-accept-focus
     Setting ACCEPT-FOCUS to ``#f'' hints the desktop environment that
     the window doesn't want to receive input focus.

     On X, it is the responsibility of the window manager to interpret
     this hint.  ICCCM-compliant window manager usually respect it.

    WINDOW
          a toplevel `<gdk-window>'

    ACCEPT-FOCUS
          ``#t'' if the window should receive input focus


     Since 2.4


 -- Function: gdk-window-set-focus-on-map (self `<gdk-window>')
          (focus_on_map `bool')
 -- Method: set-focus-on-map
     Setting FOCUS-ON-MAP to ``#f'' hints the desktop environment that
     the window doesn't want to receive input focus when it is mapped.
     focus_on_map should be turned off for windows that aren't triggered
     interactively (such as popups from network activity).

     On X, it is the responsibility of the window manager to interpret
     this hint.  Window managers following the freedesktop.org window
     manager extension specification should respect it.

    WINDOW
          a toplevel `<gdk-window>'

    FOCUS-ON-MAP
          ``#t'' if the window should receive input focus when mapped


     Since 2.6


 -- Function: gdk-window-shape-combine-mask (self `<gdk-window>')
          (mask `<gdk-drawable>') (x `int') (y `int')
 -- Method: shape-combine-mask
     Applies a shape mask to WINDOW. Pixels in WINDOW corresponding to
     set bits in the MASK will be visible; pixels in WINDOW
     corresponding to unset bits in the MASK will be transparent. This
     gives a non-rectangular window.

     If MASK is ``#f'', the shape mask will be unset, and the X/Y
     parameters are not used.

     On the X11 platform, this uses an X server extension which is
     widely available on most common platforms, but not available on
     very old X servers, and occasionally the implementation will be
     buggy. On servers without the shape extension, this function will
     do nothing.

     On the Win32 platform the functionality is always present.

     This function works on both toplevel and child windows.

    WINDOW
          a `<gdk-window>'

    MASK
          shape mask

    X
          X position of shape mask with respect to WINDOW

    Y
          Y position of shape mask with respect to WINDOW



 -- Function: gdk-window-shape-combine-region (self `<gdk-window>')
          (shape_region `<gdk-region>') (offset_x `int')
          (offset_y `int')
 -- Method: shape-combine-region
     Makes pixels in WINDOW outside SHAPE-REGION be transparent, so that
     the window may be nonrectangular. See also
     `gdk-window-shape-combine-mask' to use a bitmap as the mask.

     If SHAPE-REGION is ``#f'', the shape will be unset, so the whole
     window will be opaque again. OFFSET-X and OFFSET-Y are ignored if
     SHAPE-REGION is ``#f''.

     On the X11 platform, this uses an X server extension which is
     widely available on most common platforms, but not available on
     very old X servers, and occasionally the implementation will be
     buggy. On servers without the shape extension, this function will
     do nothing.

     On the Win32 platform, this functionality is always present.

     This function works on both toplevel and child windows.

    WINDOW
          a `<gdk-window>'

    SHAPE-REGION
          region of window to be non-transparent

    OFFSET-X
          X position of SHAPE-REGION in WINDOW coordinates

    OFFSET-Y
          Y position of SHAPE-REGION in WINDOW coordinates



 -- Function: gdk-window-set-child-shapes (self `<gdk-window>')
 -- Method: set-child-shapes
     Sets the shape mask of WINDOW to the union of shape masks for all
     children of WINDOW, ignoring the shape mask of WINDOW itself.
     Contrast with `gdk-window-merge-child-shapes' which includes the
     shape mask of WINDOW in the masks to be merged.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-merge-child-shapes (self `<gdk-window>')
 -- Method: merge-child-shapes
     Merges the shape masks for any child windows into the shape mask
     for WINDOW. i.e. the union of all masks for WINDOW and its
     children will become the new mask for WINDOW. See
     `gdk-window-shape-combine-mask'.

     This function is distinct from `gdk-window-set-child-shapes'
     because it includes WINDOW's shape mask in the set of shapes to be
     merged.

    WINDOW
          a `<gdk-window>'



 -- Function: gdk-window-input-shape-combine-mask (self `<gdk-window>')
          (mask `<gdk-drawable>') (x `int') (y `int')
 -- Method: input-shape-combine-mask
     Like `gdk-window-shape-combine-mask', but the shape applies only
     to event handling. Mouse events which happen while the pointer
     position corresponds to an unset bit in the mask will be passed on
     the window below WINDOW.

     An input shape is typically used with RGBA windows. The alpha
     channel of the window defines which pixels are invisible and
     allows for nicely antialiased borders, and the input shape
     controls where the window is "clickable".

     On the X11 platform, this requires version 1.1 of the shape
     extension.

     On the Win32 platform, this functionality is not present and the
     function does nothing.

    WINDOW
          a `<gdk-window>'

    MASK
          shape mask

    X
          X position of shape mask with respect to WINDOW

    Y
          Y position of shape mask with respect to WINDOW


     Since 2.10


 -- Function: gdk-window-set-child-input-shapes (self `<gdk-window>')
 -- Method: set-child-input-shapes
     Sets the input shape mask of WINDOW to the union of input shape
     masks for all children of WINDOW, ignoring the input shape mask of
     WINDOW itself. Contrast with `gdk-window-merge-child-input-shapes'
     which includes the input shape mask of WINDOW in the masks to be
     merged.

    WINDOW
          a `<gdk-window>'


     Since 2.10


 -- Function: gdk-window-merge-child-input-shapes (self `<gdk-window>')
 -- Method: merge-child-input-shapes
     Merges the input shape masks for any child windows into the input
     shape mask for WINDOW. i.e. the union of all input masks for
     WINDOW and its children will become the new input mask for WINDOW.
     See `gdk-window-input-shape-combine-mask'.

     This function is distinct from `gdk-window-set-child-input-shapes'
     because it includes WINDOW's input shape mask in the set of shapes
     to be merged.

    WINDOW
          a `<gdk-window>'


     Since 2.10


 -- Function: gdk-window-set-static-gravities (self `<gdk-window>')
          (use_static `bool') =>  (ret `bool')
 -- Method: set-static-gravities
     Set the bit gravity of the given window to static, and flag it so
     all children get static subwindow gravity. This is used if you are
     implementing scary features that involve deep knowledge of the
     windowing system. Don't worry about it unless you have to.

    WINDOW
          a `<gdk-window>'

    USE-STATIC
          ``#t'' to turn on static gravity

    RET
          ``#t'' if the server supports static gravity



 -- Function: gdk-window-set-hints (self `<gdk-window>') (x `int')
          (y `int') (min_width `int') (min_height `int')
          (max_width `int') (max_height `int') (flags `int')
 -- Method: set-hints
     `gdk_window_set_hints' is deprecated and should not be used in
     newly-written code.

     This function is broken and useless and you should ignore it. If
     using GTK+, use functions such as `gtk-window-resize',
     `gtk-window-set-size-request', `gtk-window-move',
     `gtk-window-parse-geometry', and `gtk-window-set-geometry-hints',
     depending on what you're trying to do.

     If using GDK directly, use `gdk-window-set-geometry-hints'.

    WINDOW
          a `<gdk-window>'

    X
          ignored field, does not matter

    Y
          ignored field, does not matter

    MIN-WIDTH
          minimum width hint

    MIN-HEIGHT
          minimum height hint

    MAX-WIDTH
          max width hint

    MAX-HEIGHT
          max height hint

    FLAGS
          logical OR of GDK_HINT_POS, GDK_HINT_MIN_SIZE, and/or
          GDK_HINT_MAX_SIZE



 -- Function: gdk-window-set-title (self `<gdk-window>')
          (title `mchars')
 -- Method: set-title
     Sets the title of a toplevel window, to be displayed in the
     titlebar. If you haven't explicitly set the icon name for the
     window (using `gdk-window-set-icon-name'), the icon name will be
     set to TITLE as well. TITLE must be in UTF-8 encoding (as with all
     user-readable strings in GDK/GTK+). TITLE may not be ``#f''.

    WINDOW
          a toplevel `<gdk-window>'

    TITLE
          title of WINDOW



 -- Function: gdk-window-set-background (self `<gdk-window>')
          (color `<gdk-color>')
 -- Method: set-background
     Sets the background color of WINDOW. (However, when using GTK+,
     set the background of a widget with `gtk-widget-modify-bg' - if
     you're an application - or `gtk-style-set-background' - if you're
     implementing a custom widget.)

     The COLOR must be allocated; `gdk-rgb-find-color' is the best way
     to allocate a color.

     See also `gdk-window-set-back-pixmap'.

    WINDOW
          a `<gdk-window>'

    COLOR
          an allocated `<gdk-color>'



 -- Function: gdk-window-set-back-pixmap (self `<gdk-window>')
          (pixmap `<gdk-pixmap>') (parent_relative `bool')
 -- Method: set-back-pixmap
     Sets the background pixmap of WINDOW. May also be used to set a
     background of "None" on WINDOW, by setting a background pixmap of
     ``#f''. A background pixmap will be tiled, positioning the first
     tile at the origin of WINDOW, or if PARENT-RELATIVE is ``#t'', the
     tiling will be done based on the origin of the parent window
     (useful to align tiles in a parent with tiles in a child).

     A background pixmap of ``#f'' means that the window will have no
     background. A window with no background will never have its
     background filled by the windowing system, instead the window will
     contain whatever pixels were already in the corresponding area of
     the display.

     The windowing system will normally fill a window with its
     background when the window is obscured then exposed, and when you
     call `gdk-window-clear'.

    WINDOW
          a `<gdk-window>'

    PIXMAP
          a `<gdk-pixmap>', or ``#f''

    PARENT-RELATIVE
          whether the tiling origin is at the origin of WINDOW's parent



 -- Function: gdk-window-set-cursor (self `<gdk-window>')
          (cursor `<gdk-cursor>')
 -- Method: set-cursor
     Sets the mouse pointer for a `<gdk-window>'. Use `gdk-cursor-new'
     or `gdk-cursor-new-from-pixmap' to create the cursor. To make the
     cursor invisible, use `gdk-cursor-new-from-pixmap' to create a
     cursor with no pixels in it. Passing ``#f'' for the CURSOR
     argument to `gdk-window-set-cursor' means that WINDOW will use the
     cursor of its parent window. Most windows should use this default.

    WINDOW
          a `<gdk-window>'

    CURSOR
          a cursor



 -- Function: gdk-window-get-geometry (self `<gdk-window>') => 
          (x `int') (y `int') (width `int') (height `int') (depth `int')
 -- Method: get-geometry
     Any of the return location arguments to this function may be
     ``#f'', if you aren't interested in getting the value of that
     field.

     The X and Y coordinates returned are relative to the parent window
     of WINDOW, which for toplevels usually means relative to the window
     decorations (titlebar, etc.) rather than relative to the root
     window (screen-size background window).

     On the X11 platform, the geometry is obtained from the X server,
     so reflects the latest position of WINDOW; this may be out-of-sync
     with the position of WINDOW delivered in the
     most-recently-processed `<gdk-event-configure>'.
     `gdk-window-get-position' in contrast gets the position from the
     most recent configure event.

     If WINDOW is not a toplevel, it is _much_ better to call
     `gdk-window-get-position' and `gdk-drawable-get-size' instead,
     because it avoids the roundtrip to the X server and because
     `gdk-drawable-get-size' supports the full 32-bit coordinate space,
     whereas `gdk-window-get-geometry' is restricted to the 16-bit
     coordinates of X11.

    WINDOW
          a `<gdk-window>'

    X
          return location for X coordinate of window (relative to its
          parent)

    Y
          return location for Y coordinate of window (relative to its
          parent)

    WIDTH
          return location for width of window

    HEIGHT
          return location for height of window

    DEPTH
          return location for bit depth of window



 -- Function: gdk-window-set-icon-list (self `<gdk-window>')
          (pixbufs `glist-of')
 -- Method: set-icon-list
     Sets a list of icons for the window. One of these will be used to
     represent the window when it has been iconified. The icon is
     usually shown in an icon box or some sort of task bar. Which icon
     size is shown depends on the window manager.  The window manager
     can scale the icon but setting several size icons can give better
     image quality since the window manager may only need to scale the
     icon by a small amount or not at all.

    WINDOW
          The `<gdk-window>' toplevel window to set the icon of.

    PIXBUFS
          A list of pixbufs, of different sizes.



 -- Function: gdk-window-set-modal-hint (self `<gdk-window>')
          (modal `bool')
 -- Method: set-modal-hint
     The application can use this hint to tell the window manager that
     a certain window has modal behaviour. The window manager can use
     this information to handle modal windows in a special way.

     You should only use this on windows for which you have previously
     called `gdk-window-set-transient-for'

    WINDOW
          A toplevel `<gdk-window>'

    MODAL
          ``#t'' if the window is modal, ``#f'' otherwise.



 -- Function: gdk-window-set-type-hint (self `<gdk-window>')
          (hint `<gdk-window-type-hint>')
 -- Method: set-type-hint
     The application can use this call to provide a hint to the window
     manager about the functionality of a window. The window manager
     can use this information when determining the decoration and
     behaviour of the window.

     The hint must be set before the window is mapped.

    WINDOW
          A toplevel `<gdk-window>'

    HINT
          A hint of the function this window will have



 -- Function: gdk-window-get-type-hint (self `<gdk-window>') => 
          (ret `<gdk-window-type-hint>')
 -- Method: get-type-hint
     This function returns the type hint set for a window.

    WINDOW
          A toplevel `<gdk-window>'

    RET
          The type hint set for WINDOW


     Since 2.10


 -- Function: gdk-window-set-skip-taskbar-hint (self `<gdk-window>')
          (skips_taskbar `bool')
 -- Method: set-skip-taskbar-hint
     Toggles whether a window should appear in a task list or window
     list. If a window's semantic type as specified with
     `gdk-window-set-type-hint' already fully describes the window,
     this function should _not_ be called in addition, instead you
     should allow the window to be treated according to standard policy
     for its semantic type.

    WINDOW
          a toplevel `<gdk-window>'

    SKIPS-TASKBAR
          ``#t'' to skip the taskbar


     Since 2.2


 -- Function: gdk-window-set-skip-pager-hint (self `<gdk-window>')
          (skips_pager `bool')
 -- Method: set-skip-pager-hint
     Toggles whether a window should appear in a pager (workspace
     switcher, or other desktop utility program that displays a small
     thumbnail representation of the windows on the desktop). If a
     window's semantic type as specified with
     `gdk-window-set-type-hint' already fully describes the window, this
     function should _not_ be called in addition, instead you should
     allow the window to be treated according to standard policy for
     its semantic type.

    WINDOW
          a toplevel `<gdk-window>'

    SKIPS-PAGER
          ``#t'' to skip the pager


     Since 2.2


 -- Function: gdk-window-set-urgency-hint (self `<gdk-window>')
          (urgent `bool')
 -- Method: set-urgency-hint
     Toggles whether a window needs the user's urgent attention.

    WINDOW
          a toplevel `<gdk-window>'

    URGENT
          ``#t'' if the window is urgent


     Since 2.8


 -- Function: gdk-window-get-position (self `<gdk-window>') => 
          (x `int') (y `int')
 -- Method: get-position
     Obtains the position of the window as reported in the
     most-recently-processed `<gdk-event-configure>'. Contrast with
     `gdk-window-get-geometry' which queries the X server for the
     current window position, regardless of which events have been
     received or processed.

     The position coordinates are relative to the window's parent
     window.

    WINDOW
          a `<gdk-window>'

    X
          X coordinate of window

    Y
          Y coordinate of window



 -- Function: gdk-window-get-root-origin (self `<gdk-window>') => 
          (x `int') (y `int')
 -- Method: get-root-origin
     Obtains the top-left corner of the window manager frame in root
     window coordinates.

    WINDOW
          a toplevel `<gdk-window>'

    X
          return location for X position of window frame

    Y
          return location for Y position of window frame



 -- Function: gdk-window-get-origin (self `<gdk-window>') => 
          (ret `int') (x `int') (y `int')
 -- Method: get-origin
     Obtains the position of a window in root window coordinates.
     (Compare with `gdk-window-get-position' and
     `gdk-window-get-geometry' which return the position of a window
     relative to its parent window.)

    WINDOW
          a `<gdk-window>'

    X
          return location for X coordinate

    Y
          return location for Y coordinate

    RET
          not meaningful, ignore



 -- Function: gdk-window-get-deskrelative-origin (self `<gdk-window>')
          =>  (ret `bool') (x `int') (y `int')
 -- Method: get-deskrelative-origin
     `gdk_window_get_deskrelative_origin' is deprecated and should not
     be used in newly-written code.

     This gets the origin of a `<gdk-window>' relative to an
     Enlightenment-window-manager desktop. As long as you don't assume
     that the user's desktop/workspace covers the entire root window
     (i.e. you don't assume that the desktop begins at root window
     coordinate 0,0) this function is not necessary. It's deprecated
     for that reason.

    WINDOW
          a toplevel `<gdk-window>'

    X
          return location for X coordinate

    Y
          return location for Y coordinate

    RET
          not meaningful



 -- Function: gdk-window-get-parent (self `<gdk-window>') => 
          (ret `<gdk-window>')
 -- Method: get-parent
     Obtains the parent of WINDOW, as known to GDK. Does not query the X
     server; thus this returns the parent as passed to
     `gdk-window-new', not the actual parent. This should never matter
     unless you're using Xlib calls mixed with GDK calls on the X11
     platform. It may also matter for toplevel windows, because the
     window manager may choose to reparent them.

    WINDOW
          a `<gdk-window>'

    RET
          parent of WINDOW



 -- Function: gdk-window-get-toplevel (self `<gdk-window>') => 
          (ret `<gdk-window>')
 -- Method: get-toplevel
     Gets the toplevel window that's an ancestor of WINDOW.

    WINDOW
          a `<gdk-window>'

    RET
          the toplevel window containing WINDOW



 -- Function: gdk-window-get-children (self `<gdk-window>') => 
          (ret `glist-of')
 -- Method: get-children
     Gets the list of children of WINDOW known to GDK. This function
     only returns children created via GDK, so for example it's useless
     when used with the root window; it only returns windows an
     application created itself.

     The returned list must be freed, but the elements in the list need
     not be.

    WINDOW
          a `<gdk-window>'

    RET
          list of child windows inside WINDOW



 -- Function: gdk-window-get-events (self `<gdk-window>') => 
          (ret `<gdk-event-mask>')
 -- Method: get-events
     Gets the event mask for WINDOW. See `gdk-window-set-events'.

    WINDOW
          a `<gdk-window>'

    RET
          event mask for WINDOW



 -- Function: gdk-window-set-events (self `<gdk-window>')
          (event_mask `<gdk-event-mask>')
 -- Method: set-events
     The event mask for a window determines which events will be
     reported for that window. For example, an event mask including
     `<gdk-button-press-mask>' means the window should report button
     press events. The event mask is the bitwise OR of values from the
     `<gdk-event-mask>' enumeration.

    WINDOW
          a `<gdk-window>'

    EVENT-MASK
          event mask for WINDOW



 -- Function: gdk-window-set-icon (self `<gdk-window>')
          (icon_window `<gdk-window>') (pixmap `<gdk-pixmap>')
          (mask `<gdk-drawable>')
 -- Method: set-icon
     Sets the icon of WINDOW as a pixmap or window. If using GTK+,
     investigate `gtk-window-set-default-icon-list' first, and then
     `gtk-window-set-icon-list' and `gtk-window-set-icon'. If those
     don't meet your needs, look at `gdk-window-set-icon-list'. Only if
     all those are too high-level do you want to fall back to
     `gdk-window-set-icon'.

    WINDOW
          a toplevel `<gdk-window>'

    ICON-WINDOW
          a `<gdk-window>' to use for the icon, or ``#f'' to unset

    PIXMAP
          a `<gdk-pixmap>' to use as the icon, or ``#f'' to unset

    MASK
          a 1-bit pixmap (`<gdk-bitmap>') to use as mask for PIXMAP, or
          ``#f'' to have none



 -- Function: gdk-window-set-icon-name (self `<gdk-window>')
          (name `mchars')
 -- Method: set-icon-name
     Windows may have a name used while minimized, distinct from the
     name they display in their titlebar. Most of the time this is a
     bad idea from a user interface standpoint. But you can set such a
     name with this function, if you like.

    WINDOW
          a toplevel `<gdk-window>'

    NAME
          name of window while iconified (minimized)



 -- Function: gdk-window-set-transient-for (self `<gdk-window>')
          (parent `<gdk-window>')
 -- Method: set-transient-for
     Indicates to the window manager that WINDOW is a transient dialog
     associated with the application window PARENT. This allows the
     window manager to do things like center WINDOW on PARENT and keep
     WINDOW above PARENT.

     See `gtk-window-set-transient-for' if you're using `<gtk-window>'
     or `<gtk-dialog>'.

    WINDOW
          a toplevel `<gdk-window>'

    PARENT
          another toplevel `<gdk-window>'



 -- Function: gdk-window-set-role (self `<gdk-window>') (role `mchars')
 -- Method: set-role
     When using GTK+, typically you should use `gtk-window-set-role'
     instead of this low-level function.

     The window manager and session manager use a window's role to
     distinguish it from other kinds of window in the same application.
     When an application is restarted after being saved in a previous
     session, all windows with the same title and role are treated as
     interchangeable. So if you have two windows with the same title
     that should be distinguished for session management purposes, you
     should set the role on those windows. It doesn't matter what
     string you use for the role, as long as you have a different role
     for each non-interchangeable kind of window.

    WINDOW
          a toplevel `<gdk-window>'

    ROLE
          a string indicating its role



 -- Function: gdk-window-set-group (self `<gdk-window>')
          (leader `<gdk-window>')
 -- Method: set-group
     Sets the group leader window for WINDOW. By default, GDK sets the
     group leader for all toplevel windows to a global window
     implicitly created by GDK.  With this function you can override
     this default.

     The group leader window allows the window manager to distinguish
     all windows that belong to a single application. It may for
     example allow users to minimize/unminimize all windows belonging
     to an application at once. You should only set a non-default group
     window if your application pretends to be multiple applications.

    WINDOW
          a toplevel `<gdk-window>'

    LEADER
          group leader window, or ``#f'' to restore the default group
          leader window



 -- Function: gdk-window-get-group (self `<gdk-window>') => 
          (ret `<gdk-window>')
 -- Method: get-group
     Returns the group leader window for WINDOW. See
     `gdk-window-set-group'.

    WINDOW
          a toplevel `<gdk-window>'

    RET
          the group leader window for WINDOW


     Since 2.4


 -- Function: gdk-window-set-decorations (self `<gdk-window>')
          (decorations `<gdk-wm-decoration>')
 -- Method: set-decorations
     "Decorations" are the features the window manager adds to a
     toplevel `<gdk-window>'. This function sets the traditional Motif
     window manager hints that tell the window manager which
     decorations you would like your window to have. Usually you should
     use `gtk-window-set-decorated' on a `<gtk-window>' instead of
     using the GDK function directly.

     The DECORATIONS argument is the logical OR of the fields in the
     `<gdk-wm-decoration>' enumeration. If `<gdk-decor-all>' is
     included in the mask, the other bits indicate which decorations
     should be turned off. If `<gdk-decor-all>' is not included, then
     the other bits indicate which decorations should be turned on.

     Most window managers honor a decorations hint of 0 to disable all
     decorations, but very few honor all possible combinations of bits.

    WINDOW
          a toplevel `<gdk-window>'

    DECORATIONS
          decoration hint mask



 -- Function: gdk-window-set-functions (self `<gdk-window>')
          (functions `<gdk-wm-function>')
 -- Method: set-functions
     Sets hints about the window management functions to make available
     via buttons on the window frame.

     On the X backend, this function sets the traditional Motif window
     manager hint for this purpose. However, few window managers do
     anything reliable or interesting with this hint. Many ignore it
     entirely.

     The FUNCTIONS argument is the logical OR of values from the
     `<gdk-wm-function>' enumeration. If the bitmask includes
     `<gdk-func-all>', then the other bits indicate which functions to
     disable; if it doesn't include `<gdk-func-all>', it indicates
     which functions to enable.

    WINDOW
          a toplevel `<gdk-window>'

    FUNCTIONS
          bitmask of operations to allow on WINDOW



 -- Function: gdk-window-get-toplevels =>  (ret `glist-of')
     Obtains a list of all toplevel windows known to GDK on the default
     screen (see `gdk-screen-get-toplevel-windows'). A toplevel window
     is a child of the root window (see `gdk-get-default-root-window').

     The returned list should be freed with `g-list-free', but its
     elements need not be freed.

    RET
          list of toplevel windows, free with `g-list-free'



 -- Function: gdk-get-default-root-window =>  (ret `<gdk-window>')
     Obtains the root window (parent all other windows are inside) for
     the default display and screen.

    RET
          the default root window




File: guile-gnome-gdk.info,  Node: Events,  Next: Event Structures,  Prev: Windows,  Up: Top

18 Events
*********

Functions for handling events from the window system

18.1 Overview
=============

This section describes functions dealing with events from the window
system.

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

18.2 Usage
==========

 -- Function: gdk-events-pending =>  (ret `bool')
     Checks if any events are ready to be processed for any display.

    RET
          ``#t'' if any events are pending.



 -- Function: gdk-event-peek =>  (ret `<gdk-event>')
     If there is an event waiting in the event queue of some open
     display, returns a copy of it. See `gdk-display-peek-event'.

    RET
          a copy of the first `<gdk-event>' on some event queue, or
          ``#f'' if no events are in any queues. The returned
          `<gdk-event>' should be freed with `gdk-event-free'.



 -- Function: gdk-event-get =>  (ret `<gdk-event>')
     Checks all open displays for a `<gdk-event>' to process,to be
     processed on, fetching events from the windowing system if
     necessary. See `gdk-display-get-event'.

    RET
          the next `<gdk-event>' to be processed, or ``#f'' if no events
          are pending. The returned `<gdk-event>' should be freed with
          `gdk-event-free'.



 -- Function: gdk-event-get-graphics-expose (window `<gdk-window>') => 
          (ret `<gdk-event>')
     Waits for a GraphicsExpose or NoExpose event from the X server.
     This is used in the `<gtk-text>' and `<gtk-clist>' widgets in GTK+
     to make sure any GraphicsExpose events are handled before the
     widget is scrolled.

    WINDOW
          the `<gdk-window>' to wait for the events for.

    RET
          a `<gdk-event-expose>' if a GraphicsExpose was received, or
          ``#f'' if a NoExpose event was received.



 -- Function: gdk-event-put (self `<gdk-event>')
     Appends a copy of the given event onto the front of the event
     queue for event->any.window's display, or the default event queue
     if event->any.window is ``#f''. See `gdk-display-put-event'.

    EVENT
          a `<gdk-event>'.



 -- Function: gdk-event-copy (self `<gdk-event>') => 
          (ret `<gdk-event>')
     Copies a `<gdk-event>', copying or incrementing the reference
     count of the resources associated with it (e.g. `<gdk-window>''s
     and strings).

    EVENT
          a `<gdk-event>'

    RET
          a copy of EVENT. The returned `<gdk-event>' should be freed
          with `gdk-event-free'.



 -- Function: gdk-event-get-time (self `<gdk-event>') => 
          (ret `unsigned-int32')
     Returns the time stamp from EVENT, if there is one; otherwise
     returns `<gdk-current-time>'. If EVENT is ``#f'', returns
     `<gdk-current-time>'.

    EVENT
          a `<gdk-event>'

    RET
          time stamp field from EVENT



 -- Function: gdk-event-get-axis (self `<gdk-event>')
          (axis_use `<gdk-axis-use>') =>  (ret `bool') (value `double')
     Extract the axis value for a particular axis use from an event
     structure.

    EVENT
          a `<gdk-event>'

    AXIS-USE
          the axis use to look for

    VALUE
          location to store the value found

    RET
          ``#t'' if the specified axis was found, otherwise ``#f''



 -- Function: gdk-event-get-coords (self `<gdk-event>') => 
          (ret `bool') (x_win `double') (y_win `double')
     Extract the event window relative x/y coordinates from an event.

    EVENT
          a `<gdk-event>'

    X-WIN
          location to put event window x coordinate

    Y-WIN
          location to put event window y coordinate

    RET
          ``#t'' if the event delivered event window coordinates



 -- Function: gdk-event-get-root-coords (self `<gdk-event>') => 
          (ret `bool') (x_root `double') (y_root `double')
     Extract the root window relative x/y coordinates from an event.

    EVENT
          a `<gdk-event>'

    X-ROOT
          location to put root window x coordinate

    Y-ROOT
          location to put root window y coordinate

    RET
          ``#t'' if the event delivered root window coordinates



 -- Function: gdk-get-show-events =>  (ret `bool')
     Gets whether event debugging output is enabled.

    RET
          ``#t'' if event debugging output is enabled.



 -- Function: gdk-set-show-events (show_events `bool')
     Sets whether a trace of received events is output. Note that GTK+
     must be compiled with debugging (that is, configured using the
     "-enable-debug") option) to use this option.

    SHOW-EVENTS
          ``#t'' to output event debugging information.



 -- Function: gdk-event-get-screen (self `<gdk-event>') => 
          (ret `<gdk-screen>')
     Returns the screen for the event. The screen is typically the
     screen for `event->any.window', but for events such as mouse
     events, it is the screen where the pointer was when the event
     occurs - that is, the screen which has the root window to which
     `event->motion.x_root' and `event->motion.y_root' are relative.

    EVENT
          a `<gdk-event>'

    RET
          the screen for the event


     Since 2.2



File: guile-gnome-gdk.info,  Node: Event Structures,  Next: Key Values,  Prev: Events,  Up: Top

19 Event Structures
*******************

Data structures specific to each type of event

19.1 Overview
=============

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

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

19.2 Usage
==========

 -- Class: <gdk-event-any>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-key>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-button>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-scroll>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-motion>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-expose>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-visibility>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-crossing>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-focus>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-configure>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-property>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-selection>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-dnd>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-proximity>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-client>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-no-expose>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-window-state>
     Derives from `<gboxed>'.


 -- Class: <gdk-event-setting>
     Derives from `<gboxed>'.



File: guile-gnome-gdk.info,  Node: Key Values,  Next: Selections,  Prev: Event Structures,  Up: Top

20 Key Values
*************

Functions for manipulating keyboard codes

20.1 Overview
=============

Key values are the codes which are sent whenever a key is pressed or
released.  They appear in the field of the `<gdk-event-key>' structure,
which is passed to signal handlers for the "key-press-event" and
"key-release-event" signals. The complete list of key values can be
found in the `<gdk/gdkkeysyms.h>' header file. `<gdk/gdkkeysyms.h>' is
not included in `<gtk/gtk.h>', it must be included independently,
because the file is quite large.

   Key values can be converted into a string representation using
`gdk-keyval-name'. The reverse function, converting a string to a key
value, is provided by `gdk-keyval-from-name'.

   The case of key values can be determined using `gdk-keyval-is-upper'
and `gdk-keyval-is-lower'. Key values can be converted to upper or
lower case using `gdk-keyval-to-upper' and `gdk-keyval-to-lower'.

   When it makes sense, key values can be converted to and from Unicode
characters with `gdk-keyval-to-unicode' and `gdk-unicode-to-keyval'.

   One `<gdk-keymap>' object exists for each user display.
`gdk-keymap-get-default' returns the `<gdk-keymap>' for the default
display; to obtain keymaps for other displays, use
`gdk-keymap-get-for-display'. A keymap is a mapping from
`<gdk-keymap-key>' to key values. You can think of a `<gdk-keymap-key>'
as a representation of a symbol printed on a physical keyboard key.
That is, it contains three pieces of information. First, it contains
the hardware keycode; this is an identifying number for a physical key.
Second, it contains the "level" of the key. The level indicates which
symbol on the key will be used, in a vertical direction. So on a
standard US keyboard, the key with the number "1" on it also has the
exclamation point ("!") character on it. The level indicates whether to
use the "1" or the "!" symbol. The letter keys are considered to have a
lowercase letter at level 0, and an uppercase letter at level 1, though
only the uppercase letter is printed. Third, the `<gdk-keymap-key>'
contains a group; groups are not used on standard US keyboards, but are
used in many other countries. On a keyboard with groups, there can be 3
or 4 symbols printed on a single key. The group indicates movement in a
horizontal direction. Usually groups are used for two different
languages. In group 0, a key might have two English characters, and in
group 1 it might have two Hebrew characters. The Hebrew characters will
be printed on the key next to the English characters.

   In order to use a keymap to interpret a key event, it's necessary to
first convert the keyboard state into an effective group and level.
This is done via a set of rules that varies widely according to type of
keyboard and user configuration. The function
`gdk-keymap-translate-keyboard-state' accepts a keyboard state -
consisting of hardware keycode pressed, active modifiers, and active
group - applies the appropriate rules, and returns the group/level to be
used to index the keymap, along with the modifiers which did not affect
the group and level. i.e. it returns "unconsumed modifiers." The
keyboard group may differ from the effective group used for keymap
lookups because some keys don't have multiple groups - e.g. the Enter
key is always in group 0 regardless of keyboard state.

   Note that `gdk-keymap-translate-keyboard-state' also returns the
keyval, i.e. it goes ahead and performs the keymap lookup in addition
to telling you which effective group/level values were used for the
lookup.  `<gdk-event-key>' already contains this keyval, however, so
you don't normally need to call `gdk-keymap-translate-keyboard-state'
just to get the keyval.

20.2 Usage
==========

 -- Class: <gdk-keymap>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Signal on <gdk-keymap>: direction-changed
     The ::direction_changed signal gets emitted when the direction of
     the keymap changes.

     Since 2.0


 -- Signal on <gdk-keymap>: keys-changed
     The ::keys_changed signal is emitted when the mapping represented
     by KEYMAP changes.

     Since 2.2


 -- Function: gdk-keymap-get-default =>  (ret `<gdk-keymap>')
     Returns the `<gdk-keymap>' attached to the default display.

    RET
          the `<gdk-keymap>' attached to the default display.



 -- Function: gdk-keymap-get-for-display (display `<gdk-display>') => 
          (ret `<gdk-keymap>')
     Returns the `<gdk-keymap>' attached to DISPLAY.

    DISPLAY
          the `<gdk-display>'.

    RET
          the `<gdk-keymap>' attached to DISPLAY.


     Since 2.2


 -- Function: gdk-keymap-get-direction (self `<gdk-keymap>') => 
          (ret `<pango-direction>')
 -- Method: get-direction
     Returns the direction of the keymap.

    KEYMAP
          a `<gdk-keymap>' or ``#f'' to use the default keymap. Returns:
          `PANGO_DIRECTION_LTR' or `PANGO_DIRECTION_RTL'.

    RET
          the direction of the keymap.



 -- Function: gdk-keyval-name (keyval `unsigned-int') =>  (ret `mchars')
     Converts a key value into a symbolic name. The names are the same
     as those in the `<gdk/gdkkeysyms.h>' header file but without the
     leading "GDK_".

    KEYVAL
          a key value.

    RET
          a string containing the name of the key, or ``#f'' if KEYVAL
          is not a valid key. The string should not be modified.



 -- Function: gdk-keyval-from-name (keyval_name `mchars') => 
          (ret `unsigned-int')
     Converts a key name to a key value.

    KEYVAL-NAME
          a key name.

    RET
          the corresponding key value, or `GDK_VoidSymbol' if the key
          name is not a valid key.



 -- Function: gdk-keyval-convert-case (symbol `unsigned-int') => 
          (lower `unsigned-int') (upper `unsigned-int')
     Obtains the upper- and lower-case versions of the keyval SYMBOL.
     Examples of keyvals are `<gdk-a>', `<gdk--enter>', `<gdk-f1>', etc.

    SYMBOL
          a keyval

    LOWER
          return location for lowercase version of SYMBOL

    UPPER
          return location for uppercase version of SYMBOL



 -- Function: gdk-keyval-to-upper (keyval `unsigned-int') => 
          (ret `unsigned-int')
     Converts a key value to upper case, if applicable.

    KEYVAL
          a key value.

    RET
          the upper case form of KEYVAL, or KEYVAL itself if it is
          already in upper case or it is not subject to case conversion.



 -- Function: gdk-keyval-to-lower (keyval `unsigned-int') => 
          (ret `unsigned-int')
     Converts a key value to lower case, if applicable.

    KEYVAL
          a key value.

    RET
          the lower case form of KEYVAL, or KEYVAL itself if it is
          already in lower case or it is not subject to case conversion.



 -- Function: gdk-keyval-is-upper (keyval `unsigned-int') => 
          (ret `bool')
     Returns ``#t'' if the given key value is in upper case.

    KEYVAL
          a key value.

    RET
          ``#t'' if KEYVAL is in upper case, or if KEYVAL is not
          subject to case conversion.



 -- Function: gdk-keyval-is-lower (keyval `unsigned-int') => 
          (ret `bool')
     Returns ``#t'' if the given key value is in lower case.

    KEYVAL
          a key value.

    RET
          ``#t'' if KEYVAL is in lower case, or if KEYVAL is not
          subject to case conversion.



 -- Function: gdk-keyval-to-unicode (keyval `unsigned-int') => 
          (ret `unsigned-int32')
     Convert from a GDK key symbol to the corresponding ISO10646
     (Unicode) character.

    KEYVAL
          a GDK key symbol

    RET
          the corresponding unicode character, or 0 if there is no
          corresponding character.



 -- Function: gdk-unicode-to-keyval (wc `unsigned-int32') => 
          (ret `unsigned-int')
     Convert from a ISO10646 character to a key symbol.

    WC
          a ISO10646 encoded character

    RET
          the corresponding GDK key symbol, if one exists. or, if there
          is no corresponding symbol, wc | 0x01000000




File: guile-gnome-gdk.info,  Node: Selections,  Next: Drag and Drop,  Prev: Key Values,  Up: Top

21 Selections
*************

Functions for transfering data via the X selection mechanism

21.1 Overview
=============

The X selection mechanism provides a way to transfer arbitrary chunks
of data between programs. A "selection" is a essentially a named
clipboard, identified by a string interned as a `<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). See Properties
and Atoms for more information.

   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 in the
functions in `gtkselection.h' 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).

21.2 Usage
==========

 -- Function: gdk-selection-owner-set (owner `<gdk-window>')
          (selection `<gdk-atom>') (time_ `unsigned-int32')
          (send_event `bool') =>  (ret `bool')
     Sets the owner of the given selection.

    OWNER
          a `<gdk-window>' or ``#f'' to indicate that the the owner for
          the given should be unset.

    SELECTION
          an atom identifying a selection.

    TIME
          timestamp to use when setting the selection. If this is older
          than the timestamp given last time the owner was set for the
          given selection, the request will be ignored.

    SEND-EVENT
          if ``#t'', and the new owner is different from the current
          owner, the current owner will be sent a SelectionClear event.

    RET
          ``#t'' if the selection owner was successfully changed to
          OWNER, otherwise ``#f''.



 -- Function: gdk-selection-owner-set-for-display
          (display `<gdk-display>') (owner `<gdk-window>')
          (selection `<gdk-atom>') (time_ `unsigned-int32')
          (send_event `bool') =>  (ret `bool')
     Sets the `<gdk-window>'OWNER as the current owner of the selection
     SELECTION.

    DISPLAY
          the `<gdk-display>'.

    OWNER
          a `<gdk-window>' or ``#f'' to indicate that the owner for the
          given should be unset.

    SELECTION
          an atom identifying a selection.

    TIME
          timestamp to use when setting the selection. If this is older
          than the timestamp given last time the owner was set for the
          given selection, the request will be ignored.

    SEND-EVENT
          if ``#t'', and the new owner is different from the current
          owner, the current owner will be sent a SelectionClear event.

    RET
          ``#t'' if the selection owner was successfully changed to
          owner, otherwise ``#f''.


     Since 2.2


 -- Function: gdk-selection-owner-get (selection `<gdk-atom>') => 
          (ret `<gdk-window>')
     Determines the owner of the given selection.

    SELECTION
          an atom indentifying a selection.

    RET
          if there is a selection owner for this window, and it is a
          window known to the current process, the `<gdk-window>' that
          owns the selection, otherwise ``#f''. Note that the return
          value may be owned by a different process if a foreign window
          was previously created for that window, but a new foreign
          window will never be created by this call.



 -- Function: gdk-selection-owner-get-for-display
          (display `<gdk-display>') (selection `<gdk-atom>') => 
          (ret `<gdk-window>')
     Determine the owner of the given selection.

     Note that the return value may be owned by a different process if
     a foreign window was previously created for that window, but a new
     foreign window will never be created by this call.

    DISPLAY
          a `<gdk-display>'.

    SELECTION
          an atom indentifying a selection.

    RET
          if there is a selection owner for this window, and it is a
          window known to the current process, the `<gdk-window>' that
          owns the selection, otherwise ``#f''.


     Since 2.2


 -- Function: gdk-selection-convert (requestor `<gdk-window>')
          (selection `<gdk-atom>') (target `<gdk-atom>')
          (time_ `unsigned-int32')
     Retrieves the contents of a selection in a given form.

    REQUESTOR
          a `<gdk-window>'.

    SELECTION
          an atom identifying the selection to get the contents of.

    TARGET
          the form in which to retrieve the selection.

    TIME
          the timestamp to use when retrieving the selection. The
          selection owner may refuse the request if it did not own the
          selection at the time indicated by the timestamp.



 -- Function: gdk-selection-send-notify (requestor `unsigned-int32')
          (selection `<gdk-atom>') (target `<gdk-atom>')
          (property `<gdk-atom>') (time_ `unsigned-int32')
     Sends a response to SelectionRequest event.

    REQUESTOR
          window to which to deliver response.

    SELECTION
          selection that was requested.

    TARGET
          target that was selected.

    PROPERTY
          property in which the selection owner stored the data, or
          `GDK_NONE' to indicate that the request was rejected.

    TIME
          timestamp.




File: guile-gnome-gdk.info,  Node: Drag and Drop,  Next: Properties and Atoms,  Prev: Selections,  Up: Top

22 Drag and Drop
****************

Functions for controlling drag and drop handling

22.1 Overview
=============

These functions provide a low level interface for drag and drop. The X
backend of GDK supports both the Xdnd and Motif drag and drop protocols
transparently, the Win32 backend supports the WM_DROPFILES protocol.

   GTK+ provides a higher level abstraction based on top of these
functions, and so they are not normally needed in GTK+ applications.
See the Drag and Drop section of the GTK+ documentation for more
information.

22.2 Usage
==========

 -- Class: <gdk-drag-context>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-drag-get-selection (context `<gdk-drag-context>') => 
          (ret `<gdk-atom>')
     Returns the selection atom for the current source window.

    CONTEXT
          a `<gdk-drag-context>'.

    RET
          the selection atom.



 -- Function: gdk-drag-abort (context `<gdk-drag-context>')
          (time_ `unsigned-int32')
     Aborts a drag without dropping.

     This function is called by the drag source.

    CONTEXT
          a `<gdk-drag-context>'.

    TIME
          the timestamp for this operation.



 -- Function: gdk-drop-reply (context `<gdk-drag-context>') (ok `bool')
          (time_ `unsigned-int32')
     Accepts or rejects a drop.

     This function is called by the drag destination in response to a
     drop initiated by the drag source.

    CONTEXT
          a `<gdk-drag-context>'.

    OK
          ``#t'' if the drop is accepted.

    TIME
          the timestamp for this operation.



 -- Function: gdk-drag-context-new =>  (ret `<gdk-drag-context>')
     Creates a new `<gdk-drag-context>'.

    RET
          the newly created `<gdk-drag-context>'.



 -- Function: gdk-drag-drop (context `<gdk-drag-context>')
          (time_ `unsigned-int32')
     Drops on the current destination.

     This function is called by the drag source.

    CONTEXT
          a `<gdk-drag-context>'.

    TIME
          the timestamp for this operation.



 -- Function: gdk-drag-motion (context `<gdk-drag-context>')
          (dest_window `<gdk-window>') (protocol `<gdk-drag-protocol>')
          (x_root `int') (y_root `int')
          (suggested_action `<gdk-drag-action>')
          (possible_actions `<gdk-drag-action>')
          (time_ `unsigned-int32') =>  (ret `bool')
     Updates the drag context when the pointer moves or the set of
     actions changes.

     This function is called by the drag source.

    CONTEXT
          a `<gdk-drag-context>'.

    DEST-WINDOW
          the new destination window, obtained by
          `gdk-drag-find-window'.

    PROTOCOL
          the DND protocol in use, obtained by `gdk-drag-find-window'.

    X-ROOT
          the x position of the pointer in root coordinates.

    Y-ROOT
          the y position of the pointer in root coordinates.

    SUGGESTED-ACTION
          the suggested action.

    POSSIBLE-ACTIONS
          the possible actions.

    TIME
          the timestamp for this operation.

    RET
          FIXME



 -- Function: gdk-drop-finish (context `<gdk-drag-context>')
          (success `bool') (time_ `unsigned-int32')
     Ends the drag operation after a drop.

     This function is called by the drag destination.

    CONTEXT
          a `<gtk-drag-context>'.

    SUCCESS
          ``#t'' if the data was successfully received.

    TIME
          the timestamp for this operation.



 -- Function: gdk-drag-status (context `<gdk-drag-context>')
          (action `<gdk-drag-action>') (time_ `unsigned-int32')
     Selects one of the actions offered by the drag source.

     This function is called by the drag destination in response to
     `gdk-drag-motion' called by the drag source.

    CONTEXT
          a `<gdk-drag-context>'.

    ACTION
          the selected action which will be taken when a drop happens,
          or 0 to indicate that a drop will not be accepted.

    TIME
          the timestamp for this operation.



 -- Function: gdk-drag-drop-succeeded (context `<gdk-drag-context>')
          =>  (ret `bool')
     Returns wether the dropped data has been successfully transferred.
     This function is intended to be used while handling a
     `GDK_DROP_FINISHED' event, its return value is meaningless at
     other times.

    CONTEXT
          a `<gdk-drag-context>'

    RET
          ``#t'' if the drop was successful.


     Since 2.6



File: guile-gnome-gdk.info,  Node: Properties and Atoms,  Next: Threads,  Prev: Drag and Drop,  Up: Top

23 Properties and Atoms
***********************

Functions to manipulate properties on windows

23.1 Overview
=============

Each window under X can have any number of associated "properties"
attached to it. Properties are arbitrary chunks of data identified by
"atom"s. (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.) A property has an
associated type, which is also identified using an atom.

   A property has an associated "format", an integer describing how
many bits are in each unit of data inside the property. It must be 8,
16, or 32. When data is transferred between the server and client, if
they are of different endianesses it will be byteswapped as necessary
according to the format of the property. Note that on the client side,
properties of format 32 will be stored with one unit per _long_, even
if a long integer has more than 32 bits on the platform. (This decision
was apparently made for Xlib to maintain compatibility with programs
that assumed longs were 32 bits, at the expense of programs that knew
better.)

   The functions in this section are used to add, remove and change
properties on windows, to convert atoms to and from strings and to
manipulate some types of data commonly stored in X window properties.

23.2 Usage
==========

 -- Class: <gdk-atom>
     Opaque pointer.


 -- Function: gdk-atom-intern (atom_name `mchars')
          (only_if_exists `bool') =>  (ret `<gdk-atom>')
     Finds or creates an atom corresponding to a given string.

    ATOM-NAME
          a string.

    ONLY-IF-EXISTS
          if ``#t'', GDK is allowed to not create a new atom, but just
          return `GDK_NONE' if the requested atom doesn't already
          exists. Currently, the flag is ignored, since checking the
          existance of an atom is as expensive as creating it.

    RET
          the atom corresponding to ATOM-NAME.



 -- Function: gdk-atom-name (atom `<gdk-atom>') =>  (ret `mchars')
     Determines the string corresponding to an atom.

    ATOM
          a `<gdk-atom>'.

    RET
          a newly-allocated string containing the string corresponding
          to ATOM. When you are done with the return value, you should
          free it using `g-free'.



 -- Function: gdk-property-delete (window `<gdk-window>')
          (property `<gdk-atom>')
     Deletes a property from a window.

    WINDOW
          a `<gdk-window>'.

    PROPERTY
          the property to delete.




File: guile-gnome-gdk.info,  Node: Threads,  Next: Input,  Prev: Properties and Atoms,  Up: Top

24 Threads
**********

Functions for using GDK in multi-threaded programs

24.1 Overview
=============

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 `<g-hash-table>' from multiple threads.

   GTK+ is "thread aware" but not thread safe &#x2014; it provides a
global lock controlled by `gdk-threads-enter'/`gdk-threads-leave' which
protects all use of GTK+. That is, only one thread can use GTK+ at any
given time.

   Unfortunately the above holds with the X11 backend only. With the
Win32 backend, GDK calls should not be attempted from multiple threads
at all.

   You must call `g-thread-init' and `gdk-threads-init' before executing
any other GTK+ or GDK functions in a threaded GTK+ program.

   Idles, timeouts, and input functions are executed outside of the
main GTK+ lock.  So, if you need to call GTK+ inside of such a
callback, you must surround the callback with a
`gdk-threads-enter'/`gdk-threads-leave' pair.  (However, signals are
still executed within the main GTK+ lock.)

   In particular, this means, if you are writing widgets that might be
used in threaded programs, you _must_ surround timeouts and idle
functions in this matter.

   As always, you must also surround any calls to GTK+ not made within
a signal handler with a `gdk-threads-enter'/`gdk-threads-leave' pair.

   Before calling `gdk-threads-leave' from a thread other than your main
thread, you probably want to call `gdk-flush' to send all pending
commands to the windowing system. (The reason you don't need to do this
from the main thread is that GDK always automatically flushes pending
commands when it runs out of incoming events to process and has to
sleep while waiting for more events.)

   A minimal main program for a threaded GTK+ application looks like:


     int
     main (int argc, char *argv[])
     {
       GtkWidget *window;

       g_thread_init (NULL);
       gdk_threads_init ();
       gdk_threads_enter ();

       gtk_init (&argc, &argv);

       window = create_window ();
       gtk_widget_show (window);

       gtk_main ();
       gdk_threads_leave ();

       return 0;
     }

   Callbacks require a bit of attention. Callbacks from GTK+ signals
are made within the GTK+ lock. However callbacks from GLib (timeouts,
IO callbacks, and idle functions) are made outside of the GTK+ lock.
So, within a signal handler you do not need to call
`gdk-threads-enter', but within the other types of callbacks, you do.

   Erik Mouw contributed the following code example to illustrate how
to use threads within GTK+ programs.


     /*-------------------------------------------------------------------------
      * Filename:      gtk-thread.c
      * Version:       0.99.1
      * Copyright:     Copyright (C) 1999, Erik Mouw
      * Author:        Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
      * Description:   GTK threads example.
      * Created at:    Sun Oct 17 21:27:09 1999
      * Modified by:   Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
      * Modified at:   Sun Oct 24 17:21:41 1999
      *-----------------------------------------------------------------------*/
     /*
      * Compile with:
      *
      * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
      *
      * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
      * bugs.
      *
      */

     &#x0023;include <stdio.h>
     &#x0023;include <stdlib.h>
     &#x0023;include <unistd.h>
     &#x0023;include <time.h>
     &#x0023;include <gtk/gtk.h>
     &#x0023;include <glib.h>
     &#x0023;include <pthread.h>

     &#x0023;define YES_IT_IS    (1)
     &#x0023;define NO_IT_IS_NOT (0)

     typedef struct
     {
       GtkWidget *label;
       int what;
     } yes_or_no_args;

     G_LOCK_DEFINE_STATIC (yes_or_no);
     static volatile int yes_or_no = YES_IT_IS;

     void destroy (GtkWidget *widget, gpointer data)
     {
       gtk_main_quit ();
     }

     void *argument_thread (void *args)
     {
       yes_or_no_args *data = (yes_or_no_args *)args;
       gboolean say_something;

       for (;;)
         {
           /* sleep a while */
           sleep(rand() / (RAND_MAX / 3) + 1);

           /* lock the yes_or_no_variable */
           G_LOCK(yes_or_no);

           /* do we have to say something? */
           say_something = (yes_or_no != data->what);

           if(say_something)
     	{
     	  /* set the variable */
     	  yes_or_no = data->what;
     	}

           /* Unlock the yes_or_no variable */
           G_UNLOCK (yes_or_no);

           if (say_something)
     	{
     	  /* get GTK thread lock */
     	  gdk_threads_enter ();

     	  /* set label text */
     	  if(data->what == YES_IT_IS)
     	    gtk_label_set_text (GTK_LABEL (data->label), "O yes, it is!");
     	  else
     	    gtk_label_set_text (GTK_LABEL (data->label), "O no, it isn't!");

     	  /* release GTK thread lock */
     	  gdk_threads_leave ();
     	}
         }

       return NULL;
     }

     int main (int argc, char *argv[])
     {
       GtkWidget *window;
       GtkWidget *label;
       yes_or_no_args yes_args, no_args;
       pthread_t no_tid, yes_tid;

       /* init threads */
       g_thread_init (NULL);
       gdk_threads_init ();
       gdk_threads_enter ();

       /* init gtk */
       gtk_init(&argc, &argv);

       /* init random number generator */
       srand ((unsigned int) time (NULL));

       /* create a window */
       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

       gtk_signal_connect (GTK_OBJECT (window), "destroy",
     		      GTK_SIGNAL_FUNC (destroy), NULL);

       gtk_container_set_border_width (GTK_CONTAINER (window), 10);

       /* create a label */
       label = gtk_label_new ("And now for something completely different ...");
       gtk_container_add (GTK_CONTAINER (window), label);

       /* show everything */
       gtk_widget_show (label);
       gtk_widget_show (window);

       /* create the threads */
       yes_args.label = label;
       yes_args.what = YES_IT_IS;
       pthread_create (&yes_tid, NULL, argument_thread, &yes_args);

       no_args.label = label;
       no_args.what = NO_IT_IS_NOT;
       pthread_create (&no_tid, NULL, argument_thread, &no_args);

       /* enter the GTK main loop */
       gtk_main ();
       gdk_threads_leave ();

       return 0;
     }

24.2 Usage
==========

 -- Function: gdk-threads-init
     Initializes GDK so that it can be used from multiple threads in
     conjunction with `gdk-threads-enter' and `gdk-threads-leave'.
     `g-thread-init' must be called previous to this function.

     This call must be made before any use of the main loop from GTK+;
     to be safe, call it before `gtk-init'.


 -- Function: gdk-threads-enter
     This macro marks the beginning of a critical section in which GDK
     and GTK+ functions can be called. Only one thread at a time can be
     in such a critial section.


 -- Function: gdk-threads-leave
     Leaves a critical region begun with `gdk-threads-enter'.



File: guile-gnome-gdk.info,  Node: Input,  Next: Input Devices,  Prev: Threads,  Up: Top

25 Input
********

Callbacks on file descriptors

25.1 Overview
=============

The functions in this section are used to establish callbacks when some
condition becomes true for a file descriptor. They are currently just
wrappers around the IO Channel facility.

25.2 Usage
==========


File: guile-gnome-gdk.info,  Node: Input Devices,  Next: Pango Interaction,  Prev: Input,  Up: Top

26 Input Devices
****************

Functions for handling extended input devices

26.1 Overview
=============

In addition to the normal keyboard and mouse input devices, GTK+ also
contains support for "extended input devices". In particular, this
support is targeted at graphics tablets. Graphics tablets typically
return sub-pixel positioning information and possibly information about
the pressure and tilt of the stylus. Under X, the support for extended
devices is done through the "XInput" extension.

   Because handling extended input devices may involve considerable
overhead, they need to be turned on for each `<gdk-window>'
individually using `gdk-input-set-extension-events'. (Or, more
typically, for GtkWidgets, using `gtk-widget-set-extension-events'). As
an additional complication, depending on the support from the windowing
system, its possible that a normal mouse cursor will not be displayed
for a particular extension device. If an application does not want to
deal with displaying a cursor itself, it can ask only to get extension
events from devices that will display a cursor, by passing the
`GDK_EXTENSION_EVENTS_CURSOR' value to
`gdk-input-set-extension-events'. Otherwise, the application must
retrieve the device information using `gdk-devices-list', check the
field, and, if it is ``#f'', draw a cursor itself when it receives
motion events.

   Each pointing device is assigned a unique integer ID; events from a
particular device can be identified by the field in the event
structure. The events generated by pointer devices have also been
extended to contain , and fields which contain the extended information
reported as additional "valuators" from the device. The field is a a
double value ranging from 0.0 to 1.0, while the tilt fields are double
values ranging from -1.0 to 1.0. (With -1.0 representing the maximum
tilt to the left or up, and 1.0 representing the maximum tilt to the
right or down.)

   One additional field in each event is the field, which contains an
enumeration value describing the type of device; this currently can be
one of `GDK_SOURCE_MOUSE', `GDK_SOURCE_PEN', `GDK_SOURCE_ERASER', or
`GDK_SOURCE_CURSOR'. This field is present to allow simple applications
to (for instance) delete when they detect eraser devices without having
to keep track of complicated per-device settings.

   Various aspects of each device may be configured. The easiest way of
creating a GUI to allow the user to configure such a device is to use
the `<gtk-input-dialog>' widget in GTK+. However, even when using this
widget, application writers will need to directly query and set the
configuration parameters in order to save the state between invocations
of the application.  The configuration of devices is queried using
`gdk-devices-list'. Each device must be activated using
`gdk-device-set-mode', which also controls whether the device's range
is mapped to the entire screen or to a single window.  The mapping of
the valuators of the device onto the predefined valuator types is set
using `gdk-device-set-axis-use'. And the source type for each device
can be set with `gdk-device-set-source'.

   Devices may also have associated "keys" or macro buttons. Such keys
can be globally set to map into normal X keyboard events. The mapping
is set using `gdk-device-set-key'.

   The interfaces in this section will most likely be considerably
modified in the future to accomodate devices that may have different
sets of additional valuators than the pressure and .

26.2 Usage
==========

 -- Class: <gdk-device>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-devices-list =>  (ret `glist-of')
     Returns the list of available input devices for the default
     display. The list is statically allocated and should not be freed.

    RET
          a list of `<gdk-device>'



 -- Function: gdk-device-set-source (self `<gdk-device>')
          (source `<gdk-input-source>')
 -- Method: set-source
     Sets the source type for an input device.

    DEVICE
          a `<gdk-device>'.

    SOURCE
          the source type.



 -- Function: gdk-device-set-mode (self `<gdk-device>')
          (mode `<gdk-input-mode>') =>  (ret `bool')
 -- Method: set-mode
     Sets a the mode of an input device. The mode controls if the
     device is active and whether the device's range is mapped to the
     entire screen or to a single window.

    DEVICE
          a `<gdk-device>'.

    MODE
          the input mode.

    RET
          ``#t'' if the mode was successfully changed.



 -- Function: gdk-device-set-key (self `<gdk-device>')
          (index_ `unsigned-int') (keyval `unsigned-int')
          (modifiers `<gdk-modifier-type>')
 -- Method: set-key
     Specifies the X key event to generate when a macro button of a
     device is pressed.

    DEVICE
          a `<gdk-device>'.

    INDEX
          the index of the macro button to set.

    KEYVAL
          the keyval to generate.

    MODIFIERS
          the modifiers to set.



 -- Function: gdk-device-set-axis-use (self `<gdk-device>')
          (index_ `unsigned-int') (use `<gdk-axis-use>')
 -- Method: set-axis-use
     Specifies how an axis of a device is used.

    DEVICE
          a `<gdk-device>'.

    INDEX
          the index of the axis.

    USE
          specifies how the axis is used.



 -- Function: gdk-device-get-core-pointer =>  (ret `<gdk-device>')
     Returns the core pointer device for the default display.

    RET
          the core pointer device; this is owned by the display and
          should not be freed.



 -- Function: gdk-device-get-axis (self `<gdk-device>')
          (use `<gdk-axis-use>') =>  (ret `bool') (axes `double')
          (value `double')
 -- Method: get-axis
     Interprets an array of double as axis values for a given device,
     and locates the value in the array for a given axis use.

    DEVICE
          a `<gdk-device>'

    AXES
          pointer to an array of axes

    USE
          the use to look for

    VALUE
          location to store the found value.

    RET
          ``#t'' if the given axis use was found, otherwise ``#f''



 -- Function: gdk-input-set-extension-events (window `<gdk-window>')
          (mask `int') (mode `<gdk-extension-mode>')
     Turns extension events on or off for a particular window, and
     specifies the event mask for extension events.

    WINDOW
          a `<gdk-window>'.

    MASK
          the event mask

    MODE
          the type of extension events that are desired.




File: guile-gnome-gdk.info,  Node: Pango Interaction,  Next: Cairo Interaction,  Prev: Input Devices,  Up: Top

27 Pango Interaction
********************

Using Pango in GDK

27.1 Overview
=============

Pango is the text layout system used by GDK and GTK+. The functions and
types in this section are used to render Pango objects to GDK.
drawables, and also extend the set of Pango attributes to include
stippling and embossing.

   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'll usually want to use `gtk-widget-get-pango-context', or
`gtk-widget-create-pango-layout', rather than using the lowlevel
`gdk-pango-context-get-for-screen'. Once you have a `<pango-layout>',
you can set the text and attributes of it with Pango functions like
`pango-layout-set-text' and get its size with `pango-layout-get-size'.
(Note that Pango uses a fixed point system internally, so converting
between Pango units and pixels using PANGO_SCALE or the `pango-pixels'
macro.)

   Rendering a Pango layout is done most simply with `gdk-draw-layout';
you can also draw pieces of the layout with `gdk-draw-layout' or
`gdk-draw-glyphs'. `<gdk-pango-renderer>' is a subclass of
`<pango-renderer>' that is used internally to implement these functions.
Using it directly or subclassing it can be useful in some cases. See the
`<gdk-pango-renderer>' documentation for details.


     #define RADIUS 100
     #define N_WORDS 10
     #define FONT "Sans Bold 18"

     GdkScreen *screen = gdk_drawable_get_screen (drawable);
     PangoRenderer *renderer;
     GdkGC *gc;

     PangoMatrix matrix = PANGO_MATRIX_INIT;
     PangoContext *context;
     PangoLayout *layout;
     PangoFontDescription *desc;

     double device_radius;
     int width, height;
     int i;

     /* Get the default renderer for the screen, and set it up for drawing  */
     renderer = gdk_pango_renderer_get_default (screen);
     gdk_pango_renderer_set_drawable (GDK_PANGO_RENDERER (renderer), drawable);

     gc = gdk_gc_new (drawable);
     gdk_pango_renderer_set_gc (GDK_PANGO_RENDERER (renderer), gc);

     /* 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 */
     gdk_drawable_get_size (drawable, &width, &height);
     device_radius = MIN (width, height) / 2.;

     pango_matrix_translate (&matrix,
                             device_radius + (width - 2 * device_radius) / 2,
                             device_radius + (height - 2 * device_radius) / 2);
     pango_matrix_scale (&matrix, device_radius / RADIUS, device_radius / RADIUS);

     /* Create a PangoLayout, set the font and text */
     context = gdk_pango_context_get_for_screen (screen);
     layout = pango_layout_new (context);
     pango_layout_set_text (layout, "Text", -1);
     desc = pango_font_description_from_string (FONT);
     pango_layout_set_font_description (layout, desc);
     pango_font_description_free (desc);

     /* Draw the layout N_WORDS times in a circle */
     for (i = 0; i < N_WORDS; i++)
       {
         GdkColor color;
         PangoMatrix rotated_matrix = matrix;
         int width, height;
         double angle = (360. * i) / N_WORDS;

         /* Gradient from red at angle == 60 to blue at angle == 300 */
         color.red   = 65535 * (1 + cos ((angle - 60) * M_PI / 180.)) / 2;
         color.green = 0;
         color.blue  = 65535  - color.red;

         gdk_pango_renderer_set_override_color (GDK_PANGO_RENDERER (renderer),
                                                PANGO_RENDER_PART_FOREGROUND, &color);

         pango_matrix_rotate (&rotated_matrix, angle);

         pango_context_set_matrix (context, &rotated_matrix);

         /* Inform Pango to re-layout the text with the new transformation matrix */
         pango_layout_context_changed (layout);

         pango_layout_get_size (layout, &width, &height);
         pango_renderer_draw_layout (renderer, layout,
                                     - width / 2, - RADIUS * PANGO_SCALE);
       }

     /* Clean up default renderer, since it is shared */
     gdk_pango_renderer_set_override_color (GDK_PANGO_RENDERER (renderer),
                                            PANGO_RENDER_PART_FOREGROUND, NULL);
     gdk_pango_renderer_set_drawable (GDK_PANGO_RENDERER (renderer), NULL);
     gdk_pango_renderer_set_gc (GDK_PANGO_RENDERER (renderer), NULL);

     /* free the objects we created */
     g_object_unref (layout);
     g_object_unref (context);
     g_object_unref (gc);

27.2 Usage
==========

 -- Class: <gdk-pango-renderer>
     Derives from `<pango-renderer>'.

     This class defines the following properties:

    `screen'
          the GdkScreen for the renderer



 -- Function: gdk-pango-renderer-new (screen `<gdk-screen>') => 
          (ret `<pango-renderer>')
     Creates a new `<pango-renderer>' for SCREEN. Normally you can use
     the results of `gdk-pango-renderer-get-default' rather than
     creating a new renderer.

    SCREEN
          a `<gdk-screen>'

    RET
          a newly created `<pango-renderer>'. Free with
          `g-object-unref'.


     Since 2.6


 -- Function: gdk-pango-renderer-get-default (screen `<gdk-screen>')
          =>  (ret `<pango-renderer>')
     Gets the default `<pango-renderer>' for a screen. This default
     renderer is shared by all users of the display, so properties such
     as the color or transformation matrix set for the renderer may be
     overwritten by functions such as `gdk-draw-layout'.

     Before using the renderer, you need to call
     `gdk-pango-renderer-set-drawable' and `gdk-pango-renderer-set-gc'
     to set the drawable and graphics context to use for drawing.

    SCREEN
          a `<gdk-screen>'

    RET
          the default `<pango-renderer>' for SCREEN. The renderer is
          owned by GTK+ and will be kept around until the screen is
          closed.


     Since 2.6


 -- Function: gdk-pango-renderer-set-drawable
          (self `<gdk-pango-renderer>') (drawable `<gdk-drawable>')
 -- Method: set-drawable
     Sets the drawable the renderer draws to.

    GDK-RENDERER
          a `<gdk-pango-renderer>'

    DRAWABLE
          the new target drawable, or ``#f''


     Since 2.6


 -- Function: gdk-pango-renderer-set-gc (self `<gdk-pango-renderer>')
          (gc `<gdk-gc>')
 -- Method: set-gc
     Sets the GC the renderer draws with. Note that the GC must not be
     modified until it is unset by calling the function again with
     ``#f'' for the GC parameter, since GDK may make internal copies of
     the GC which won't be updated to follow changes to the original GC.

    GDK-RENDERER
          a `<gdk-pango-renderer>'

    GC
          the new GC to use for drawing, or ``#f''


     Since 2.6


 -- Function: gdk-pango-renderer-set-stipple
          (self `<gdk-pango-renderer>') (part `<pango-render-part>')
          (stipple `<gdk-drawable>')
 -- Method: set-stipple
     Sets the stipple for one render part (foreground, background,
     underline, etc.)  Note that this is overwritten when iterating
     through the individual styled runs of a `<pango-layout>' or
     `<pango-layout-line>'. This function is thus only useful when you
     call low level functions like `pango-renderer-draw-glyphs'
     directly, or in the 'prepare_run' virtual function of a subclass
     of `<gdk-pango-renderer>'.

    GDK-RENDERER
          a `<gdk-pango-renderer>'

    PART
          the part to render with the stipple

    STIPPLE
          the new stipple value.


     Since 2.6


 -- Function: gdk-pango-context-get =>  (ret `<pango-context>')
     Creates a `<pango-context>' for the default GDK screen.

     The context must be freed when you're finished with it.

     When using GTK+, normally you should use
     `gtk-widget-get-pango-context' instead of this function, to get
     the appropriate context for the widget you intend to render text
     onto.

     The newly created context will have the default font options (see
     `<cairo-font-options-t>') for the default screen; if these options
     change it will not be updated. Using
     `gtk-widget-get-pango-context' is more convenient if you want to
     keep a context around and track changes to the screen's font
     rendering settings.

    RET
          a new `<pango-context>' for the default display



 -- Function: gdk-pango-context-get-for-screen (screen `<gdk-screen>')
          =>  (ret `<pango-context>')
     Creates a `<pango-context>' for SCREEN.

     The context must be freed when you're finished with it.

     When using GTK+, normally you should use
     `gtk-widget-get-pango-context' instead of this function, to get
     the appropriate context for the widget you intend to render text
     onto.

     The newly created context will have the default font options (see
     `<cairo-font-options-t>') for the screen; if these options change
     it will not be updated. Using `gtk-widget-get-pango-context' is
     more convenient if you want to keep a context around and track
     changes to the screen's font rendering settings.

    SCREEN
          the `<gdk-screen>' for which the context is to be created.

    RET
          a new `<pango-context>' for SCREEN


     Since 2.2


 -- Function: gdk-pango-context-set-colormap
          (context `<pango-context>') (colormap `<gdk-colormap>')
     `gdk_pango_context_set_colormap' is deprecated and should not be
     used in newly-written code.

     This function used to set the colormap to be used for drawing with
     CONTEXT. The colormap is now always derived from the graphics
     context used for drawing, so calling this function is no longer
     necessary.

    CONTEXT
          a `<pango-context>'

    COLORMAP
          a `<gdk-colormap>'



 -- Function: gdk-pango-attr-embossed-new (embossed `bool') => 
          (ret `<pango-attribute>')
     Creates a new attribute containing a embossed bitmap to be used
     when rendering the text.

    EMBOSSED
          a bitmap to be set as embossed

    RET
          new `<pango-attribute>'



 -- Function: gdk-pango-attr-stipple-new (stipple `<gdk-drawable>') => 
          (ret `<pango-attribute>')
     Creates a new attribute containing a stipple bitmap to be used
     when rendering the text.

    STIPPLE
          a bitmap to be set as stipple

    RET
          new `<pango-attribute>'




File: guile-gnome-gdk.info,  Node: Cairo Interaction,  Next: X Window System Interaction,  Prev: Pango Interaction,  Up: Top

28 Cairo Interaction
********************

Functions to support using Cairo

28.1 Overview
=============

Cairo is a graphics library that supports vector graphics and image
compositing that can be used with GDK. Since 2.8, GTK+ does most 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 drawables. Additional
functions allow to convert GDK's rectangles and regions into Cairo
paths and to use pixbufs as sources for drawing operations.

28.2 Usage
==========

 -- Function: gdk-cairo-create (drawable `<gdk-drawable>') => 
          (ret `cairo-t')
     Creates a Cairo context for drawing to DRAWABLE.

    DRAWABLE
          a `<gdk-drawable>'

    RET
          A newly created Cairo context. Free with `cairo-destroy' when
          you are done drawing.


     Since 2.8


 -- Function: gdk-cairo-set-source-color (cr `cairo-t')
          (color `<gdk-color>')
     Sets the specified `<gdk-color>' as the source color of CR.

    CR
          a `<cairo-t>'

    COLOR
          a `<gdk-color>'


     Since 2.8


 -- Function: gdk-cairo-set-source-pixbuf (cr `cairo-t')
          (pixbuf `<gdk-pixbuf>') (pixbuf_x `double')
          (pixbuf_y `double')
     Sets the given pixbuf as the source pattern for the Cairo context.
     The pattern has an extend mode of `CAIRO_EXTEND_NONE' and is
     aligned so that the origin of PIXBUF is PIXBUF-X, PIXBUF-Y

    CR
          a `<cairo>' context

    PIXBUF
          a `<gdk-pixbuf>'

    PIXBUF-X
          X coordinate of location to place upper left corner of PIXBUF

    PIXBUF-Y
          Y coordinate of location to place upper left corner of PIXBUF


     Since 2.8


 -- Function: gdk-cairo-set-source-pixmap (cr `cairo-t')
          (pixmap `<gdk-pixmap>') (pixmap_x `double')
          (pixmap_y `double')
     Sets the given pixmap as the source pattern for the Cairo context.
     The pattern has an extend mode of `CAIRO_EXTEND_NONE' and is
     aligned so that the origin of PIXBUF is PIXBUF-X, PIXBUF-Y

    CR
          a `<cairo>' context

    PIXMAP
          a `<gdk-pixmap>'

    PIXMAP-X
          X coordinate of location to place upper left corner of PIXMAP

    PIXMAP-Y
          Y coordinate of location to place upper left corner of PIXMAP


     Since 2.10


 -- Function: gdk-cairo-rectangle (cr `cairo-t')
          (rectangle `<gdk-rectangle>')
     Adds the given rectangle to the current path of CR.

    CR
          a `<cairo-t>'

    RECTANGLE
          a `<gdk-rectangle>'


     Since 2.8


 -- Function: gdk-cairo-region (cr `cairo-t') (region `<gdk-region>')
     Adds the given region to the current path of CR.

    CR
          a `<cairo-t>'

    REGION
          a `<gdk-region>'


     Since 2.8



File: guile-gnome-gdk.info,  Node: X Window System Interaction,  Next: Initialization and Versions,  Prev: Cairo Interaction,  Up: Top

29 X Window System Interaction
******************************

X backend-specific functions

29.1 Overview
=============

29.2 Usage
==========

 -- Function: gdk-pixmap-foreign-new-for-display
          (display `<gdk-display>') (anid `unsigned-long') => 
          (ret `<gdk-pixmap>')
     Wraps a native pixmap in a `<gdk-pixmap>'. This may fail if the
     pixmap has been destroyed.

     For example in the X backend, a native pixmap handle is an Xlib
     `<xid>'.

    DISPLAY
          The `<gdk-display>' where ANID is located.

    ANID
          a native pixmap handle.

    RET
          the newly-created `<gdk-pixmap>' wrapper for the native
          pixmap or ``#f'' if the pixmap has been destroyed.


     Since 2.2


 -- Function: gdk-pixmap-foreign-new-for-screen (screen `<gdk-screen>')
          (anid `unsigned-long') (width `int') (height `int')
          (depth `int') =>  (ret `<gdk-pixmap>')
     Wraps a native pixmap in a `<gdk-pixmap>'. This may fail if the
     pixmap has been destroyed.

     For example in the X backend, a native pixmap handle is an Xlib
     `<xid>'.

     This function is an alternative to
     `gdk-pixmap-foreign-new-for-display' for cases where the
     dimensions of the pixmap are known. For the X backend, this avoids
     a roundtrip to the server.

    SCREEN
          a `<gdk-screen>'

    ANID
          a native pixmap handle

    WIDTH
          the width of the pixmap identified by ANID

    HEIGHT
          the height of the pixmap identified by ANID

    DEPTH
          the depth of the pixmap identified by ANID

    RET
          the newly-created `<gdk-pixmap>' wrapper for the native
          pixmap or ``#f'' if the pixmap has been destroyed.


     Since 2.10


 -- Function: gdk-window-foreign-new-for-display
          (display `<gdk-display>') (anid `unsigned-long') => 
          (ret `<gdk-window>')
     Wraps a native window in a `<gdk-window>'. This may fail if the
     window has been destroyed. If the window was already known to GDK,
     a new reference to the existing `<gdk-window>' is returned.

     For example in the X backend, a native window handle is an Xlib
     `<xid>'.

    DISPLAY
          the `<gdk-display>' where the window handle comes from.

    ANID
          a native window handle.

    RET
          a `<gdk-window>' wrapper for the native window or ``#f'' if
          the window has been destroyed. The wrapper will be newly
          created, if one doesn't exist already.


     Since 2.2


 -- Function: gdk-window-lookup (anid `unsigned-long') => 
          (ret `<gdk-window>')
     Looks up the `<gdk-window>' that wraps the given native window
     handle.

     For example in the X backend, a native window handle is an Xlib
     `<xid>'.

    ANID
          a native window handle.

    RET
          the `<gdk-window>' wrapper for the native window, or ``#f'' if
          there is none.



 -- Function: gdk-pixmap-lookup (anid `unsigned-long') => 
          (ret `<gdk-pixmap>')
     Looks up the `<gdk-pixmap>' that wraps the given native pixmap
     handle.

     For example in the X backend, a native pixmap handle is an Xlib
     `<xid>'.

    ANID
          a native pixmap handle.

    RET
          the `<gdk-window>' wrapper for the native window, or ``#f'' if
          there is none.




File: guile-gnome-gdk.info,  Node: Initialization and Versions,  Next: The GdkPixbuf Structure,  Prev: X Window System Interaction,  Up: Top

30 Initialization and Versions
******************************

Library version numbers.

30.1 Overview
=============

These macros and variables let you check the version of gdk-pixbuf
you're linking against.

30.2 Usage
==========


File: guile-gnome-gdk.info,  Node: The GdkPixbuf Structure,  Next: Reference Counting and Memory Mangement,  Prev: Initialization and Versions,  Up: Top

31 The GdkPixbuf Structure
**************************

Information that describes an image.

31.1 Overview
=============

The structure contains information that describes an image in memory.

   Image data in a pixbuf is stored in memory in uncompressed, packed
format. Rows in the image are stored top to bottom, and in each row
pixels are stored from left to right. There may be padding at the end
of a row. The "rowstride" value of a pixbuf, as returned by
`gdk-pixbuf-get-rowstride', indicates the number of bytes between rows.

   The following code illustrates a simple put_pixel() function for RGB
pixbufs with 8 bits per channel with an alpha channel. It is not
included in the gdk-pixbuf library for performance reasons; rather than
making several function calls for each pixel, your own code can take
shortcuts.


     static void
     put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
     {
       int width, height, rowstride, n_channels;
       guchar *pixels, *p;

       n_channels = gdk_pixbuf_get_n_channels (pixbuf);

       g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
       g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
       g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
       g_assert (n_channels == 4);

       width = gdk_pixbuf_get_width (pixbuf);
       height = gdk_pixbuf_get_height (pixbuf);

       g_assert (x >= 0 && x < width);
       g_assert (y >= 0 && y < height);

       rowstride = gdk_pixbuf_get_rowstride (pixbuf);
       pixels = gdk_pixbuf_get_pixels (pixbuf);

       p = pixels + y * rowstride + x * n_channels;
       p[0] = red;
       p[1] = green;
       p[2] = blue;
       p[3] = alpha;
     }

   This function will not work for pixbufs with images that are other
than 8 bits per sample or channel, but it will work for most of the
pixbufs that GTK+ uses.

   If you are doing `memcpy' of raw pixbuf data, note that the last row
in the pixbuf may not be as wide as the full rowstride, but rather just
as wide as the pixel data needs to be. That is, it is unsafe to do
`memcpy (dest, pixels, rowstride * height)' to copy a whole pixbuf. Use
`gdk-pixbuf-copy' instead, or compute the width in bytes of the last
row as `width * ((n_channels * bits_per_sample + 7) / 8)'.

31.2 Usage
==========

 -- Class: <gdk-pixbuf>
     Derives from `<gobject>'.

     This class defines the following properties:

    `colorspace'
          The colorspace in which the samples are interpreted

    `n-channels'
          The number of samples per pixel

    `has-alpha'
          Whether the pixbuf has an alpha channel

    `bits-per-sample'
          The number of bits per sample

    `width'
          The number of columns of the pixbuf

    `height'
          The number of rows of the pixbuf

    `rowstride'
          The number of bytes between the start of a row and the start
          of the next row

    `pixels'
          A pointer to the pixel data of the pixbuf



 -- Function: gdk-pixbuf-get-colorspace (self `<gdk-pixbuf>') => 
          (ret `<gdk-colorspace>')
 -- Method: get-colorspace
     Queries the color space of a pixbuf.

    PIXBUF
          A pixbuf.

    RET
          Color space.



 -- Function: gdk-pixbuf-get-n-channels (self `<gdk-pixbuf>') => 
          (ret `int')
 -- Method: get-n-channels
     Queries the number of channels of a pixbuf.

    PIXBUF
          A pixbuf.

    RET
          Number of channels.



 -- Function: gdk-pixbuf-get-has-alpha (self `<gdk-pixbuf>') => 
          (ret `bool')
 -- Method: get-has-alpha
     Queries whether a pixbuf has an alpha channel (opacity
     information).

    PIXBUF
          A pixbuf.

    RET
          ``#t'' if it has an alpha channel, ``#f'' otherwise.



 -- Function: gdk-pixbuf-get-bits-per-sample (self `<gdk-pixbuf>') => 
          (ret `int')
 -- Method: get-bits-per-sample
     Queries the number of bits per color sample in a pixbuf.

    PIXBUF
          A pixbuf.

    RET
          Number of bits per color sample.



 -- Function: gdk-pixbuf-get-width (self `<gdk-pixbuf>') =>  (ret `int')
 -- Method: get-width
     Queries the width of a pixbuf.

    PIXBUF
          A pixbuf.

    RET
          Width in pixels.



 -- Function: gdk-pixbuf-get-height (self `<gdk-pixbuf>') => 
          (ret `int')
 -- Method: get-height
     Queries the height of a pixbuf.

    PIXBUF
          A pixbuf.

    RET
          Height in pixels.



 -- Function: gdk-pixbuf-get-rowstride (self `<gdk-pixbuf>') => 
          (ret `int')
 -- Method: get-rowstride
     Queries the rowstride of a pixbuf, which is the number of bytes
     between the start of a row and the start of the next row.

    PIXBUF
          A pixbuf.

    RET
          Distance between row starts.



 -- Function: gdk-pixbuf-get-option (self `<gdk-pixbuf>')
          (key `mchars') =>  (ret `mchars')
 -- Method: get-option
     Looks up KEY in the list of options that may have been attached to
     the PIXBUF when it was loaded.

    PIXBUF
          a `<gdk-pixbuf>'

    KEY
          a nul-terminated string.

    RET
          the value associated with KEY. This is a nul-terminated
          string that should not be freed or ``#f'' if KEY was not
          found.




File: guile-gnome-gdk.info,  Node: Reference Counting and Memory Mangement,  Next: File Loading,  Prev: The GdkPixbuf Structure,  Up: Top

32 Reference Counting and Memory Mangement
******************************************

Functions for reference counting and memory management on pixbufs.

32.1 Overview
=============

`<gdk-pixbuf>' structures are reference counted. This means that an
application can share a single pixbuf among many parts of the code.
When a piece of the program needs to keep a pointer to a pixbuf, it
should add a reference to it by calling `g-object-ref'. When it no
longer needs the pixbuf, it should subtract a reference by calling
`g-object-unref'. The pixbuf will be destroyed when its reference count
drops to zero. Newly-created `<gdk-pixbuf>' structures start with a
reference count of one.

   As `<gdk-pixbuf>' is derived from `<gobject>' now, `gdk-pixbuf-ref'
and `gdk-pixbuf-unref' are deprecated in favour of `g-object-ref' and
`g-object-unref' resp.

   _Finalizing_ a pixbuf means to free its pixel data and to free the
`<gdk-pixbuf>' structure itself. Most of the library functions that
create `<gdk-pixbuf>' structures create the pixel data by themselves
and define the way it should be freed; you do not need to worry about
those. The only function that lets you specify how to free the pixel
data is `gdk-pixbuf-new-from-data'. Since you pass it a pre-allocated
pixel buffer, you must also specify a way to free that data. This is
done with a function of type `<gdk-pixbuf-destroy-notify>'. When a
pixbuf created with `gdk-pixbuf-new-from-data' is finalized, your
destroy notification function will be called, and it is its
responsibility to free the pixel array.

32.2 Usage
==========


File: guile-gnome-gdk.info,  Node: File Loading,  Next: File saving,  Prev: Reference Counting and Memory Mangement,  Up: Top

33 File Loading
***************

Loading a pixbuf from a file.

33.1 Overview
=============

The gdk-pixbuf library provides a simple mechanism for loading an image
from a file in synchronous fashion. This means that the library takes
control of the application while the file is being loaded; from the
user's point of view, the application will block until the image is
done loading.

   This interface can be used by applications in which blocking is
acceptable while an image is being loaded. It can also be used to load
small images in general.  Applications that need progressive loading
can use the `<gdk-pixbuf-loader>' functionality instead.

33.2 Usage
==========

 -- Function: gdk-pixbuf-new-from-file (filename `mchars') => 
          (ret `<gdk-pixbuf>')
     Creates a new pixbuf by loading an image from a file. The file
     format is detected automatically. If ``#f'' is returned, then
     ERROR will be set. Possible errors are in the `<gdk-pixbuf-error>'
     and `<g-file-error>' domains.

    FILENAME
          Name of file to load, in the GLib file name encoding

    ERROR
          Return location for an error

    RET
          A newly-created pixbuf with a reference count of 1, or ``#f''
          if any of several error conditions occurred: the file could
          not be opened, there was no loader for the file's format,
          there was not enough memory to allocate the image buffer, or
          the image file contained invalid data.



 -- Function: gdk-pixbuf-new-from-file-at-size (filename `mchars')
          (width `int') (height `int') =>  (ret `<gdk-pixbuf>')
     Creates a new pixbuf by loading an image from a file. The file
     format is detected automatically. If ``#f'' is returned, then
     ERROR will be set. Possible errors are in the `<gdk-pixbuf-error>'
     and `<g-file-error>' domains. The image will be scaled to fit in
     the requested size, preserving the image's aspect ratio.

    FILENAME
          Name of file to load, in the GLib file name encoding

    WIDTH
          The width the image should have or -1 to not constrain the
          width

    HEIGHT
          The height the image should have or -1 to not constrain the
          height

    ERROR
          Return location for an error

    RET
          A newly-created pixbuf with a reference count of 1, or ``#f''
          if any of several error conditions occurred: the file could
          not be opened, there was no loader for the file's format,
          there was not enough memory to allocate the image buffer, or
          the image file contained invalid data.


     Since 2.4


 -- Function: gdk-pixbuf-new-from-file-at-scale (filename `mchars')
          (width `int') (height `int') (preserve_aspect_ratio `bool')
          =>  (ret `<gdk-pixbuf>')
     Creates a new pixbuf by loading an image from a file. The file
     format is detected automatically. If ``#f'' is returned, then
     ERROR will be set. Possible errors are in the `<gdk-pixbuf-error>'
     and `<g-file-error>' domains. The image will be scaled to fit in
     the requested size, optionally preserving the image's aspect ratio.

     When preserving the aspect ratio, a WIDTH of -1 will cause the
     image to be scaled to the exact given height, and a HEIGHT of -1
     will cause the image to be scaled to the exact given width. When
     not preserving aspect ratio, a WIDTH or HEIGHT of -1 means to not
     scale the image at all in that dimension. Negative values for
     WIDTH and HEIGHT are allowed since 2.8.

    FILENAME
          Name of file to load, in the GLib file name encoding

    WIDTH
          The width the image should have or -1 to not constrain the
          width

    HEIGHT
          The height the image should have or -1 to not constrain the
          height

    PRESERVE-ASPECT-RATIO
          ``#t'' to preserve the image's aspect ratio

    ERROR
          Return location for an error

    RET
          A newly-created pixbuf with a reference count of 1, or ``#f''
          if any of several error conditions occurred: the file could
          not be opened, there was no loader for the file's format,
          there was not enough memory to allocate the image buffer, or
          the image file contained invalid data.


     Since 2.6



File: guile-gnome-gdk.info,  Node: File saving,  Next: Image Data in Memory,  Prev: File Loading,  Up: Top

34 File saving
**************

Saving a pixbuf to a file.

34.1 Overview
=============

These functions allow to save a `<gdk-pixbuf>' in a number of file
formats.  The formatted data can be written to a file or to a memory
buffer. gdk-pixbuf can also call a user-defined callback on the data,
which allows to e.g. write the image to a socket or store it in a
database.

34.2 Usage
==========


File: guile-gnome-gdk.info,  Node: Image Data in Memory,  Next: Inline data,  Prev: File saving,  Up: Top

35 Image Data in Memory
***********************

Creating a pixbuf from image data that is already in memory.

35.1 Overview
=============

The most basic way to create a pixbuf is to wrap an existing pixel
buffer with a `<gdk-pixbuf>' structure. You can use the
`gdk-pixbuf-new-from-data' function to do this You need to specify the
destroy notification function that will be called when the data buffer
needs to be freed; this will happen when a `<gdk-pixbuf>' is finalized
by the reference counting functions If you have a chunk of static data
compiled into your application, you can pass in ``#f'' as the destroy
notification function so that the data will not be freed.

   The `gdk-pixbuf-new' function can be used as a convenience to create
a pixbuf with an empty buffer. This is equivalent to allocating a data
buffer using ``malloc'' and then wrapping it with
`gdk-pixbuf-new-from-data'. The `gdk-pixbuf-new' function will compute
an optimal rowstride so that rendering can be performed with an
efficient algorithm.

   As a special case, you can use the `gdk-pixbuf-new-from-xpm-data'
function to create a pixbuf from inline XPM image data.

   You can also copy an existing pixbuf with the `gdk-pixbuf-copy'
function.  This is not the same as just doing a `g-object-ref' on the
old pixbuf; the copy function will actually duplicate the pixel data in
memory and create a new `<gdk-pixbuf>' structure for it.

35.2 Usage
==========

 -- Function: gdk-pixbuf-new (colorspace `<gdk-colorspace>')
          (has_alpha `bool') (bits_per_sample `int') (width `int')
          (height `int') =>  (ret `<gdk-pixbuf>')
     Creates a new `<gdk-pixbuf>' structure and allocates a buffer for
     it. The buffer has an optimal rowstride. Note that the buffer is
     not cleared; you will have to fill it completely yourself.

    COLORSPACE
          Color space for image

    HAS-ALPHA
          Whether the image should have transparency information

    BITS-PER-SAMPLE
          Number of bits per color sample

    WIDTH
          Width of image in pixels, must be > 0

    HEIGHT
          Height of image in pixels, must be > 0

    RET
          A newly-created `<gdk-pixbuf>' with a reference count of 1, or
          ``#f'' if not enough memory could be allocated for the image
          buffer.



 -- Function: gdk-pixbuf-new-subpixbuf (self `<gdk-pixbuf>')
          (src_x `int') (src_y `int') (width `int') (height `int') => 
          (ret `<gdk-pixbuf>')
 -- Method: new-subpixbuf
     Creates a new pixbuf which represents a sub-region of SRC-PIXBUF.
     The new pixbuf shares its pixels with the original pixbuf, so
     writing to one affects both. The new pixbuf holds a reference to
     SRC-PIXBUF, so SRC-PIXBUF will not be finalized until the new
     pixbuf is finalized.

    SRC-PIXBUF
          a `<gdk-pixbuf>'

    SRC-X
          X coord in SRC-PIXBUF

    SRC-Y
          Y coord in SRC-PIXBUF

    WIDTH
          width of region in SRC-PIXBUF

    HEIGHT
          height of region in SRC-PIXBUF

    RET
          a new pixbuf




File: guile-gnome-gdk.info,  Node: Inline data,  Next: Scaling,  Prev: Image Data in Memory,  Up: Top

36 Inline data
**************

Functions for inlined pixbuf handling.

36.1 Overview
=============

Using `<gdk-pixdata>', images can be compiled into an application,
making it unnecessary to refer to external image files at runtime.
gdk-pixbuf includes a utility named gdk-pixbuf-csource, which can be
used to convert image files into `<gdk-pixdata>' structures suitable
for inclusion in C sources. To convert the `<gdk-pixdata>' structures
back into `<gdk-pixbuf>'s, use gdk_pixbuf_from_pixdata.

36.2 Usage
==========


File: guile-gnome-gdk.info,  Node: Scaling,  Next: Utilities,  Prev: Inline data,  Up: Top

37 Scaling
**********

Scaling pixbufs and scaling and compositing pixbufs

37.1 Overview
=============

The gdk-pixbuf contains functions to scale pixbufs, to scale pixbufs and
composite against an existing image, and to scale pixbufs and composite
against a solid color or checkerboard. Compositing a checkerboard is a
common way to show an image with an alpha channel in image-viewing and
editing software.

   Since the full-featured functions (`gdk-pixbuf-scale',
`gdk-pixbuf-composite', and `gdk-pixbuf-composite-color') are rather
complex to use and have many arguments, two simple convenience
functions are provided, `gdk-pixbuf-scale-simple' and
`gdk-pixbuf-composite-color-simple' which create a new pixbuf of a given
size, scale an original image to fit, and then return the new pixbuf.

   The following example demonstrates handling an expose event by
rendering the appropriate area of a source image (which is scaled to
fit the widget) onto the widget's window. The source image is rendered
against a checkerboard, which provides a visual representation of the
alpha channel if the image has one. If the image doesn't have an alpha
channel, calling `gdk-pixbuf-composite-color' function has exactly the
same effect as calling `gdk-pixbuf-scale'.


     gboolean
     expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
     {
       GdkPixbuf *dest;

       dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);

       gdk_pixbuf_composite_color (pixbuf, dest,
                                   0, 0, event->area.width, event->area.height,
                                   -event->area.x, -event->area.y,
                                   (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
                                   (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
                                   GDK_INTERP_BILINEAR, 255,
                                   event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);

       gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
                                      0, 0, event->area.x, event->area.y,
                                      event->area.width, event->area.height,
                                      GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);

       gdk_pixbuf_unref (dest);

       return TRUE;
     }

37.2 Usage
==========

 -- Function: gdk-pixbuf-scale-simple (self `<gdk-pixbuf>')
          (dest_width `int') (dest_height `int')
          (interp_type `<gdk-interp-type>') =>  (ret `<gdk-pixbuf>')
 -- Method: scale-simple
     Create a new `<gdk-pixbuf>' containing a copy of SRC scaled to
     DEST-WIDTH x DEST-HEIGHT. Leaves SRC unaffected.  INTERP-TYPE
     should be `<gdk-interp-nearest>' if you want maximum speed (but
     when scaling down `<gdk-interp-nearest>' is usually unusably
     ugly). The default INTERP-TYPE should be `<gdk-interp-bilinear>'
     which offers reasonable quality and speed.

     You can scale a sub-portion of SRC by creating a sub-pixbuf
     pointing into SRC; see `gdk-pixbuf-new-subpixbuf'.

     For more complicated scaling/compositing see `gdk-pixbuf-scale' and
     `gdk-pixbuf-composite'.

    SRC
          a `<gdk-pixbuf>'

    DEST-WIDTH
          the width of destination image

    DEST-HEIGHT
          the height of destination image

    INTERP-TYPE
          the interpolation type for the transformation.

    RET
          the new `<gdk-pixbuf>', or ``#f'' if not enough memory could
          be allocated for it.



 -- Function: gdk-pixbuf-scale (self `<gdk-pixbuf>')
          (dest `<gdk-pixbuf>') (dest_x `int') (dest_y `int')
          (dest_width `int') (dest_height `int') (offset_x `double')
          (offset_y `double') (scale_x `double') (scale_y `double')
          (interp_type `<gdk-interp-type>')
 -- Method: scale
     Creates a transformation of the source image SRC by scaling by
     SCALE-X and SCALE-Y then translating by OFFSET-X and OFFSET-Y,
     then renders the rectangle (DEST-X, DEST-Y, DEST-WIDTH,
     DEST-HEIGHT) of the resulting image onto the destination image
     replacing the previous contents.

     Try to use `gdk-pixbuf-scale-simple' first, this function is the
     industrial-strength power tool you can fall back to if
     `gdk-pixbuf-scale-simple' isn't powerful enough.

    SRC
          a `<gdk-pixbuf>'

    DEST
          the `<gdk-pixbuf>' into which to render the results

    DEST-X
          the left coordinate for region to render

    DEST-Y
          the top coordinate for region to render

    DEST-WIDTH
          the width of the region to render

    DEST-HEIGHT
          the height of the region to render

    OFFSET-X
          the offset in the X direction (currently rounded to an
          integer)

    OFFSET-Y
          the offset in the Y direction (currently rounded to an
          integer)

    SCALE-X
          the scale factor in the X direction

    SCALE-Y
          the scale factor in the Y direction

    INTERP-TYPE
          the interpolation type for the transformation.



 -- Function: gdk-pixbuf-composite-color-simple (self `<gdk-pixbuf>')
          (dest_width `int') (dest_height `int')
          (interp_type `<gdk-interp-type>') (overall_alpha `int')
          (check_size `int') (color1 `unsigned-int32')
          (color2 `unsigned-int32') =>  (ret `<gdk-pixbuf>')
 -- Method: composite-color-simple
     Creates a new `<gdk-pixbuf>' by scaling SRC to DEST-WIDTH x
     DEST-HEIGHT and compositing the result with a checkboard of colors
     COLOR1 and COLOR2.

    SRC
          a `<gdk-pixbuf>'

    DEST-WIDTH
          the width of destination image

    DEST-HEIGHT
          the height of destination image

    INTERP-TYPE
          the interpolation type for the transformation.

    OVERALL-ALPHA
          overall alpha for source image (0..255)

    CHECK-SIZE
          the size of checks in the checkboard (must be a power of two)

    COLOR1
          the color of check at upper left

    COLOR2
          the color of the other check

    RET
          the new `<gdk-pixbuf>', or ``#f'' if not enough memory could
          be allocated for it.



 -- Function: gdk-pixbuf-composite (self `<gdk-pixbuf>')
          (dest `<gdk-pixbuf>') (dest_x `int') (dest_y `int')
          (dest_width `int') (dest_height `int') (offset_x `double')
          (offset_y `double') (scale_x `double') (scale_y `double')
          (interp_type `<gdk-interp-type>') (overall_alpha `int')
 -- Method: composite
     Creates a transformation of the source image SRC by scaling by
     SCALE-X and SCALE-Y then translating by OFFSET-X and OFFSET-Y.
     This gives an image in the coordinates of the destination pixbuf.
     The rectangle (DEST-X, DEST-Y, DEST-WIDTH, DEST-HEIGHT) is then
     composited onto the corresponding rectangle of the original
     destination image.

     When the destination rectangle contains parts not in the source
     image, the data at the edges of the source image is replicated to
     infinity.

     (The missing figure, pixbuf-composite-diagram

    SRC
          a `<gdk-pixbuf>'

    DEST
          the `<gdk-pixbuf>' into which to render the results

    DEST-X
          the left coordinate for region to render

    DEST-Y
          the top coordinate for region to render

    DEST-WIDTH
          the width of the region to render

    DEST-HEIGHT
          the height of the region to render

    OFFSET-X
          the offset in the X direction (currently rounded to an
          integer)

    OFFSET-Y
          the offset in the Y direction (currently rounded to an
          integer)

    SCALE-X
          the scale factor in the X direction

    SCALE-Y
          the scale factor in the Y direction

    INTERP-TYPE
          the interpolation type for the transformation.

    OVERALL-ALPHA
          overall alpha for source image (0..255)



 -- Function: gdk-pixbuf-composite-color (self `<gdk-pixbuf>')
          (dest `<gdk-pixbuf>') (dest_x `int') (dest_y `int')
          (dest_width `int') (dest_height `int') (offset_x `double')
          (offset_y `double') (scale_x `double') (scale_y `double')
          (interp_type `<gdk-interp-type>') (overall_alpha `int')
          (check_x `int') (check_y `int') (check_size `int')
          (color1 `unsigned-int32') (color2 `unsigned-int32')
 -- Method: composite-color
     Creates a transformation of the source image SRC by scaling by
     SCALE-X and SCALE-Y then translating by OFFSET-X and OFFSET-Y,
     then composites the rectangle (DEST-X ,DEST-Y, DEST-WIDTH,
     DEST-HEIGHT) of the resulting image with a checkboard of the
     colors COLOR1 and COLOR2 and renders it onto the destination image.

     See `gdk-pixbuf-composite-color-simple' for a simpler variant of
     this function suitable for many tasks.

    SRC
          a `<gdk-pixbuf>'

    DEST
          the `<gdk-pixbuf>' into which to render the results

    DEST-X
          the left coordinate for region to render

    DEST-Y
          the top coordinate for region to render

    DEST-WIDTH
          the width of the region to render

    DEST-HEIGHT
          the height of the region to render

    OFFSET-X
          the offset in the X direction (currently rounded to an
          integer)

    OFFSET-Y
          the offset in the Y direction (currently rounded to an
          integer)

    SCALE-X
          the scale factor in the X direction

    SCALE-Y
          the scale factor in the Y direction

    INTERP-TYPE
          the interpolation type for the transformation.

    OVERALL-ALPHA
          overall alpha for source image (0..255)

    CHECK-X
          the X offset for the checkboard (origin of checkboard is at
          -CHECK-X, -CHECK-Y)

    CHECK-Y
          the Y offset for the checkboard

    CHECK-SIZE
          the size of checks in the checkboard (must be a power of two)

    COLOR1
          the color of check at upper left

    COLOR2
          the color of the other check



 -- Function: gdk-pixbuf-rotate-simple (self `<gdk-pixbuf>')
          (angle `<gdk-pixbuf-rotation>') =>  (ret `<gdk-pixbuf>')
 -- Method: rotate-simple
     Rotates a pixbuf by a multiple of 90 degrees, and returns the
     result in a new pixbuf.

    SRC
          a `<gdk-pixbuf>'

    ANGLE
          the angle to rotate by

    RET
          a new pixbuf


     Since 2.6


 -- Function: gdk-pixbuf-flip (self `<gdk-pixbuf>') (horizontal `bool')
          =>  (ret `<gdk-pixbuf>')
 -- Method: flip
     Flips a pixbuf horizontally or vertically and returns the result
     in a new pixbuf.

    SRC
          a `<gdk-pixbuf>'

    HORIZONTAL
          ``#t'' to flip horizontally, ``#f'' to flip vertically

    RET
          a new pixbuf.


     Since 2.6



File: guile-gnome-gdk.info,  Node: Utilities,  Next: Animations,  Prev: Scaling,  Up: Top

38 Utilities
************

Utility and miscellaneous convenience functions.

38.1 Overview
=============

These functions provide miscellaneous utilities for manipulating
pixbufs. The pixel data in pixbufs may of course be manipulated
directly by applications, but several common operations can be
performed by these functions instead.

38.2 Usage
==========

 -- Function: gdk-pixbuf-add-alpha (self `<gdk-pixbuf>')
          (substitute_color `bool') (r `unsigned-char')
          (g `unsigned-char') (b `unsigned-char') => 
          (ret `<gdk-pixbuf>')
 -- Method: add-alpha
     Takes an existing pixbuf and adds an alpha channel to it. If the
     existing pixbuf already had an alpha channel, the channel values
     are copied from the original; otherwise, the alpha channel is
     initialized to 255 (full opacity).

     If SUBSTITUTE-COLOR is ``#t'', then the color specified by (R, G,
     B) will be assigned zero opacity. That is, if you pass (255, 255,
     255) for the substitute color, all white pixels will become fully
     transparent.

    PIXBUF
          A `<gdk-pixbuf>'.

    SUBSTITUTE-COLOR
          Whether to set a color to zero opacity. If this is ``#f'',
          then the (R, G, B) arguments will be ignored.

    R
          Red value to substitute.

    G
          Green value to substitute.

    B
          Blue value to substitute.

    RET
          A newly-created pixbuf with a reference count of 1.



 -- Function: gdk-pixbuf-copy-area (self `<gdk-pixbuf>') (src_x `int')
          (src_y `int') (width `int') (height `int')
          (dest_pixbuf `<gdk-pixbuf>') (dest_x `int') (dest_y `int')
 -- Method: copy-area
     Copies a rectangular area from SRC-PIXBUF to DEST-PIXBUF.
     Conversion of pixbuf formats is done automatically.

    SRC-PIXBUF
          Source pixbuf.

    SRC-X
          Source X coordinate within SRC-PIXBUF.

    SRC-Y
          Source Y coordinate within SRC-PIXBUF.

    WIDTH
          Width of the area to copy.

    HEIGHT
          Height of the area to copy.

    DEST-PIXBUF
          Destination pixbuf.

    DEST-X
          X coordinate within DEST-PIXBUF.

    DEST-Y
          Y coordinate within DEST-PIXBUF.



 -- Function: gdk-pixbuf-saturate-and-pixelate (self `<gdk-pixbuf>')
          (dest `<gdk-pixbuf>') (saturation `float') (pixelate `bool')
 -- Method: saturate-and-pixelate
     Modifies saturation and optionally pixelates SRC, placing the
     result in DEST. SRC and DEST may be the same pixbuf with no ill
     effects.  If SATURATION is 1.0 then saturation is not changed. If
     it's less than 1.0, saturation is reduced (the image turns toward
     grayscale); if greater than 1.0, saturation is increased (the
     image gets more vivid colors). If PIXELATE is ``#t'', then pixels
     are faded in a checkerboard pattern to create a pixelated image.
     SRC and DEST must have the same image format, size, and rowstride.

    SRC
          source image

    DEST
          place to write modified version of SRC

    SATURATION
          saturation factor

    PIXELATE
          whether to pixelate



 -- Function: gdk-pixbuf-fill (self `<gdk-pixbuf>')
          (pixel `unsigned-int32')
 -- Method: fill
     Clears a pixbuf to the given RGBA value, converting the RGBA value
     into the pixbuf's pixel format. The alpha will be ignored if the
     pixbuf doesn't have an alpha channel.

    PIXBUF
          a `<gdk-pixbuf>'

    PIXEL
          RGBA pixel to clear to (0xffffffff is opaque white,
          0x00000000 transparent black)




File: guile-gnome-gdk.info,  Node: Animations,  Next: GdkPixbufLoader,  Prev: Utilities,  Up: Top

39 Animations
*************

Animated images.

39.1 Overview
=============

The gdk-pixbuf library provides a simple mechanism to load and represent
animations. An animation is conceptually a series of frames to be
displayed over time. Each frame is the same size. The animation may not
be represented as a series of frames internally; for example, it may be
stored as a sprite and instructions for moving the sprite around a
background. To display an animation you don't need to understand its
representation, however; you just ask gdk-pixbuf what should be
displayed at a given point in time.

39.2 Usage
==========

 -- Class: <gdk-pixbuf-animation>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Class: <gdk-pixbuf-animation-iter>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Class: <gdk-pixbuf-simple-anim>
     Derives from `<gdk-pixbuf-animation>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gdk-pixbuf-animation-new-from-file (filename `mchars')
          =>  (ret `<gdk-pixbuf-animation>')
     Creates a new animation by loading it from a file. The file format
     is detected automatically. If the file's format does not support
     multi-frame images, then an animation with a single frame will be
     created. Possible errors are in the `<gdk-pixbuf-error>' and
     `<g-file-error>' domains.

    FILENAME
          Name of file to load, in the GLib file name encoding

    ERROR
          return location for error

    RET
          A newly-created animation with a reference count of 1, or
          ``#f'' if any of several error conditions ocurred: the file
          could not be opened, there was no loader for the file's
          format, there was not enough memory to allocate the image
          buffer, or the image file contained invalid data.



 -- Function: gdk-pixbuf-animation-get-width
          (self `<gdk-pixbuf-animation>') =>  (ret `int')
 -- Method: get-width
     Queries the width of the bounding box of a pixbuf animation.

    ANIMATION
          An animation.

    RET
          Width of the bounding box of the animation.



 -- Function: gdk-pixbuf-animation-get-height
          (self `<gdk-pixbuf-animation>') =>  (ret `int')
 -- Method: get-height
     Queries the height of the bounding box of a pixbuf animation.

    ANIMATION
          An animation.

    RET
          Height of the bounding box of the animation.



 -- Function: gdk-pixbuf-simple-anim-new (width `int') (height `int')
          (rate `float') =>  (ret `<gdk-pixbuf-simple-anim>')
     Creates a new, empty animation.

    WIDTH
          the width of the animation

    HEIGHT
          the height of the animation

    RATE
          the speed of the animation, in frames per second

    RET
          a newly allocated `<gdk-pixbuf-simple-anim>'


     Since 2.8


 -- Function: gdk-pixbuf-simple-anim-add-frame
          (self `<gdk-pixbuf-simple-anim>') (pixbuf `<gdk-pixbuf>')
 -- Method: add-frame
     Adds a new frame to ANIMATION. The PIXBUF must have the dimensions
     specified when the animation was constructed.

    ANIMATION
          a `<gdk-pixbuf-simple-anim>'

    PIXBUF
          the pixbuf to add


     Since 2.8


