This is guile-gnome-gdk.info, produced by makeinfo version 4.8 from
/home/wingo/src/guile-gnome/platform/gtk/doc/gdk/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.

* Concept 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-exit (error_code `int')
     `gdk_exit' is deprecated and should not be used in newly-written
     code.

     Exits the application using the ``exit'' system call.

     This routine is provided mainly for backwards compatibility,
     since it used to perform tasks necessary to exit the application
     cleanly. Those tasks are now performed in a function which is
     automatically called on exit (via the use of `g-atexit').

    ERROR-CODE
          the error code to pass to the ``exit'' call.



 -- 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 commandline
     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 command line option.

    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>
     This `<gobject>' 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-pointer (self `<gdk-display>')
          (screen `<gdk-screen**>') (mask `<gdk-modifier-type*>') => 
          (x `int') (y `int')
 -- Method: get-pointer
     Gets the current location of the pointer and the current
     modifier mask for a given display.

    DISPLAY
          a `<gdk-display>'

    SCREEN
          location to store the screen that the cursor is on, or
          ``#f''.

    X
          location to store root window X coordinate of pointer, or
          ``#f''.

    Y
          location to store root window Y coordinate of pointer, or
          ``#f''.

    MASK
          location to store current modifier mask, or ``#f''


     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
=========

 -- 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')
     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>
     This `<gobject>' 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>

 -- Function: gdk-rectangle-intersect (self `<gdk-rectangle>')
          (src2 `<gdk-rectangle>') (dest `<gdk-rectangle>') => 
          (ret `bool')
     Calculates the intersection of two rectangles. It is allowed for
     DEST to be the same as either SRC1 or SRC2.

    SRC1
          a `<gdk-rectangle>'

    SRC2
          a `<gdk-rectangle>'

    DEST
          return location for the intersection of SRC1 and SRC2

    RET
          ``#t'' if the rectangles intersect.



 -- Function: gdk-rectangle-union (self `<gdk-rectangle>')
          (src2 `<gdk-rectangle>') (dest `<gdk-rectangle>')
     Calculates the union of two rectangles. The union of rectangles
     SRC1 and SRC2 is the smallest rectangle which includes both SRC1
     and SRC2 within it. It is allowed for DEST to be the same as
     either SRC1 or SRC2.

    SRC1
          a `<gdk-rectangle>'

    SRC2
          a `<gdk-rectangle>'

    DEST
          return location for the union of SRC1 and SRC2



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

    RET
          a new empty `<gdk-region>'



 -- Function: gdk-region-polygon (points `<gdk-point*>')
          (npoints `int') (fill_rule `<gdk-fill-rule>') => 
          (ret `<gdk-region*>')
     Creates a new `<gdk-region>' using the polygon defined by a
     number of points.

    POINTS
          an array of `<gdk-point>' structs

    NPOINTS
          the number of elements in the POINTS array

    FILL-RULE
          specifies which pixels are included in the region when the
          polygon overlaps itself.

    RET
          a new `<gdk-region>' based on the given polygon



 -- 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-get-clipbox (self `<gdk-region*>')
          (rectangle `<gdk-rectangle>')
     Obtains the smallest rectangle which includes the entire
     `<gdk-region>'.

    REGION
          a `<gdk-region>'

    RECTANGLE
          return location for the clipbox



 -- Function: gdk-region-get-rectangles (self `<gdk-region*>')
          (rectangles `<gdk-rectangle**>') =>  (n_rectangles `int')
     Obtains the area covered by the region as a list of rectangles.
     The array returned in RECTANGLES must be freed with `g-free'.

    REGION
          a `<gdk-region>'

    RECTANGLES
          return location for an array of rectangles

    N-RECTANGLES
          length of returned array



 -- 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>
     This `<gobject>' 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-new-with-values (drawable `<gdk-drawable>')
          (values `<gdk-gc-values*>')
          (values_mask `<gdk-gc-values-mask>') =>  (ret `<gdk-gc>')
     Create a new GC with the given initial values.

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

    VALUES
          a structure containing initial values for the GC.

    VALUES-MASK
          a bit mask indicating which fields in VALUES are set.

    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-values (self `<gdk-gc>')
          (values `<gdk-gc-values*>')
          (values_mask `<gdk-gc-values-mask>')
 -- Method: set-values
     Sets attributes of a graphics context in bulk. For each flag set
     in VALUES-MASK, the corresponding field will be read from VALUES
     and set as the new value for GC. If you're only setting a few
     values on GC, calling individual "setter" functions is likely
     more convenient.

    GC
          a `<gdk-gc>'

    VALUES
          struct containing the new values

    VALUES-MASK
          mask indicating which struct fields are to be used



 -- Function: gdk-gc-get-values (self `<gdk-gc>')
          (values `<gdk-gc-values*>')
 -- Method: get-values
     Retrieves the current values from a graphics context. Note that
     only the pixel values of the VALUES->FOREGROUND and
     VALUES->BACKGROUND are filled, use `gdk-colormap-query-color' to
     obtain the rgb values if you need them.

    GC
          a `<gdk-gc>'.

    VALUES
          the `<gdk-gc-values>' structure in which to store the
          results.



 -- 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-bitmap*>')
 -- 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-set-dashes (self `<gdk-gc>') (dash_offset `int')
          (dash_list `<gint8*>') (n `int')
 -- Method: set-dashes
     Sets the way dashed-lines are drawn. Lines will be drawn with
     alternating on and off segments of the lengths specified in
     DASH-LIST. The manner in which the on and off segments are drawn
     is determined by the LINE-STYLE value of the GC. (This can be
     changed with `gdk-gc-set-line-attributes'.)

     The DASH-OFFSET defines the phase of the pattern, specifying how
     many pixels into the dash-list the pattern should actually begin.

    GC
          a `<gdk-gc>'.

    DASH-OFFSET
          the phase of the dash pattern.

    DASH-LIST
          an array of dash lengths.

    N
          the number of elements in DASH-LIST.



 -- 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>
     This `<gobject>' class defines no properties, other than those
     defined by its superclasses.


 -- Function: gdk-drawable-set-data (self `<gdk-drawable>')
          (key `mchars') (data `<gpointer>')
          (destroy_func `<g-destroy-notify>')
 -- Method: set-data
     `gdk_drawable_set_data' is deprecated and should not be used in
     newly-written code.

     This function is equivalent to `g-object-set-data', the
     `<gobject>' variant should be used instead.

    DRAWABLE
          a `<gdk-drawable>'

    KEY
          name to store the data under

    DATA
          arbitrary data

    DESTROY-FUNC
          function to free DATA, or ``#f''



 -- Function: gdk-drawable-get-data (self `<gdk-drawable>')
          (key `mchars') =>  (ret `<gpointer>')
 -- Method: get-data
     `gdk_drawable_get_data' is deprecated and should not be used in
     newly-written code.

     Equivalent to `g-object-get-data'; the `<gobject>' variant
     should be used instead.

    DRAWABLE
          a `<gdk-drawable>'

    KEY
          name the data was stored under

    RET
          the data stored at KEY



 -- 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-points (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (points `<gdk-point*>') (npoints `int')
     Draws a number of points, 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>'.

    POINTS
          an array of `<gdk-point>' structures.

    NPOINTS
          the number of points to be drawn.



 -- 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-lines (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (points `<gdk-point*>') (npoints `int')
     Draws a series of lines connecting the given points. The way in
     which joins between lines are draw is determined by the
     `<gdk-cap-style>' value in the `<gdk-gc>'. This can be set with
     `gdk-gc-set-line-attributes'.

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

    GC
          a `<gdk-gc>'.

    POINTS
          an array of `<gdk-point>' structures specifying the
          endpoints of the

    NPOINTS
          the size of the POINTS array.



 -- 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-segments (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (segs `<gdk-segment*>') (nsegs `int')
     Draws a number of unconnected lines.

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

    GC
          a `<gdk-gc>'.

    SEGS
          an array of `<gdk-segment>' structures specifying the start
          and end points of the lines to be drawn.

    NSEGS
          the number of line segments to draw, i.e. the size of the
          SEGS array.



 -- 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-polygon (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (filled `bool') (points `<gdk-point*>')
          (npoints `int')
     Draws an outlined or filled polygon.

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

    GC
          a `<gdk-gc>'.

    FILLED
          ``#t'' if the polygon should be filled. The polygon is
          closed automatically, connecting the last point to the
          first point if necessary.

    POINTS
          an array of `<gdk-point>' structures specifying the points
          making up the polygon.

    NPOINTS
          the number of points.



 -- 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-text (drawable `<gdk-drawable>')
          (font `<gdk-font>') (gc `<gdk-gc>') (x `int') (y `int')
          (text `mchars') (text_length `int')
     `gdk_draw_text' is deprecated and should not be used in
     newly-written code.  Use `gdk-draw-layout' instead.

     Draws a number 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.

    TEXT
          the characters to draw.

    TEXT-LENGTH
          the number of characters of TEXT to draw.



 -- Function: gdk-draw-text-wc (drawable `<gdk-drawable>')
          (font `<gdk-font>') (gc `<gdk-gc>') (x `int') (y `int')
          (text `<gdk-wchar*>') (text_length `int')
     `gdk_draw_text_wc' is deprecated and should not be used in
     newly-written code. Use `gdk-draw-layout' instead.

     Draws a number of wide characters using the given font of
     fontset. If the font is a 1-byte font, the string is converted
     into 1-byte characters (discarding the high bytes) before output.

    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.

    TEXT
          the wide characters to draw.

    TEXT-LENGTH
          the number 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-bitmap*>')
     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>'



 -- Function: gdk-pixmap-create-from-xpm (drawable `<gdk-drawable>')
          (mask `<gdk-bitmap**>') (transparent_color `<gdk-color>')
          (filename `mchars') =>  (ret `<gdk-pixmap*>')
     Create a pixmap from a XPM file.

    DRAWABLE
          a `<gdk-drawable>', used to determine default values for
          the new pixmap.

    MASK
          a pointer to a place to store a bitmap representing the
          transparency mask of the XPM file. Can be ``#f'', in which
          case transparency will be ignored.

    TRANSPARENT-COLOR
          the color to be used for the pixels that are transparent in
          the input file. Can be ``#f'', in which case a default
          color will be used.

    FILENAME
          the filename of a file containing XPM data.

    RET
          the `<gdk-pixmap>'



 -- Function: gdk-pixmap-colormap-create-from-xpm
          (drawable `<gdk-drawable>') (colormap `<gdk-colormap>')
          (mask `<gdk-bitmap**>') (transparent_color `<gdk-color>')
          (filename `mchars') =>  (ret `<gdk-pixmap*>')
     Create a pixmap from a XPM file using a particular colormap.

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

    COLORMAP
          the `<gdk-colormap>' that the new pixmap will be use. If
          omitted, the colormap for WINDOW will be used.

    MASK
          a pointer to a place to store a bitmap representing the
          transparency mask of the XPM file. Can be ``#f'', in which
          case transparency will be ignored.

    TRANSPARENT-COLOR
          the color to be used for the pixels that are transparent in
          the input file. Can be ``#f'', in which case a default
          color will be used.

    FILENAME
          the filename of a file containing XPM data.

    RET
          the `<gdk-pixmap>'.



 -- Function: gdk-pixmap-create-from-xpm-d
          (drawable `<gdk-drawable>') (mask `<gdk-bitmap**>')
          (transparent_color `<gdk-color>') =>  (ret `<gdk-pixmap*>')
          (data `mchars')
     Create a pixmap from data in XPM format.

    DRAWABLE
          a `<gdk-drawable>', used to determine default values for
          the new pixmap.

    MASK
          Pointer to a place to store a bitmap representing the
          transparency mask of the XPM file. Can be ``#f'', in which
          case transparency will be ignored.

    TRANSPARENT-COLOR
          This color will be used for the pixels that are transparent
          in the input file.  Can be ``#f'' in which case a default
          color will be used.

    DATA
          Pointer to a string containing the XPM data.

    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-draw-rgb-image (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (width `int')
          (height `int') (dith `<gdk-rgb-dither>')
          (rgb_buf `<guchar*>') (rowstride `int')
     Draws an RGB image in the drawable. This is the core GdkRGB
     function, and likely the only one you will need to use.

     The ROWSTRIDE parameter allows for lines to be aligned more
     flexibly. For example, lines may be allocated to begin on 32-bit
     boundaries, even if the width of the rectangle is odd. Rowstride
     is also useful when drawing a subrectangle of a larger image in
     memory. Finally, to replicate the same line a number of times,
     the trick of setting ROWSTRIDE to 0 is allowed.

     In general, for 0 <= i < WIDTH and 0 <= j < height, the pixel (x
     + i, y + j) is colored with red value RGB-BUF[J * ROWSTRIDE + I *
     3], green value RGB-BUF[J * ROWSTRIDE + I * 3 + 1], and blue
     value RGB-BUF[J * ROWSTRIDE + I * 3 + 2].

    DRAWABLE
          The `<gdk-drawable>' to draw in (usually a `<gdk-window>').

    GC
          The graphics context (all GDK drawing operations require
          one; its contents are ignored).

    X
          The x coordinate of the top-left corner in the drawable.

    Y
          The y coordinate of the top-left corner in the drawable.

    WIDTH
          The width of the rectangle to be drawn.

    HEIGHT
          The height of the rectangle to be drawn.

    DITH
          A `<gdk-rgb-dither>' value, selecting the desired dither
          mode.

    RGB-BUF
          The pixel data, represented as packed 24-bit data.

    ROWSTRIDE
          The number of bytes from the start of one row in RGB-BUF to
          the start of the next.



 -- Function: gdk-draw-indexed-image (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (width `int')
          (height `int') (dith `<gdk-rgb-dither>') (buf `<guchar*>')
          (rowstride `int') (cmap `<gdk-rgb-cmap*>')
     Draws an indexed image in the drawable, using a `<gdk-rgb-cmap>'
     to assign actual colors to the color indices.

    DRAWABLE
          The `<gdk-drawable>' to draw in (usually a `<gdk-window>').

    GC
          The graphics context.

    X
          The x coordinate of the top-left corner in the drawable.

    Y
          The y coordinate of the top-left corner in the drawable.

    WIDTH
          The width of the rectangle to be drawn.

    HEIGHT
          The height of the rectangle to be drawn.

    DITH
          A `<gdk-rgb-dither>' value, selecting the desired dither
          mode.

    BUF
          The pixel data, represented as 8-bit color indices.

    ROWSTRIDE
          The number of bytes from the start of one row in BUF to the
          start of the next.

    CMAP
          The `<gdk-rgb-cmap>' used to assign colors to the color
          indices.



 -- Function: gdk-draw-gray-image (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (width `int')
          (height `int') (dith `<gdk-rgb-dither>') (buf `<guchar*>')
          (rowstride `int')
     Draws a grayscale image in the drawable.

    DRAWABLE
          The `<gdk-drawable>' to draw in (usually a `<gdk-window>').

    GC
          The graphics context.

    X
          The x coordinate of the top-left corner in the drawable.

    Y
          The y coordinate of the top-left corner in the drawable.

    WIDTH
          The width of the rectangle to be drawn.

    HEIGHT
          The height of the rectangle to be drawn.

    DITH
          A `<gdk-rgb-dither>' value, selecting the desired dither
          mode.

    BUF
          The pixel data, represented as 8-bit gray values.

    ROWSTRIDE
          The number of bytes from the start of one row in BUF to the
          start of the next.



 -- Function: gdk-draw-rgb-32-image (drawable `<gdk-drawable>')
          (gc `<gdk-gc>') (x `int') (y `int') (width `int')
          (height `int') (dith `<gdk-rgb-dither>') (buf `<guchar*>')
          (rowstride `int')
     Draws a padded RGB image in the drawable. The image is stored as
     one pixel per 32-bit word. It is laid out as a red byte, a green
     byte, a blue byte, and a padding byte.

     It's unlikely that this function will give significant
     performance gains in practice. In my experience, the performance
     gain from having pixels aligned to 32-bit boundaries is
     cancelled out by the increased memory bandwidth.

    DRAWABLE
          The `<gdk-drawable>' to draw in (usually a `<gdk-window>').

    GC
          The graphics context.

    X
          The x coordinate of the top-left corner in the drawable.

    Y
          The y coordinate of the top-left corner in the drawable.

    WIDTH
          The width of the rectangle to be drawn.

    HEIGHT
          The height of the rectangle to be drawn.

    DITH
          A `<gdk-rgb-dither>' value, selecting the desired dither
          mode.

    BUF
          The pixel data, represented as padded 32-bit data.

    ROWSTRIDE
          The number of bytes from the start of one row in BUF to the
          start of the next.



 -- Function: gdk-rgb-cmap-new (n_colors `int') => 
          (ret `<gdk-rgb-cmap*>') (colors `unsigned-int32')
     Creates a new `<gdk-rgb-cmap>' structure. The cmap maps color
     indexes to RGB colors. If N-COLORS is less than 256, then images
     containing color values greater than or equal to N-COLORS will
     produce undefined results, including possibly segfaults.

    COLORS
          The colors, represented as 0xRRGGBB integer values.

    N-COLORS
          The number of colors in the cmap.

    RET
          The newly created `<gdk-rgb-cmap>'



 -- 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 field of a `<gdk-color>'
     struct.

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

    RET
          The X pixel value.



 -- Function: gdk-rgb-find-color (colormap `<gdk-colormap>')
          (color `<gdk-color>')
     COLORMAP should be the colormap for the graphics context and
     drawable you're using to draw. If you're drawing to a
     `<gtk-widget>', call `gtk-widget-get-colormap'.

     COLOR should have its `red', `green', and `blue' fields
     initialized; `gdk-rgb-find-color' will fill in the `pixel' field
     with the best matching pixel from a color cube. The color is
     then ready to be used for drawing, e.g. you can call
     `gdk-gc-set-foreground' which expects `pixel' to be initialized.

     In many cases, you can avoid this whole issue by calling
     `gdk-gc-set-rgb-fg-color' or `gdk-gc-set-rgb-bg-color', which do
     not expect `pixel' to be initialized in advance. If you use
     those functions, there's no need for `gdk-rgb-find-color'.

    COLORMAP
          a `<gdk-colormap>'

    COLOR
          a `<gdk-color>'



 -- 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>
     This `<gobject>' 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-bitmap*>') (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-render-pixmap-and-mask (self `<gdk-pixbuf>')
          (pixmap_return `<gdk-pixmap**>')
          (mask_return `<gdk-bitmap**>') (alpha_threshold `int')
 -- Method: render-pixmap-and-mask
     Creates a pixmap and a mask bitmap which are returned in the
     PIXMAP-RETURN and MASK-RETURN arguments, respectively, and
     renders a pixbuf and its corresponding thresholded alpha mask to
     them. This is merely a convenience function; applications that
     need to render pixbufs with dither offsets or to given drawables
     should use `gdk-draw-pixbuf' and
     `gdk-pixbuf-render-threshold-alpha'.

     The pixmap that is created is created for the colormap returned
     by `gdk-rgb-get-colormap'. You normally will want to instead use
     the actual colormap for a widget, and use
     `gdk-pixbuf-render-pixmap-and-mask-for-colormap'.

     If the pixbuf does not have an alpha channel, then *MASK-RETURN
     will be set to ``#f''.

    PIXBUF
          A pixbuf.

    PIXMAP-RETURN
          Location to store a pointer to the created pixmap, or
          ``#f'' if the pixmap is not needed.

    MASK-RETURN
          Location to store a pointer to the created mask, or ``#f''
          if the mask is not needed.

    ALPHA-THRESHOLD
          Threshold value for opacity values.



 -- 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>

 -- Class: <gdk-colormap>
     This `<gobject>' class defines no properties, other than those
     defined by its superclasses.


 -- 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 , ,
     and fields of a `<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 field will be 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
==========

 -- Function: gdk-query-depths (depths `<gint**>') =>  (count `int')
     This function returns the available bit depths for the default
     screen. It's equivalent to listing the visuals
     (`gdk-list-visuals') and then looking at the depth field in each
     visual, removing duplicates.

     The array returned by this function should not be freed.

    DEPTHS
          return location for available depths

    COUNT
          return location for number of available depths



 -- Function: gdk-query-visual-types
          (visual_types `<gdk-visual-type**>') =>  (count `int')
     This function returns the available visual types for the default
     screen. It's equivalent to listing the visuals
     (`gdk-list-visuals') and then looking at the type field in each
     visual, removing duplicates.

     The array returned by this function should not be freed.

    VISUAL-TYPES
          return location for the available visual types

    COUNT
          return location for the number of available visual types



 -- 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>')
     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>

 -- 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-text-extents (font `<gdk-font>') (text `mchars')
          (text_length `int') =>  (lbearing `int') (rbearing `int')
          (width `int') (ascent `int') (descent `int')
     `gdk_text_extents' is deprecated and should not be used in
     newly-written code.

     Gets the metrics of a string.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure

    TEXT-LENGTH
          the length of the text in bytes. (If the font is a 16-bit
          font, this is twice the length of the text in characters.)

    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-text-extents-wc (font `<gdk-font>')
          (text `<gdk-wchar*>') (text_length `int') => 
          (lbearing `int') (rbearing `int') (width `int')
          (ascent `int') (descent `int')
     `gdk_text_extents_wc' is deprecated and should not be used in
     newly-written code.

     Gets the metrics of a string of wide characters.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure.

    TEXT-LENGTH
          the length of the text in character.

    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-text-width-wc (font `<gdk-font>')
          (text `<gdk-wchar*>') (text_length `int') =>  (ret `int')
     `gdk_text_width_wc' is deprecated and should not be used in
     newly-written code.

     Determines the width of a given wide-character string.

    FONT
          a `<gdk-font>'

    TEXT
          the text to measure.

    TEXT-LENGTH
          the length of the text in characters.

    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.



 -- Function: gdk-mbstowcs (dest `<gdk-wchar*>') (src `mchars')
          (dest_max `int') =>  (ret `int')
     `gdk_mbstowcs' is deprecated and should not be used in
     newly-written code.

     Converts a multi-byte string to a wide character string. (The
     function name comes from an acronym of 'Multi-Byte String TO
     Wide Character String').

    DEST
          the space to place the converted wide character string into.

    SRC
          the multi-byte string to convert, which must be
          nul-terminated.

    DEST-MAX
          the maximum number of wide characters to place in DEST.

    RET
          the number of wide characters written into DEST, or -1 if
          the conversion failed.




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>

 -- 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)

     `<gdk-xterm>' (I-beam)

     `<gdk-watch>' (busy)

     `<gdk-fleur>' (for moving objects)

     `<gdk-hand1>' (a right-pointing hand)

     `<gdk-hand2>' (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-new (self `<gdk-window*>')
          (attributes `<gdk-window-attr*>') (attributes_mask `int')
          =>  (ret `<gdk-window*>')
     Creates a new `<gdk-window>' using the attributes from
     ATTRIBUTES.  See `<gdk-window-attr>' and
     `<gdk-window-attributes-type>' for more details. Note: to use
     this on displays other than the default display, PARENT must be
     specified.

    PARENT
          a `<gdk-window>', or ``#f'' to create the window as a child
          of the default root window for the default display.

    ATTRIBUTES
          attributes of the new window

    ATTRIBUTES-MASK
          mask indicating which fields in ATTRIBUTES are valid

    RET
          the new `<gdk-window>'



 -- Function: gdk-window-destroy (self `<gdk-window*>')
     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>')
     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*>')
     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*>')
     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*>')
     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')
     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')
     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>')
     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*>')
     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*>')
     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*>')
     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*>')
     "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*>')
     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*>')
     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*>')
     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*>')
     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*>')
     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')
     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')
     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')
     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')
     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')
     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')
     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')
     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')
     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*>')
     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')
     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')
     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*>')
     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*>')
     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')
     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*>')
     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')
     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')
     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-constrain-size (geometry `<gdk-geometry*>')
          (flags `unsigned-int') (width `int') (height `int') => 
          (new_width `int') (new_height `int')
     Constrains a desired width and height according to a set of
     geometry hints (such as minimum and maximum size).

    GEOMETRY
          a `<gdk-geometry>' structure

    FLAGS
          a mask indicating what portions of GEOMETRY are set

    WIDTH
          desired width of window

    HEIGHT
          desired height of the window

    NEW-WIDTH
          location to store resulting width

    NEW-HEIGHT
          location to store resulting height



 -- Function: gdk-window-begin-paint-rect (self `<gdk-window*>')
          (rectangle `<gdk-rectangle>')
     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*>')
     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*>')
     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')
     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')
     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*>')
     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*>')
     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*>')
     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')
     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-get-internal-paint-info
          (self `<gdk-window*>') (real_drawable `<gdk-drawable**>')
          =>  (x_offset `int') (y_offset `int')
     If you bypass the GDK layer and use windowing system primitives
     to draw directly onto a `<gdk-window>', then you need to deal
     with two details: there may be an offset between GDK coordinates
     and windowing system coordinates, and GDK may have redirected
     drawing to a offscreen pixmap as the result of a
     `gdk-window-begin-paint-region' calls. This function allows
     retrieving the information you need to compensate for these
     effects.

     This function exposes details of the GDK implementation, and is
     thus likely to change in future releases of GDK.

    WINDOW
          a `<gdk-window>'

    REAL-DRAWABLE
          location to store the drawable to which drawing should be
          done.

    X-OFFSET
          location to store the X offset between coordinates in
          WINDOW, and the underlying window system primitive
          coordinates for *REAL-DRAWABLE.

    Y-OFFSET
          location to store the Y offset between coordinates in
          WINDOW, and the underlying window system primitive
          coordinates for *REAL-DRAWABLE.



 -- Function: gdk-window-configure-finished (self `<gdk-window*>')
     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-user-data (self `<gdk-window*>')
          (user_data `<gpointer>')
     For most purposes this function is deprecated in favor of
     `g-object-set-data'. However, for historical reasons GTK+ stores
     the `<gtk-widget>' that owns a `<gdk-window>' as user data on the
     `<gdk-window>'. So, custom widget implementations should use
     this function for that. If GTK+ receives an event for a
     `<gdk-window>', and the user data for the window is non-``#f'',
     GTK+ will assume the user data is a `<gtk-widget>', and forward
     the event to that widget.

    WINDOW
          a `<gdk-window>'

    USER-DATA
          user data



 -- Function: gdk-window-set-override-redirect (self `<gdk-window*>')
          (override_redirect `bool')
     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')
     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')
     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-add-filter (self `<gdk-window*>')
          (function `<gdk-filter-func>') (data `<gpointer>')
     Adds an event filter to WINDOW, allowing you to intercept events
     before they reach GDK. This is a low-level operation and makes
     it easy to break GDK and/or GTK+, so you have to know what
     you're doing. Pass ``#f'' for WINDOW to get all events for all
     windows, instead of events for a specific window.

    WINDOW
          a `<gdk-window>'

    FUNCTION
          filter callback

    DATA
          data to pass to filter callback



 -- Function: gdk-window-remove-filter (self `<gdk-window*>')
          (function `<gdk-filter-func>') (data `<gpointer>')
     Remove a filter previously added with `gdk-window-add-filter'.

    WINDOW
          a `<gdk-window>'

    FUNCTION
          previously-added filter function

    DATA
          user data for previously-added filter function



 -- Function: gdk-window-shape-combine-mask (self `<gdk-window*>')
          (mask `<gdk-bitmap*>') (x `int') (y `int')
     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')
     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*>')
     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*>')
     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-bitmap*>') (x `int')
          (y `int')
     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*>')
     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*>')
     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')
     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')
     `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')
     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>')
     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')
     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>')
     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')
     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.

    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-geometry-hints (self `<gdk-window*>')
          (geometry `<gdk-geometry*>')
          (geom_mask `<gdk-window-hints>')
     Sets the geometry hints for WINDOW. Hints flagged in GEOM-MASK
     are set, hints not flagged in GEOM-MASK are unset. To unset all
     hints, use a GEOM-MASK of 0 and a GEOMETRY of ``#f''.

     This function provides hints to the windowing system about
     acceptable sizes for a toplevel window. The purpose of this is
     to constrain user resizing, but the windowing system will
     typically (but is not required to) also constrain the current
     size of the window to the provided values and constrain
     programatic resizing via `gdk-window-resize' or
     `gdk-window-move-resize'.

     Note that on X11, this effect has no effect on windows of type
     `GDK_WINDOW_TEMP' or windows where override redirect has been
     turned on via `gdk-window-set-override-redirect' since these
     windows are not resizable by the user.

     Since you can't count on the windowing system doing the
     constraints for programmatic resizes, you should generally call
     `gdk-window-constrain-size' yourself to determine appropriate
     sizes.

    WINDOW
          a toplevel `<gdk-window>'

    GEOMETRY
          geometry hints

    GEOM-MASK
          bitmask indicating fields of GEOMETRY to pay attention to



 -- Function: gdk-window-set-icon-list (self `<gdk-window*>')
          (pixbufs `glist-of')
     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')
     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>')
     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>')
     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')
     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')
     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')
     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')
     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')
     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-frame-extents (self `<gdk-window*>')
          (rect `<gdk-rectangle>')
     Obtains the bounding box of the window, including window manager
     titlebar/borders if any. The frame position is given in root
     window coordinates.  To get the position of the window itself
     (rather than the frame) in root window coordinates, use
     `gdk-window-get-origin'.

    WINDOW
          a toplevel `<gdk-window>'

    RECT
          rectangle to fill with bounding box of the window frame



 -- Function: gdk-window-get-origin (self `<gdk-window*>') => 
          (ret `int') (x `int') (y `int')
     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')
     `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-pointer (self `<gdk-window*>')
          (mask `<gdk-modifier-type*>') =>  (ret `<gdk-window*>')
          (x `int') (y `int')
     Obtains the current pointer position and modifier state. The
     position is given in coordinates relative to the upper left
     corner of WINDOW.

    WINDOW
          a `<gdk-window>'

    X
          return location for X coordinate of pointer

    Y
          return location for Y coordinate of pointer

    MASK
          return location for modifier mask

    RET
          the window containing the pointer (as with
          `gdk-window-at-pointer'), or ``#f'' if the window
          containing the pointer isn't known to GDK



 -- Function: gdk-window-get-parent (self `<gdk-window*>') => 
          (ret `<gdk-window*>')
     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*>')
     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')
     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>')
     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>')
     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-bitmap*>')
     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')
     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*>')
     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')
     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*>')
     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*>')
     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>')
     "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-get-decorations (self `<gdk-window*>')
          (decorations `<gdk-wm-decoration*>') =>  (ret `bool')
     Returns the decorations set on the GdkWindow with
     `<gdk-window-set-decorations>'

    WINDOW
          The toplevel `<gdk-window>' to get the decorations from

    DECORATIONS
          The window decorations will be written here

    RET
          TRUE if the window has decorations set, FALSE otherwise.



 -- Function: gdk-window-set-functions (self `<gdk-window*>')
          (functions `<gdk-wm-function>')
     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



 -- Function: gdk-set-pointer-hooks
          (new_hooks `<gdk-pointer-hooks*>') => 
          (ret `<gdk-pointer-hooks*>')
     This function allows for hooking into the operation of getting
     the current location of the pointer. This is only useful for
     such low-level tools as an event recorder. Applications should
     never have any reason to use this facility.

     This function is not multihead safe. For multihead operation, see
     `gdk-display-set-pointer-hooks'.

    NEW-HOOKS
          a table of pointers to functions for getting quantities
          related to the current pointer position, or ``#f'' to
          restore the default table.

    RET
          the previous pointer hook table




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-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-state (self `<gdk-event>')
          (state `<gdk-modifier-type*>') =>  (ret `bool')
     If the event contains a "state" field, puts that field in STATE.
     Otherwise stores an empty state (0). Returns ``#t'' if there was
     a state field in the event. EVENT may be ``#f'', in which case
     it's treated as if the event had no state field.

    EVENT
          a `<gdk-event>' or NULL

    STATE
          return location for state

    RET
          ``#t'' if there was a state field in the 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-event-handler-set (func `<gdk-event-func>')
          (data `<gpointer>') (notify `<g-destroy-notify>')
     Sets the function to call to handle all events from GDK.

     Note that GTK+ uses this to install its own event handler, so it
     is usually not useful for GTK+ applications. (Although an
     application can call this function then call `gtk-main-do-event'
     to pass events to GTK+.)

    FUNC
          the function to call to handle events from GDK.

    DATA
          user data to pass to the function.

    NOTIFY
          the function to call when the handler function is removed,
          i.e. when `gdk-event-handler-set' is called with another
          event handler.



 -- Function: gdk-add-client-message-filter
          (message_type `<gdk-atom>') (func `<gdk-filter-func>')
          (data `<gpointer>')
     Adds a filter to the default display to be called when X
     ClientMessage events are received. See
     `gdk-display-add-client-message-filter'.

    MESSAGE-TYPE
          the type of ClientMessage events to receive. This will be
          checked against the field of the XClientMessage event
          struct.

    FUNC
          the function to call to process the event.

    DATA
          user data to pass to FUNC.



 -- 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 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


 -- Function: gdk-setting-get (name `mchars') (value `<gvalue>') => 
          (ret `bool')
     Obtains a desktop-wide setting, such as the double-click time,
     for the default screen. See `gdk-screen-get-setting'.

    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.




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>

 -- Class: <gdk-event-key>

 -- Class: <gdk-event-button>

 -- Class: <gdk-event-scroll>

 -- Class: <gdk-event-motion>

 -- Class: <gdk-event-expose>

 -- Class: <gdk-event-visibility>

 -- Class: <gdk-event-crossing>

 -- Class: <gdk-event-focus>

 -- Class: <gdk-event-configure>

 -- Class: <gdk-event-property>

 -- Class: <gdk-event-selection>

 -- Class: <gdk-event-dnd>

 -- Class: <gdk-event-proximity>

 -- Class: <gdk-event-client>

 -- Class: <gdk-event-no-expose>

 -- Class: <gdk-event-window-state>

 -- Class: <gdk-event-setting>


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>
     This `<gobject>' 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-lookup-key (self `<gdk-keymap>')
          (key `<gdk-keymap-key*>') =>  (ret `unsigned-int')
 -- Method: lookup-key
     Looks up the keyval mapped to a keycode/group/level triplet. If
     no keyval is bound to KEY, returns 0. For normal user input, you
     want to use `gdk-keymap-translate-keyboard-state' instead of
     this function, since the effective group/level may not be the
     same as the current keyboard state.

    KEYMAP
          a `<gdk-keymap>' or ``#f'' to use the default keymap

    KEY
          a `<gdk-keymap-key>' with keycode, group, and level
          initialized

    RET
          a keyval, or 0 if none was mapped to the given KEY



 -- Function: gdk-keymap-translate-keyboard-state
          (self `<gdk-keymap>') (hardware_keycode `unsigned-int')
          (state `<gdk-modifier-type>') (group `int')
          (consumed_modifiers `<gdk-modifier-type*>') => 
          (ret `bool') (keyval `unsigned-int')
          (effective_group `int') (level `int')
 -- Method: translate-keyboard-state
     Translates the contents of a `<gdk-event-key>' into a keyval,
     effective group, and level. Modifiers that affected the
     translation and are thus unavailable for application use are
     returned in CONSUMED-MODIFIERS. See `gdk-keyval-get-keys' for an
     explanation of groups and levels. The EFFECTIVE-GROUP is the
     group that was actually used for the translation; some keys such
     as Enter are not affected by the active keyboard group. The
     LEVEL is derived from STATE. For convenience, `<gdk-event-key>'
     already contains the translated keyval, so this function isn't
     as useful as you might think.

     CONSUMED-MODIFIERS gives modifiers that should be masked out from
     STATE when comparing this key press to a hot key. For instance,
     on a US keyboard, the `plus' symbol is shifted, so when
     comparing a key press to a `<Control>plus' accelerator <Shift>
     should be masked out.


          /* We want to ignore irrelevant modifiers like ScrollLock */
          &#x0023;define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
          gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
                                               event->state, event->group,
                                               &keyval, NULL, NULL, &consumed);
          if (keyval == GDK_PLUS &&
              (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
            /* Control was pressed */

     An older interpretation CONSUMED-MODIFIERS was that it contained
     all modifiers that might affect the translation of the key; this
     allowed accelerators to be stored with irrelevant consumed
     modifiers, by doing:


          /* XXX Don't do this XXX */
          if (keyval == accel_keyval &&
              (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
            /* Accelerator was pressed */

     However, this did not work if multi-modifier combinations were
     used in the keymap, since, for instance, `<Control>' would be
     masked out even if only `<Control><Alt>' was used in the keymap.
     To support this usage as well as well as possible, all _single
     modifier_ combinations that could affect the key for any
     combination of modifiers will be returned in CONSUMED-MODIFIERS;
     multi-modifier combinations are returned only when actually
     found in STATE. When you store accelerators, you should always
     store them with consumed modifiers removed. Store
     `<Control>plus', not `<Control><Shift>plus',

    KEYMAP
          a `<gdk-keymap>', or ``#f'' to use the default

    HARDWARE-KEYCODE
          a keycode

    STATE
          a modifier state

    GROUP
          active keyboard group

    KEYVAL
          return location for keyval

    EFFECTIVE-GROUP
          return location for effective group

    LEVEL
          return location for level

    CONSUMED-MODIFIERS
          return location for modifiers that were used to determine
          the group or level

    RET
          ``#t'' if there was a keyval bound to the
          keycode/state/group



 -- Function: gdk-keymap-get-entries-for-keyval (self `<gdk-keymap>')
          (keyval `unsigned-int') (keys `<gdk-keymap-key**>') => 
          (ret `bool') (n_keys `int')
 -- Method: get-entries-for-keyval
     Obtains a list of keycode/group/level combinations that will
     generate KEYVAL. Groups and levels are two kinds of keyboard
     mode; in general, the level determines whether the top or bottom
     symbol on a key is used, and the group determines whether the
     left or right symbol is used. On US keyboards, the shift key
     changes the keyboard level, and there are no groups. A group
     switch key might convert a keyboard between Hebrew to English
     modes, for example.  `<gdk-event-key>' contains a `group' field
     that indicates the active keyboard group. The level is computed
     from the modifier mask. The returned array should be freed with
     `g-free'.

    KEYMAP
          a `<gdk-keymap>', or ``#f'' to use the default keymap

    KEYVAL
          a keyval, such as `GDK_a', `GDK_Up', `GDK_Return', etc.

    KEYS
          return location for an array of `<gdk-keymap-key>'

    N-KEYS
          return location for number of elements in returned array

    RET
          ``#t'' if keys were found and returned



 -- Function: gdk-keymap-get-entries-for-keycode
          (self `<gdk-keymap>') (hardware_keycode `unsigned-int')
          (keys `<gdk-keymap-key**>') (keyvals `<guint**>') => 
          (ret `bool') (n_entries `int')
 -- Method: get-entries-for-keycode
     Returns the keyvals bound to HARDWARE-KEYCODE. The Nth
     `<gdk-keymap-key>' in KEYS is bound to the Nth keyval in
     KEYVALS. Free the returned arrays with `g-free'. When a keycode
     is pressed by the user, the keyval from this list of entries is
     selected by considering the effective keyboard group and level.
     See `gdk-keymap-translate-keyboard-state'.

    KEYMAP
          a `<gdk-keymap>' or ``#f'' to use the default keymap

    HARDWARE-KEYCODE
          a keycode

    KEYS
          return location for array of `<gdk-keymap-key>', or NULL

    KEYVALS
          return location for array of keyvals, or NULL

    N-ENTRIES
          length of KEYS and KEYVALS

    RET
          ``#t'' if there were any entries



 -- 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-property-get (requestor `<gdk-window*>')
          (data `<guchar**>') (prop_type `<gdk-atom*>') => 
          (ret `bool') (prop_format `int')
     Retrieves selection data that was stored by the selection data
     in response to a call to `gdk-selection-convert'. This function
     will not be used by applications, who should use the
     `<gtk-clipboard>' API instead.

    REQUESTOR
          the window on which the data is stored

    DATA
          location to store a pointer to the retrieved data. If the
          retrieval failed, ``#f'' we be stored here, otherwise, it
          will be non-``#f'' and the returned data should be freed
          with `g-free' when you are finished using it. The length of
          the allocated memory is one more than the length of the
          returned data, and the final byte will always be zero, to
          ensure nul-termination of strings.

    PROP-TYPE
          location to store the type of the property.

    PROP-FORMAT
          location to store the format of the property.

    RET
          the length of the retrieved data.



 -- 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>
     This `<gobject>' 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-find-window (context `<gdk-drag-context>')
          (drag_window `<gdk-window*>') (x_root `int') (y_root `int')
          (dest_window `<gdk-window**>')
          (protocol `<gdk-drag-protocol*>')
     Finds the destination window and DND protocol to use at the
     given pointer position.

     This function is called by the drag source to obtain the
     DEST-WINDOW and PROTOCOL parameters for `gdk-drag-motion'.

    CONTEXT
          a `<gdk-drag-context>'.

    DRAG-WINDOW
          a window which may be at the pointer position, but should
          be ignored, since it is put up by the drag source as an
          icon.

    X-ROOT
          the x position of the pointer in root coordinates.

    Y-ROOT
          the y position of the pointer in root coordinates.

    DEST-WINDOW
          location to store the destination window in.

    PROTOCOL
          location to store the DND protocol in.



 -- Function: gdk-drag-find-window-for-screen
          (context `<gdk-drag-context>')
          (drag_window `<gdk-window*>') (screen `<gdk-screen>')
          (x_root `int') (y_root `int')
          (dest_window `<gdk-window**>')
          (protocol `<gdk-drag-protocol*>')
     Finds the destination window and DND protocol to use at the
     given pointer position.

     This function is called by the drag source to obtain the
     DEST-WINDOW and PROTOCOL parameters for `gdk-drag-motion'.

    CONTEXT
          a `<gdk-drag-context>'

    DRAG-WINDOW
          a window which may be at the pointer position, but should
          be ignored, since it is put up by the drag source as an
          icon.

    SCREEN
          the screen where the destination window is sought.

    X-ROOT
          the x position of the pointer in root coordinates.

    Y-ROOT
          the y position of the pointer in root coordinates.

    DEST-WINDOW
          location to store the destination window in.

    PROTOCOL
          location to store the DND protocol in.


     Since 2.2


 -- 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-get-protocol (xid `unsigned-int32')
          (protocol `<gdk-drag-protocol*>') =>  (ret `unsigned-int32')
     Finds out the DND protocol supported by a window.

    XID
          the X id of the destination window.

    PROTOCOL
          location where the supported DND protocol is returned.

    RET
          the X id of the window where the drop should happen. This
          may be XID or the X id of a proxy window, or None if XID
          doesn't support Drag and Drop.



 -- Function: gdk-drag-get-protocol-for-display
          (display `<gdk-display>') (xid `unsigned-int32')
          (protocol `<gdk-drag-protocol*>') =>  (ret `unsigned-int32')
     Finds out the DND protocol supported by a window.

    DISPLAY
          the `<gdk-display>' where the destination window resides

    XID
          the X id of the destination window.

    PROTOCOL
          location where the supported DND protocol is returned.

    RET
          the X id of the window where the drop should happen. This
          may be XID or the X id of a proxy window, or None if XID
          doesn't support Drag and Drop.


     Since 2.2


 -- 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>

 -- 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-get (window `<gdk-window*>')
          (property `<gdk-atom>') (type `<gdk-atom>')
          (offset `unsigned-long') (length `unsigned-long')
          (pdelete `int') (actual_property_type `<gdk-atom*>')
          (data `<guchar**>') =>  (ret `bool') (actual_format `int')
          (actual_length `int')
     Retrieves a portion of the contents of a property. If the
     property does not exist, then the function returns ``#f'', and
     `GDK_NONE' will be stored in ACTUAL-PROPERTY-TYPE.

     The `x-get-window-property' function that `gdk-property-get'
     uses has a very confusing and complicated set of semantics.
     Unfortunately, `gdk-property-get' makes the situation worse
     instead of better (the semantics should be considered
     undefined), and also prints warnings to stderr in cases where it
     should return a useful error to the program. You are advised to
     use `x-get-window-property' directly until a replacement
     function for `gdk-property-get' is provided.

    WINDOW
          a `<gdk-window>'.

    PROPERTY
          the property to retrieve.

    TYPE
          the desired property type, or `GDK_NONE', if any type of
          data is acceptable. If this does not match the actual type,
          then ACTUAL-FORMAT and ACTUAL-LENGTH will be filled in, a
          warning will be printed to stderr and no data will be
          returned.

    OFFSET
          the offset into the property at which to begin retrieving
          data, in 4 byte units.

    LENGTH
          the length of the data to retrieve in bytes. Data is
          considered to be retrieved in 4 byte chunks, so LENGTH will
          be rounded up to the next highest 4 byte boundary (so be
          careful not to pass a value that might overflow when rounded
          up).

    PDELETE
          if ``#t'', delete the property after retrieving the data.

    ACTUAL-PROPERTY-TYPE
          location to store the actual type of the property.

    ACTUAL-FORMAT
          location to store the actual return format of the data;
          either 8, 16 or 32 bits.

    ACTUAL-LENGTH
          location to store the length of the retrieved data, in
          bytes. Data returned in the 32 bit format is stored in a
          long variable, so the actual number of 32 bit elements
          should be be calculated via ACTUAL-LENGTH/sizeof(glong) to
          ensure portability to 64 bit systems.

    DATA
          location to store a pointer to the data. The retrieved data
          should be freed with `g-free' when you are finished using
          it.

    RET
          ``#t'' if data was sucessfully received and stored in DATA,
          otherwise ``#f''.



 -- Function: gdk-property-change (window `<gdk-window*>')
          (property `<gdk-atom>') (type `<gdk-atom>') (format `int')
          (mode `<gdk-prop-mode>') (data `<guchar*>')
          (nelements `int')
     Changes the contents of a property on a window.

    WINDOW
          a `<gdk-window>'.

    PROPERTY
          the property to change.

    TYPE
          the new type for the property. If MODE is
          `GDK_PROP_MODE_PREPEND' or `GDK_PROP_MODE_APPEND', then
          this must match the existing type or an error will occur.

    FORMAT
          the new format for the property. If MODE is
          `GDK_PROP_MODE_PREPEND' or `GDK_PROP_MODE_APPEND', then
          this must match the existing format or an error will occur.

    MODE
          a value describing how the new data is to be combined with
          the current data.

    DATA
          the data (a `guchar *'`gushort *', or `gulong *', depending
          on FORMAT), cast to a `guchar *'.

    NELEMENTS
          the number of elements of size determined by the format,
          contained in DATA.



 -- 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
==========

 -- 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>')
     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')
     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>')
     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>')
     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-state (self `<gdk-device*>')
          (window `<gdk-window*>') (mask `<gdk-modifier-type*>') => 
          (axes `double')
     Gets the current state of a device.

    DEVICE
          a `<gdk-device>'.

    WINDOW
          a `<gdk-window>'.

    AXES
          an array of doubles to store the values of the axes of
          DEVICE in, or ``#f''.

    MASK
          location to store the modifiers, or ``#f''.



 -- Function: gdk-device-get-history (self `<gdk-device*>')
          (window `<gdk-window*>') (start `unsigned-int32')
          (stop `unsigned-int32') (events `<gdk-time-coord***>') => 
          (ret `bool') (n_events `int')
     Obtains the motion history for a device; given a starting and
     ending timestamp, return all events in the motion history for
     the device in the given range of time. Some windowing systems do
     not support motion history, in which case, ``#f'' will be
     returned. (This is not distinguishable from the case where
     motion history is supported and no events were found.)

    DEVICE
          a `<gdk-device>'

    WINDOW
          the window with respect to which which the event
          coordinates will be reported

    START
          starting timestamp for range of events to return

    STOP
          ending timestamp for the range of events to return

    EVENTS
          location to store a newly-allocated array of
          `<gdk-time-coord>', or ``#f''

    N-EVENTS
          location to store the length of EVENTS, or ``#f''

    RET
          ``#t'' if the windowing system supports motion history and
          at least one event was found.



 -- Function: gdk-device-get-axis (self `<gdk-device*>')
          (use `<gdk-axis-use>') =>  (ret `bool') (axes `double')
          (value `double')
     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.



