<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gdk-General">
<refmeta>
<refentrytitle role="top_of_page" id="gdk-General.top_of_page">General</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>General</refname>
<refpurpose>Library initialization and miscellaneous functions</refpurpose>
</refnamediv>

<refsynopsisdiv id="gdk-General.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gdk/gdk.h&gt;

<link linkend="void">void</link>                <link linkend="gdk-init">gdk_init</link>                            (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);
<link linkend="gboolean">gboolean</link>            <link linkend="gdk-init-check">gdk_init_check</link>                      (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);
<link linkend="void">void</link>                <link linkend="gdk-parse-args">gdk_parse_args</link>                      (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);
const <link linkend="gchar">gchar</link>*        <link linkend="gdk-get-display-arg-name">gdk_get_display_arg_name</link>            (void);
<link linkend="gchar">gchar</link>*              <link linkend="gdk-set-locale">gdk_set_locale</link>                      (void);
<link linkend="void">void</link>                <link linkend="gdk-set-sm-client-id">gdk_set_sm_client_id</link>                (const <link linkend="gchar">gchar</link> *sm_client_id);
<link linkend="void">void</link>                <link linkend="gdk-exit">gdk_exit</link>                            (<link linkend="gint">gint</link> error_code);
<link linkend="void">void</link>                <link linkend="gdk-notify-startup-complete">gdk_notify_startup_complete</link>         (void);
<link linkend="void">void</link>                <link linkend="gdk-notify-startup-complete-with-id">gdk_notify_startup_complete_with_id</link> (const <link linkend="gchar">gchar</link> *startup_id);

const <link linkend="char">char</link> *        <link linkend="gdk-get-program-class">gdk_get_program_class</link>               (void);
<link linkend="void">void</link>                <link linkend="gdk-set-program-class">gdk_set_program_class</link>               (const <link linkend="char">char</link> *program_class);

<link linkend="gchar">gchar</link>*              <link linkend="gdk-get-display">gdk_get_display</link>                     (void);

<link linkend="void">void</link>                <link linkend="gdk-flush">gdk_flush</link>                           (void);

<link linkend="gint">gint</link>                <link linkend="gdk-screen-width">gdk_screen_width</link>                    (void);
<link linkend="gint">gint</link>                <link linkend="gdk-screen-height">gdk_screen_height</link>                   (void);
<link linkend="gint">gint</link>                <link linkend="gdk-screen-width-mm">gdk_screen_width_mm</link>                 (void);
<link linkend="gint">gint</link>                <link linkend="gdk-screen-height-mm">gdk_screen_height_mm</link>                (void);

<link linkend="GdkGrabStatus">GdkGrabStatus</link>       <link linkend="gdk-pointer-grab">gdk_pointer_grab</link>                    (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="gboolean">gboolean</link> owner_events,
                                                         <link linkend="GdkEventMask">GdkEventMask</link> event_mask,
                                                         <link linkend="GdkWindow">GdkWindow</link> *confine_to,
                                                         <link linkend="GdkCursor">GdkCursor</link> *cursor,
                                                         <link linkend="guint32">guint32</link> time_);
enum                <link linkend="GdkGrabStatus">GdkGrabStatus</link>;
<link linkend="void">void</link>                <link linkend="gdk-pointer-ungrab">gdk_pointer_ungrab</link>                  (<link linkend="guint32">guint32</link> time_);
<link linkend="gboolean">gboolean</link>            <link linkend="gdk-pointer-is-grabbed">gdk_pointer_is_grabbed</link>              (void);
<link linkend="void">void</link>                <link linkend="gdk-set-double-click-time">gdk_set_double_click_time</link>           (<link linkend="guint">guint</link> msec);

<link linkend="GdkGrabStatus">GdkGrabStatus</link>       <link linkend="gdk-keyboard-grab">gdk_keyboard_grab</link>                   (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="gboolean">gboolean</link> owner_events,
                                                         <link linkend="guint32">guint32</link> time_);
<link linkend="void">void</link>                <link linkend="gdk-keyboard-ungrab">gdk_keyboard_ungrab</link>                 (<link linkend="guint32">guint32</link> time_);

<link linkend="void">void</link>                <link linkend="gdk-beep">gdk_beep</link>                            (void);

<link linkend="gboolean">gboolean</link>            <link linkend="gdk-get-use-xshm">gdk_get_use_xshm</link>                    (void);
<link linkend="void">void</link>                <link linkend="gdk-set-use-xshm">gdk_set_use_xshm</link>                    (<link linkend="gboolean">gboolean</link> use_xshm);

<link linkend="void">void</link>                <link linkend="gdk-error-trap-push">gdk_error_trap_push</link>                 (void);
<link linkend="gint">gint</link>                <link linkend="gdk-error-trap-pop">gdk_error_trap_pop</link>                  (void);

#define             <link linkend="GDK-WINDOWING-X11--CAPS">GDK_WINDOWING_X11</link>
#define             <link linkend="GDK-WINDOWING-WIN32--CAPS">GDK_WINDOWING_WIN32</link>
</synopsis>
</refsynopsisdiv>









<refsect1 id="gdk-General.description" role="desc">
<title role="desc.title">Description</title>
<para>
This section describes the GDK initialization functions and miscellaneous
utility functions.
</para>
</refsect1>

<refsect1 id="gdk-General.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="gdk-init" role="function">
<title>gdk_init ()</title>
<indexterm zone="gdk-init"><primary sortas="init">gdk_init</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_init                            (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);</programlisting>
<para>
Initializes the GDK library and connects to the X server.
If initialization fails, a warning message is output and the application
terminates with a call to <literal>exit(1)</literal>.
</para>
<para>
Any arguments used by GDK are removed from the array and <parameter>argc</parameter> and <parameter>argv</parameter> are
updated accordingly.
</para>
<para>
GTK+ initializes GDK in <link linkend="gtk-init"><function>gtk_init()</function></link> and so this function is not usually needed
by GTK+ applications.
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara>the number of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara>the array of command line arguments.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-init-check" role="function">
<title>gdk_init_check ()</title>
<indexterm zone="gdk-init-check"><primary sortas="init_check">gdk_init_check</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_init_check                      (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);</programlisting>
<para>
Initializes the GDK library and connects to the X server, returning <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on
success.
</para>
<para>
Any arguments used by GDK are removed from the array and <parameter>argc</parameter> and <parameter>argv</parameter> are
updated accordingly.
</para>
<para>
GTK+ initializes GDK in <link linkend="gtk-init"><function>gtk_init()</function></link> and so this function is not usually needed
by GTK+ applications.
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara>the number of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara>the array of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if initialization succeeded.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-parse-args" role="function" condition="since:2.2">
<title>gdk_parse_args ()</title>
<indexterm zone="gdk-parse-args" role="2.2"><primary sortas="parse_args">gdk_parse_args</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_parse_args                      (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);</programlisting>
<para>
Parse command line arguments, and store for future
use by calls to <link linkend="gdk-display-open"><function>gdk_display_open()</function></link>.
</para>
<para>
Any arguments used by GDK are removed from the array and <parameter>argc</parameter> and <parameter>argv</parameter> are
updated accordingly.
</para>
<para>
You shouldn't call this function explicitely if you are using
<link linkend="gtk-init"><function>gtk_init()</function></link>, <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>, <link linkend="gdk-init"><function>gdk_init()</function></link>, or <link linkend="gdk-init-check"><function>gdk_init_check()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara> the number of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara> the array of command line arguments.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-get-display-arg-name" role="function" condition="since:2.2">
<title>gdk_get_display_arg_name ()</title>
<indexterm zone="gdk-get-display-arg-name" role="2.2"><primary sortas="get_display_arg_name">gdk_get_display_arg_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        gdk_get_display_arg_name            (void);</programlisting>
<para>
Gets the display name specified in the command line arguments passed
to <link linkend="gdk-init"><function>gdk_init()</function></link> or <link linkend="gdk-parse-args"><function>gdk_parse_args()</function></link>, if any.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the display name, if specified explicitely, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>
  this string is owned by GTK+ and must not be modified or freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-set-locale" role="function">
<title>gdk_set_locale ()</title>
<indexterm zone="gdk-set-locale"><primary sortas="set_locale">gdk_set_locale</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gdk_set_locale                      (void);</programlisting>
<para>
Initializes the support for internationalization by calling the <function><link linkend="setlocale"><function>setlocale()</function></link></function>
system call. This function is called by <link linkend="gtk-set-locale"><function>gtk_set_locale()</function></link> and so GTK+
applications should use that instead.
</para>
<para>
The locale to use is determined by the <envar>LANG</envar> environment variable,
so to run an application in a certain locale you can do something like this:
<informalexample>
<programlisting>
  export LANG="fr"
  ... run application ...
</programlisting>
</informalexample>
</para>
<para>
If the locale is not supported by X then it is reset to the standard "C"
locale.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the resulting locale.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-set-sm-client-id" role="function">
<title>gdk_set_sm_client_id ()</title>
<indexterm zone="gdk-set-sm-client-id"><primary sortas="set_sm_client_id">gdk_set_sm_client_id</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_set_sm_client_id                (const <link linkend="gchar">gchar</link> *sm_client_id);</programlisting>
<para>
Sets the <literal>SM_CLIENT_ID</literal> 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.
</para>
<para>
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 <literal>WM_CLIENT_LEADER</literal> property. 
(Both documents are part of the X Window System distribution.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sm_client_id</parameter>&#160;:</term>
<listitem><simpara> the client id assigned by the session manager when the
   connection was opened, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to remove the property.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-exit" role="function" condition="deprecated:">
<title>gdk_exit ()</title>
<indexterm zone="gdk-exit" role="deprecated"><primary sortas="exit">gdk_exit</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_exit                            (<link linkend="gint">gint</link> error_code);</programlisting>
<warning><para><literal>gdk_exit</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Exits the application using the <function><link linkend="exit"><function>exit()</function></link></function> system call.
</para>
<para>
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 <link linkend="g-atexit"><function>g_atexit()</function></link>).
</para><variablelist role="params">
<varlistentry><term><parameter>error_code</parameter>&#160;:</term>
<listitem><simpara>the error code to pass to the <function><link linkend="exit"><function>exit()</function></link></function> call.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-notify-startup-complete" role="function" condition="since:2.2">
<title>gdk_notify_startup_complete ()</title>
<indexterm zone="gdk-notify-startup-complete" role="2.2"><primary sortas="notify_startup_complete">gdk_notify_startup_complete</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_notify_startup_complete         (void);</programlisting>
<para>
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.
</para>
<para>
GTK+ will call this function automatically after opening the first
<link linkend="GtkWindow"><type>GtkWindow</type></link> unless <link linkend="gtk-window-set-auto-startup-notification"><function>gtk_window_set_auto_startup_notification()</function></link> is called 
to disable that feature.</para>
<para>
</para><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gdk-notify-startup-complete-with-id" role="function" condition="since:2.12">
<title>gdk_notify_startup_complete_with_id ()</title>
<indexterm zone="gdk-notify-startup-complete-with-id" role="2.12"><primary sortas="notify_startup_complete_with_id">gdk_notify_startup_complete_with_id</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_notify_startup_complete_with_id (const <link linkend="gchar">gchar</link> *startup_id);</programlisting>
<para>
Indicates to the GUI environment that the application has finished
loading, using a given identifier.
</para>
<para>
GTK+ will call this function automatically for <link linkend="GtkWindow"><type>GtkWindow</type></link> with custom
startup-notification identifier unless
<link linkend="gtk-window-set-auto-startup-notification"><function>gtk_window_set_auto_startup_notification()</function></link> is called to disable
that feature.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>startup_id</parameter>&#160;:</term>
<listitem><simpara> a startup-notification identifier, for which notification
             process should be completed
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="gdk-get-program-class" role="function">
<title>gdk_get_program_class ()</title>
<indexterm zone="gdk-get-program-class"><primary sortas="get_program_class">gdk_get_program_class</primary></indexterm><programlisting>const <link linkend="char">char</link> *        gdk_get_program_class               (void);</programlisting>
<para>
Gets the program class. Unless the program class has explicitly
been set with <link linkend="gdk-set-program-class"><function>gdk_set_program_class()</function></link> or with the <option>--class</option>
commandline option, the default value is the program name (determined
with <link linkend="g-get-prgname"><function>g_get_prgname()</function></link>) with the first character converted to uppercase.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the program class.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-set-program-class" role="function">
<title>gdk_set_program_class ()</title>
<indexterm zone="gdk-set-program-class"><primary sortas="set_program_class">gdk_set_program_class</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_set_program_class               (const <link linkend="char">char</link> *program_class);</programlisting>
<para>
Sets the program class. The X11 backend uses the program class to set
the class name part of the <literal>WM_CLASS</literal> property on
toplevel windows; see the ICCCM.
</para><variablelist role="params">
<varlistentry><term><parameter>program_class</parameter>&#160;:</term>
<listitem><simpara>a string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-get-display" role="function">
<title>gdk_get_display ()</title>
<indexterm zone="gdk-get-display"><primary sortas="get_display">gdk_get_display</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gdk_get_display                     (void);</programlisting>
<para>
Gets the name of the display, which usually comes from the <envar>DISPLAY</envar>
environment variable or the <option>--display</option> command line option.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the name of the display.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-flush" role="function">
<title>gdk_flush ()</title>
<indexterm zone="gdk-flush"><primary sortas="flush">gdk_flush</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_flush                           (void);</programlisting>
<para>
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 <link linkend="gdk-error-trap-push"><function>gdk_error_trap_push()</function></link> and <link linkend="gdk-error-trap-pop"><function>gdk_error_trap_pop()</function></link>.
</para></refsect2>
<refsect2 id="gdk-screen-width" role="function">
<title>gdk_screen_width ()</title>
<indexterm zone="gdk-screen-width"><primary sortas="screen_width">gdk_screen_width</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_screen_width                    (void);</programlisting>
<para>
Returns the width of the default screen in pixels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the width of the default screen in pixels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-screen-height" role="function">
<title>gdk_screen_height ()</title>
<indexterm zone="gdk-screen-height"><primary sortas="screen_height">gdk_screen_height</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_screen_height                   (void);</programlisting>
<para>
Returns the height of the default screen in pixels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the height of the default screen in pixels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-screen-width-mm" role="function">
<title>gdk_screen_width_mm ()</title>
<indexterm zone="gdk-screen-width-mm"><primary sortas="screen_width_mm">gdk_screen_width_mm</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_screen_width_mm                 (void);</programlisting>
<para>
Returns the width of the default screen in millimeters.
Note that on many X servers this value will not be correct.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the width of the default screen in millimeters,
though it is not always correct.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-screen-height-mm" role="function">
<title>gdk_screen_height_mm ()</title>
<indexterm zone="gdk-screen-height-mm"><primary sortas="screen_height_mm">gdk_screen_height_mm</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_screen_height_mm                (void);</programlisting>
<para>
Returns the height of the default screen in millimeters.
Note that on many X servers this value will not be correct.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the height of the default screen in millimeters,
though it is not always correct.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-pointer-grab" role="function">
<title>gdk_pointer_grab ()</title>
<indexterm zone="gdk-pointer-grab"><primary sortas="pointer_grab">gdk_pointer_grab</primary></indexterm><programlisting><link linkend="GdkGrabStatus">GdkGrabStatus</link>       gdk_pointer_grab                    (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="gboolean">gboolean</link> owner_events,
                                                         <link linkend="GdkEventMask">GdkEventMask</link> event_mask,
                                                         <link linkend="GdkWindow">GdkWindow</link> *confine_to,
                                                         <link linkend="GdkCursor">GdkCursor</link> *cursor,
                                                         <link linkend="guint32">guint32</link> time_);</programlisting>
<para>
Grabs the pointer (usually a mouse) so that all events are passed to this
application until the pointer is ungrabbed with <link linkend="gdk-pointer-ungrab"><function>gdk_pointer_ungrab()</function></link>, or
the grab window becomes unviewable.
This overrides any previous pointer grab by this client.
</para>
<para>
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 <link linkend="GtkHPaned"><type>GtkHPaned</type></link> and <link linkend="GtkVPaned"><type>GtkVPaned</type></link> widgets, and for resizing columns in <link linkend="GtkCList"><type>GtkCList</type></link>
widgets.
</para>
<para>
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 <parameter>owner_events</parameter> set to
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.
</para>
<para>
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 <link linkend="GdkEventGrabBroken"><type>GdkEventGrabBroken</type></link> events that
are emitted when the grab ends unvoluntarily.
</para><variablelist role="params">
<varlistentry><term><parameter>window</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GdkWindow"><type>GdkWindow</type></link> which will own the grab (the grab window).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>owner_events</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> then all pointer events are reported with respect to
<parameter>window</parameter> and are only reported if selected by <parameter>event_mask</parameter>. If <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> then pointer
events for this application are reported as normal, but pointer events outside
this application are reported with respect to <parameter>window</parameter> and only if selected by
<parameter>event_mask</parameter>. In either mode, unreported events are discarded.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event_mask</parameter>&#160;:</term>
<listitem><simpara>specifies the event mask, which is used in accordance with
<parameter>owner_events</parameter>. Note that only pointer events (i.e. button and motion events)
    may be selected.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>confine_to</parameter>&#160;:</term>
<listitem><simpara>If non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, the pointer will be confined to this
window during the grab. If the pointer is outside <parameter>confine_to</parameter>, it will
automatically be moved to the closest edge of <parameter>confine_to</parameter> and enter
and leave events will be generated as necessary.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cursor</parameter>&#160;:</term>
<listitem><simpara>the cursor to display while the grab is active. If this is <link linkend="NULL--CAPS"><literal>NULL</literal></link> then
the normal cursors are used for <parameter>window</parameter> and its descendants, and the cursor
for <parameter>window</parameter> is used for all other windows.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>time_</parameter>&#160;:</term>
<listitem><simpara>the timestamp of the event which led to this pointer grab. This usually
comes from a <link linkend="GdkEventButton"><type>GdkEventButton</type></link> struct, though <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link> can be used if
the time isn't known.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%GDK_GRAB_SUCCESS if the grab was successful.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GdkGrabStatus" role="enum">
<title>enum GdkGrabStatus</title>
<indexterm zone="GdkGrabStatus"><primary sortas="GrabStatus">GdkGrabStatus</primary></indexterm><programlisting>typedef enum
{
  GDK_GRAB_SUCCESS         = 0,
  GDK_GRAB_ALREADY_GRABBED = 1,
  GDK_GRAB_INVALID_TIME    = 2,
  GDK_GRAB_NOT_VIEWABLE    = 3,
  GDK_GRAB_FROZEN          = 4
} GdkGrabStatus;
</programlisting>
<para>
Returned by <link linkend="gdk-pointer-grab"><function>gdk_pointer_grab()</function></link> and <link linkend="gdk-keyboard-grab"><function>gdk_keyboard_grab()</function></link> to indicate
success or the reason for the failure of the grab attempt.
</para><variablelist role="enum">
<varlistentry id="GDK-GRAB-SUCCESS--CAPS" role="constant">
<term><literal>GDK_GRAB_SUCCESS</literal></term>
<listitem><simpara>the resource was successfully grabbed.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-GRAB-ALREADY-GRABBED--CAPS" role="constant">
<term><literal>GDK_GRAB_ALREADY_GRABBED</literal></term>
<listitem><simpara>the resource is actively grabbed by another client.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-GRAB-INVALID-TIME--CAPS" role="constant">
<term><literal>GDK_GRAB_INVALID_TIME</literal></term>
<listitem><simpara>the resource was grabbed more recently than the 
  specified time.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-GRAB-NOT-VIEWABLE--CAPS" role="constant">
<term><literal>GDK_GRAB_NOT_VIEWABLE</literal></term>
<listitem><simpara>the grab window or the <parameter>confine_to</parameter> window are not
  viewable.
</simpara></listitem>
</varlistentry>
<varlistentry id="GDK-GRAB-FROZEN--CAPS" role="constant">
<term><literal>GDK_GRAB_FROZEN</literal></term>
<listitem><simpara>the resource is frozen by an active grab of another client.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-pointer-ungrab" role="function">
<title>gdk_pointer_ungrab ()</title>
<indexterm zone="gdk-pointer-ungrab"><primary sortas="pointer_ungrab">gdk_pointer_ungrab</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_pointer_ungrab                  (<link linkend="guint32">guint32</link> time_);</programlisting>
<para>
Ungrabs the pointer on the default display, if it is grabbed by this 
application.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>time_</parameter>&#160;:</term>
<listitem><simpara> a timestamp from a <link linkend="GdkEvent"><type>GdkEvent</type></link>, or <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link> if no 
 timestamp is available.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-pointer-is-grabbed" role="function">
<title>gdk_pointer_is_grabbed ()</title>
<indexterm zone="gdk-pointer-is-grabbed"><primary sortas="pointer_is_grabbed">gdk_pointer_is_grabbed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_pointer_is_grabbed              (void);</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the pointer on the default display is currently 
grabbed by this application.
</para>
<para>
Note that this does not take the inmplicit pointer grab on button
presses into account.</para>
<para>
</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the pointer is currently grabbed by this application.* 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-set-double-click-time" role="function">
<title>gdk_set_double_click_time ()</title>
<indexterm zone="gdk-set-double-click-time"><primary sortas="set_double_click_time">gdk_set_double_click_time</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_set_double_click_time           (<link linkend="guint">guint</link> msec);</programlisting>
<para>
Set the double click time for the default display. See
<link linkend="gdk-display-set-double-click-time"><function>gdk_display_set_double_click_time()</function></link>. 
See also <link linkend="gdk-display-set-double-click-distance"><function>gdk_display_set_double_click_distance()</function></link>.
Applications should <emphasis>not</emphasis> set this, it is a 
global user-configured setting.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>msec</parameter>&#160;:</term>
<listitem><simpara> double click time in milliseconds (thousandths of a second)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-keyboard-grab" role="function">
<title>gdk_keyboard_grab ()</title>
<indexterm zone="gdk-keyboard-grab"><primary sortas="keyboard_grab">gdk_keyboard_grab</primary></indexterm><programlisting><link linkend="GdkGrabStatus">GdkGrabStatus</link>       gdk_keyboard_grab                   (<link linkend="GdkWindow">GdkWindow</link> *window,
                                                         <link linkend="gboolean">gboolean</link> owner_events,
                                                         <link linkend="guint32">guint32</link> time_);</programlisting>
<para>
Grabs the keyboard so that all events are passed to this
application until the keyboard is ungrabbed with <link linkend="gdk-keyboard-ungrab"><function>gdk_keyboard_ungrab()</function></link>.
This overrides any previous keyboard grab by this client.
</para>
<para>
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 <link linkend="GdkEventGrabBroken"><type>GdkEventGrabBroken</type></link> events that
are emitted when the grab ends unvoluntarily.
</para><variablelist role="params">
<varlistentry><term><parameter>window</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GdkWindow"><type>GdkWindow</type></link> which will own the grab (the grab window).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>owner_events</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> then all keyboard events are reported with respect to
<parameter>window</parameter>. If <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> then keyboard events for this application are reported as
normal, but keyboard events outside this application are reported with respect
to <parameter>window</parameter>. Both key press and key release events are always reported,
independant of the event mask set by the application.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>time_</parameter>&#160;:</term>
<listitem><simpara>a timestamp from a <link linkend="GdkEvent"><type>GdkEvent</type></link>, or <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link> if no timestamp is
available.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%GDK_GRAB_SUCCESS if the grab was successful.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-keyboard-ungrab" role="function">
<title>gdk_keyboard_ungrab ()</title>
<indexterm zone="gdk-keyboard-ungrab"><primary sortas="keyboard_ungrab">gdk_keyboard_ungrab</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_keyboard_ungrab                 (<link linkend="guint32">guint32</link> time_);</programlisting>
<para>
Ungrabs the keyboard on the default display, if it is grabbed by this 
application.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>time_</parameter>&#160;:</term>
<listitem><simpara> a timestamp from a <link linkend="GdkEvent"><type>GdkEvent</type></link>, or <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link> if no
       timestamp is available.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-beep" role="function">
<title>gdk_beep ()</title>
<indexterm zone="gdk-beep"><primary sortas="beep">gdk_beep</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_beep                            (void);</programlisting>
<para>
Emits a short beep on the default display.</para>
<para>
</para></refsect2>
<refsect2 id="gdk-get-use-xshm" role="function" condition="deprecated:">
<title>gdk_get_use_xshm ()</title>
<indexterm zone="gdk-get-use-xshm" role="deprecated"><primary sortas="get_use_xshm">gdk_get_use_xshm</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gdk_get_use_xshm                    (void);</programlisting>
<warning><para><literal>gdk_get_use_xshm</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if GDK will attempt to use the MIT-SHM shared memory extension.
</para>
<para>
The shared memory extension is used for <link linkend="GdkImage"><type>GdkImage</type></link>, and consequently for
<link linkend="gdk-GdkRGB">GdkRGB</link>.
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.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if use of the MIT shared memory extension will be attempted.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-set-use-xshm" role="function" condition="deprecated:">
<title>gdk_set_use_xshm ()</title>
<indexterm zone="gdk-set-use-xshm" role="deprecated"><primary sortas="set_use_xshm">gdk_set_use_xshm</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_set_use_xshm                    (<link linkend="gboolean">gboolean</link> use_xshm);</programlisting>
<warning><para><literal>gdk_set_use_xshm</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, since if it is set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> and the server does not
support the extension it may cause warning messages to be output.
</para><variablelist role="params">
<varlistentry><term><parameter>use_xshm</parameter>&#160;:</term>
<listitem><simpara>%TRUE if use of the MIT shared memory extension should be attempted.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-error-trap-push" role="function">
<title>gdk_error_trap_push ()</title>
<indexterm zone="gdk-error-trap-push"><primary sortas="error_trap_push">gdk_error_trap_push</primary></indexterm><programlisting><link linkend="void">void</link>                gdk_error_trap_push                 (void);</programlisting>
<para>
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.
</para>
<example>
<title>Trapping an X error</title>
<programlisting>
  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 ... */
    }
</programlisting>
</example></refsect2>
<refsect2 id="gdk-error-trap-pop" role="function">
<title>gdk_error_trap_pop ()</title>
<indexterm zone="gdk-error-trap-pop"><primary sortas="error_trap_pop">gdk_error_trap_pop</primary></indexterm><programlisting><link linkend="gint">gint</link>                gdk_error_trap_pop                  (void);</programlisting>
<para>
Removes the X error trap installed with <link linkend="gdk-error-trap-push"><function>gdk_error_trap_push()</function></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the X error code, or 0 if no error occurred.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GDK-WINDOWING-X11--CAPS" role="macro">
<title>GDK_WINDOWING_X11</title>
<indexterm zone="GDK-WINDOWING-X11--CAPS"><primary sortas="WINDOWING_X11">GDK_WINDOWING_X11</primary></indexterm><programlisting>#define GDK_WINDOWING_X11
</programlisting>
<para>
This macro is defined if GDK is configured to use the X backend.
</para></refsect2>
<refsect2 id="GDK-WINDOWING-WIN32--CAPS" role="macro">
<title>GDK_WINDOWING_WIN32</title>
<indexterm zone="GDK-WINDOWING-WIN32--CAPS"><primary sortas="WINDOWING_WIN32">GDK_WINDOWING_WIN32</primary></indexterm><programlisting>#define GDK_WINDOWING_WIN32
</programlisting>
<para>
This macro is defined if GDK is configured to use the Win32 backend.
</para></refsect2>

</refsect1>




</refentry>
