<?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">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="gtk-General">
<refmeta>
<refentrytitle role="top_of_page" id="gtk-General.top_of_page">Main loop and Events</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Main loop and Events</refname>
<refpurpose>Library initialization, main event loop, and events</refpurpose>
</refnamediv>

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

<synopsis>

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

<link linkend="gchar">gchar</link> *             <link linkend="gtk-set-locale">gtk_set_locale</link>                      (void);
<link linkend="void">void</link>                <link linkend="gtk-disable-setlocale">gtk_disable_setlocale</link>               (void);
<link linkend="PangoLanguage">PangoLanguage</link> *     <link linkend="gtk-get-default-language">gtk_get_default_language</link>            (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-parse-args">gtk_parse_args</link>                      (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);
<link linkend="void">void</link>                <link linkend="gtk-init">gtk_init</link>                            (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-init-check">gtk_init_check</link>                      (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-init-with-args">gtk_init_with_args</link>                  (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv,
                                                         <link linkend="char">char</link> *parameter_string,
                                                         <link linkend="GOptionEntry">GOptionEntry</link> *entries,
                                                         <link linkend="char">char</link> *translation_domain,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GOptionGroup">GOptionGroup</link> *      <link linkend="gtk-get-option-group">gtk_get_option_group</link>                (<link linkend="gboolean">gboolean</link> open_default_display);
<link linkend="void">void</link>                <link linkend="gtk-exit">gtk_exit</link>                            (<link linkend="gint">gint</link> error_code);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-events-pending">gtk_events_pending</link>                  (void);
<link linkend="void">void</link>                <link linkend="gtk-main">gtk_main</link>                            (void);
<link linkend="guint">guint</link>               <link linkend="gtk-main-level">gtk_main_level</link>                      (void);
<link linkend="void">void</link>                <link linkend="gtk-main-quit">gtk_main_quit</link>                       (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-main-iteration">gtk_main_iteration</link>                  (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-main-iteration-do">gtk_main_iteration_do</link>               (<link linkend="gboolean">gboolean</link> blocking);
<link linkend="void">void</link>                <link linkend="gtk-main-do-event">gtk_main_do_event</link>                   (<link linkend="GdkEvent">GdkEvent</link> *event);
<link linkend="void">void</link>                (<link linkend="GtkModuleInitFunc">*GtkModuleInitFunc</link>)                (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);
<link linkend="void">void</link>                (<link linkend="GtkModuleDisplayInitFunc">*GtkModuleDisplayInitFunc</link>)         (<link linkend="GdkDisplay">GdkDisplay</link> *display);

<link linkend="gboolean">gboolean</link>            <link linkend="gtk-true">gtk_true</link>                            (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-false">gtk_false</link>                           (void);

<link linkend="void">void</link>                <link linkend="gtk-grab-add">gtk_grab_add</link>                        (<link linkend="GtkWidget">GtkWidget</link> *widget);
<link linkend="GtkWidget">GtkWidget</link>*          <link linkend="gtk-grab-get-current">gtk_grab_get_current</link>                (void);
<link linkend="void">void</link>                <link linkend="gtk-grab-remove">gtk_grab_remove</link>                     (<link linkend="GtkWidget">GtkWidget</link> *widget);

<link linkend="void">void</link>                <link linkend="gtk-init-add">gtk_init_add</link>                        (<link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="gtk-quit-add-destroy">gtk_quit_add_destroy</link>                (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkObject">GtkObject</link> *object);
<link linkend="guint">guint</link>               <link linkend="gtk-quit-add">gtk_quit_add</link>                        (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>               <link linkend="gtk-quit-add-full">gtk_quit_add_full</link>                   (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="void">void</link>                <link linkend="gtk-quit-remove">gtk_quit_remove</link>                     (<link linkend="guint">guint</link> quit_handler_id);
<link linkend="void">void</link>                <link linkend="gtk-quit-remove-by-data">gtk_quit_remove_by_data</link>             (<link linkend="gpointer">gpointer</link> data);

<link linkend="guint">guint</link>               <link linkend="gtk-timeout-add-full">gtk_timeout_add_full</link>                (<link linkend="guint32">guint32</link> interval,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="guint">guint</link>               <link linkend="gtk-timeout-add">gtk_timeout_add</link>                     (<link linkend="guint32">guint32</link> interval,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="gtk-timeout-remove">gtk_timeout_remove</link>                  (<link linkend="guint">guint</link> timeout_handler_id);

<link linkend="guint">guint</link>               <link linkend="gtk-idle-add">gtk_idle_add</link>                        (<link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>               <link linkend="gtk-idle-add-priority">gtk_idle_add_priority</link>               (<link linkend="gint">gint</link> priority,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>               <link linkend="gtk-idle-add-full">gtk_idle_add_full</link>                   (<link linkend="gint">gint</link> priority,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="void">void</link>                <link linkend="gtk-idle-remove">gtk_idle_remove</link>                     (<link linkend="guint">guint</link> idle_handler_id);
<link linkend="void">void</link>                <link linkend="gtk-idle-remove-by-data">gtk_idle_remove_by_data</link>             (<link linkend="gpointer">gpointer</link> data);

<link linkend="guint">guint</link>               <link linkend="gtk-input-add-full">gtk_input_add_full</link>                  (<link linkend="gint">gint</link> source,
                                                         <link linkend="GdkInputCondition">GdkInputCondition</link> condition,
                                                         <link linkend="GdkInputFunction">GdkInputFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="void">void</link>                <link linkend="gtk-input-remove">gtk_input_remove</link>                    (<link linkend="guint">guint</link> input_handler_id);

#define             <link linkend="GTK-PRIORITY-REDRAW--CAPS">GTK_PRIORITY_REDRAW</link>
#define             <link linkend="GTK-PRIORITY-RESIZE--CAPS">GTK_PRIORITY_RESIZE</link>
#define             <link linkend="GTK-PRIORITY-HIGH--CAPS">GTK_PRIORITY_HIGH</link>
#define             <link linkend="GTK-PRIORITY-INTERNAL--CAPS">GTK_PRIORITY_INTERNAL</link>
#define             <link linkend="GTK-PRIORITY-DEFAULT--CAPS">GTK_PRIORITY_DEFAULT</link>
#define             <link linkend="GTK-PRIORITY-LOW--CAPS">GTK_PRIORITY_LOW</link>

<link linkend="guint">guint</link>               <link linkend="gtk-key-snooper-install">gtk_key_snooper_install</link>             (<link linkend="GtkKeySnoopFunc">GtkKeySnoopFunc</link> snooper,
                                                         <link linkend="gpointer">gpointer</link> func_data);
<link linkend="gint">gint</link>                (<link linkend="GtkKeySnoopFunc">*GtkKeySnoopFunc</link>)                  (<link linkend="GtkWidget">GtkWidget</link> *grab_widget,
                                                         <link linkend="GdkEventKey">GdkEventKey</link> *event,
                                                         <link linkend="gpointer">gpointer</link> func_data);
<link linkend="void">void</link>                <link linkend="gtk-key-snooper-remove">gtk_key_snooper_remove</link>              (<link linkend="guint">guint</link> snooper_handler_id);

<link linkend="GdkEvent">GdkEvent</link>*           <link linkend="gtk-get-current-event">gtk_get_current_event</link>               (void);
<link linkend="guint32">guint32</link>             <link linkend="gtk-get-current-event-time">gtk_get_current_event_time</link>          (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-get-current-event-state">gtk_get_current_event_state</link>         (<link linkend="GdkModifierType">GdkModifierType</link> *state);
<link linkend="GtkWidget">GtkWidget</link>*          <link linkend="gtk-get-event-widget">gtk_get_event_widget</link>                (<link linkend="GdkEvent">GdkEvent</link> *event);
<link linkend="void">void</link>                <link linkend="gtk-propagate-event">gtk_propagate_event</link>                 (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                                         <link linkend="GdkEvent">GdkEvent</link> *event);
</synopsis>
</refsynopsisdiv>









<refsect1 id="gtk-General.description" role="desc">
<title role="desc.title">Description</title>
<para>
Before using GTK+, you need to initialize it; initialization connects
to the window system display, and parses some standard command line
arguments. The <link linkend="gtk-init"><function>gtk_init()</function></link> function initializes GTK+. <link linkend="gtk-init"><function>gtk_init()</function></link> exits
the application if errors occur; to avoid this, use <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>.
<link linkend="gtk-init-check"><function>gtk_init_check()</function></link> allows you to recover from a failed GTK+
initialization - you might start up your application in text mode instead.
</para>
<para>
Like all GUI toolkits, GTK+ uses an event-driven programming
model. When the user is doing nothing, GTK+ sits in the
<firstterm>main loop</firstterm> and waits for input. If the user
performs some action - say, a mouse click - then the main loop "wakes
up" and delivers an event to GTK+. GTK+ forwards the event to one or
more widgets.
</para>
<para>
When widgets receive an event, they frequently emit one or more
<firstterm>signals</firstterm>. Signals notify your program that
"something interesting happened" by invoking functions you've
connected to the signal with <link linkend="g-signal-connect"><function>g_signal_connect()</function></link>. Functions connected
to a signal are often termed <firstterm>callbacks</firstterm>.
</para>
<para>
When your callbacks are invoked, you would typically take some action
- for example, when an Open button is clicked you might display a
<link linkend="GtkFileSelectionDialog"><type>GtkFileSelectionDialog</type></link>. After a callback finishes, GTK+ will return
to the main loop and await more user input.
</para>
<example>
<title>Typical <function>main</function> function for a GTK+ application</title>
<programlisting>
int
main (int argc, char **argv)
{
  /* Initialize i18n support */
  gtk_set_locale (<!-- -->);
  /* Initialize the widget set */
  gtk_init (&amp;argc, &amp;argv);
  /* Create the main window */
  mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  /* Set up our GUI elements */
  ...
  /* Show the application window */
  gtk_widget_show_all (mainwin);
  /* Enter the main event loop, and wait for user interaction */
  gtk_main (<!-- -->);
  /* The user lost interest */
  return 0;
}
</programlisting>
</example>
<para>
It's OK to use the GLib main loop directly instead of <link linkend="gtk-main"><function>gtk_main()</function></link>,
though it involves slightly more typing. See <link linkend="GMainLoop"><type>GMainLoop</type></link> in the GLib
documentation.
</para>
</refsect1>

<refsect1 id="gtk-General.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="gtk-set-locale" role="function">
<title>gtk_set_locale ()</title>
<indexterm zone="gtk-set-locale"><primary sortas="set_locale">gtk_set_locale</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             gtk_set_locale                      (void);</programlisting>
<para>
Initializes internationalization support for GTK+. <link linkend="gtk-init"><function>gtk_init()</function></link>
automatically does this, so there is typically no point
in calling this function.
</para>
<para>
If you are calling this function because you changed the locale
after GTK+ is was initialized, then calling this function
may help a bit. (Note, however, that changing the locale
after GTK+ is initialized may produce inconsistent results and
is not really supported.)
</para>
<para>
In detail - sets the current locale according to the
program environment. This is the same as calling the C library function
<literal>setlocale (LC_ALL, "")</literal> but also takes care of the 
locale specific setup of the windowing system used by GDK.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string corresponding to the locale set, typically in the
form lang_COUNTRY, where lang is an ISO-639 language code, and
COUNTRY is an ISO-3166 country code. On Unix, this form matches the
result of the <link linkend="setlocale"><function>setlocale()</function></link>; it is also used on other machines, such as 
Windows, where the C library returns a different result. The string is 
owned by GTK+ and should not be modified or freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-disable-setlocale" role="function">
<title>gtk_disable_setlocale ()</title>
<indexterm zone="gtk-disable-setlocale"><primary sortas="disable_setlocale">gtk_disable_setlocale</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_disable_setlocale               (void);</programlisting>
<para>
Prevents <link linkend="gtk-init"><function>gtk_init()</function></link>, <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>, <link linkend="gtk-init-with-args"><function>gtk_init_with_args()</function></link> and
<link linkend="gtk-parse-args"><function>gtk_parse_args()</function></link> from automatically
calling <literal>setlocale (LC_ALL, "")</literal>. You would 
want to use this function if you wanted to set the locale for 
your program to something other than the user's locale, or if 
you wanted to set different values for different locale categories.
</para>
<para>
Most programs should not need to call this function.</para>
<para>
</para></refsect2>
<refsect2 id="gtk-get-default-language" role="function">
<title>gtk_get_default_language ()</title>
<indexterm zone="gtk-get-default-language"><primary sortas="get_default_language">gtk_get_default_language</primary></indexterm><programlisting><link linkend="PangoLanguage">PangoLanguage</link> *     gtk_get_default_language            (void);</programlisting>
<para>
Returns the <link linkend="PangoLanguage"><type>PangoLanguage</type></link> for the default language currently in
effect. (Note that this can change over the life of an
application.)  The default language is derived from the current
locale. It determines, for example, whether GTK+ uses the
right-to-left or left-to-right text direction.
</para>
<para>
This function is equivalent to <link linkend="pango-language-get-default"><function>pango_language_get_default()</function></link>.  See
that function for details.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the default language as a <link linkend="PangoLanguage"><type>PangoLanguage</type></link>, must not be
freed
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-parse-args" role="function">
<title>gtk_parse_args ()</title>
<indexterm zone="gtk-parse-args"><primary sortas="parse_args">gtk_parse_args</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_parse_args                      (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);</programlisting>
<para>
Parses command line arguments, and initializes global
attributes of GTK+, but does not actually open a connection
to a display. (See <link linkend="gdk-display-open"><function>gdk_display_open()</function></link>, <link linkend="gdk-get-display-arg-name"><function>gdk_get_display_arg_name()</function></link>)
</para>
<para>
Any arguments used by GTK+ or 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>, or <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara> a pointer to the number of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara> a pointer to the array of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if initialization succeeded, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-init" role="function">
<title>gtk_init ()</title>
<indexterm zone="gtk-init"><primary sortas="init">gtk_init</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_init                            (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);</programlisting>
<para>
Call this function before using any other GTK+ functions in your GUI
applications.  It will initialize everything needed to operate the 
toolkit and parses some standard command line options. <parameter>argc</parameter> and 
<parameter>argv</parameter> are adjusted accordingly so your own code will 
never see those standard arguments. 
</para>
<para>
Note that there are some alternative ways to initialize GTK+: 
if you are calling <link linkend="gtk-parse-args"><function>gtk_parse_args()</function></link>, <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>, 
<link linkend="gtk-init-with-args"><function>gtk_init_with_args()</function></link> or <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> with 
the option group returned by <link linkend="gtk-get-option-group"><function>gtk_get_option_group()</function></link>, you 
<emphasis>don't</emphasis> have to call <link linkend="gtk-init"><function>gtk_init()</function></link>.
</para>
<para>
<note><para>
This function will terminate your program if it was unable to initialize 
the GUI for some reason. If you want your program to fall back to a 
textual interface you want to call <link linkend="gtk-init-check"><function>gtk_init_check()</function></link> instead.
</para></note></para>
<para>
</para>
<note>
<para>
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara> Address of the <parameter>argc</parameter> parameter of your 
  <link linkend="main"><function>main()</function></link> function. Changed if any arguments were handled.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara> Address of the <parameter>argv</parameter> parameter of <link linkend="main"><function>main()</function></link>. 
  Any parameters understood by <link linkend="gtk-init"><function>gtk_init()</function></link> are stripped before return.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-init-check" role="function">
<title>gtk_init_check ()</title>
<indexterm zone="gtk-init-check"><primary sortas="init_check">gtk_init_check</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_init_check                      (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv);</programlisting>
<para>
This function does the same work as <link linkend="gtk-init"><function>gtk_init()</function></link> with only 
a single change: It does not terminate the program if the GUI can't be 
initialized. Instead it returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> on failure.
</para>
<para>
This way the application can fall back to some other means of communication 
with the user - for example a curses or command line interface.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara> Address of the <parameter>argc</parameter> parameter of your 
  <link linkend="main"><function>main()</function></link> function. Changed if any arguments were handled.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara> Address of the <parameter>argv</parameter> parameter of <link linkend="main"><function>main()</function></link>. 
  Any parameters understood by <link linkend="gtk-init"><function>gtk_init()</function></link> are stripped before return.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the GUI has been successfully initialized, 
              <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-init-with-args" role="function" condition="since:2.6">
<title>gtk_init_with_args ()</title>
<indexterm zone="gtk-init-with-args" role="2.6"><primary sortas="init_with_args">gtk_init_with_args</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_init_with_args                  (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv,
                                                         <link linkend="char">char</link> *parameter_string,
                                                         <link linkend="GOptionEntry">GOptionEntry</link> *entries,
                                                         <link linkend="char">char</link> *translation_domain,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function does the same work as <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>. 
Additionally, it allows you to add your own commandline options, 
and it automatically generates nicely formatted 
<option>--help</option> output. Note that your program will
be terminated after writing out the help output.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara> a pointer to the number of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara> a pointer to the array of command line arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>parameter_string</parameter>&#160;:</term>
<listitem><simpara> a string which is displayed in
   the first line of <option>--help</option> output, after 
   <literal><replaceable>programname</replaceable> [OPTION...]</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>entries</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
   describing the options of your program
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>translation_domain</parameter>&#160;:</term>
<listitem><simpara> a translation domain to use for translating
   the <option>--help</option> output for the options in <parameter>entries</parameter>
   with <link linkend="gettext"><function>gettext()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a return location for errors 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the GUI has been successfully initialized, 
              <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="gtk-get-option-group" role="function" condition="since:2.6">
<title>gtk_get_option_group ()</title>
<indexterm zone="gtk-get-option-group" role="2.6"><primary sortas="get_option_group">gtk_get_option_group</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> *      gtk_get_option_group                (<link linkend="gboolean">gboolean</link> open_default_display);</programlisting>
<para>
Returns a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> for the commandline arguments recognized
by GTK+ and GDK. You should add this group to your <link linkend="GOptionContext"><type>GOptionContext</type></link> 
with <link linkend="g-option-context-add-group"><function>g_option_context_add_group()</function></link>, if you are using 
<link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> to parse your commandline arguments.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>open_default_display</parameter>&#160;:</term>
<listitem><simpara> whether to open the default display 
   when parsing the commandline arguments
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> for the commandline arguments recognized
  by GTK+

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="gtk-exit" role="function" condition="deprecated:Use the standard exit() function instead.">
<title>gtk_exit ()</title>
<indexterm zone="gtk-exit" role="deprecated"><primary sortas="exit">gtk_exit</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_exit                            (<link linkend="gint">gint</link> error_code);</programlisting>
<warning><para><literal>gtk_exit</literal> is deprecated and should not be used in newly-written code. Use the standard <link linkend="exit"><function>exit()</function></link> function instead.</para></warning>
<para>
Terminates the program and returns the given exit code to the caller.
This function will shut down the GUI and free all resources allocated
for GTK+.
</para><variablelist role="params">
<varlistentry><term><parameter>error_code</parameter>&#160;:</term>
<listitem><simpara>Return value to pass to the caller. This is dependent on the
target system but at least on Unix systems <link linkend="0--CAPS"><literal>0</literal></link> means success.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-events-pending" role="function">
<title>gtk_events_pending ()</title>
<indexterm zone="gtk-events-pending"><primary sortas="events_pending">gtk_events_pending</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_events_pending                  (void);</programlisting>
<para>
Checks if any events are pending. This can be used to update the GUI
and invoke timeouts etc. while doing some time intensive computation.
</para>
<example>
<title>Updating the GUI during a long computation.</title>
<programlisting>
	/* computation going on */
...
        while (gtk_events_pending (<!-- -->))
	  gtk_main_iteration (<!-- -->);
...
	/* computation continued */
</programlisting>
</example><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if any events are pending, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-main" role="function">
<title>gtk_main ()</title>
<indexterm zone="gtk-main"><primary sortas="main">gtk_main</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_main                            (void);</programlisting>
<para>
Runs the main loop until <link linkend="gtk-main-quit"><function>gtk_main_quit()</function></link> is called. You can nest calls to
<link linkend="gtk-main"><function>gtk_main()</function></link>. In that case <link linkend="gtk-main-quit"><function>gtk_main_quit()</function></link> will make the innermost invocation
of the main loop return.
</para></refsect2>
<refsect2 id="gtk-main-level" role="function">
<title>gtk_main_level ()</title>
<indexterm zone="gtk-main-level"><primary sortas="main_level">gtk_main_level</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_main_level                      (void);</programlisting>
<para>
Asks for the current nesting level of the main loop. This can be useful
when calling <link linkend="gtk-quit-add"><function>gtk_quit_add()</function></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the nesting level of the current invocation of the main loop.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-main-quit" role="function">
<title>gtk_main_quit ()</title>
<indexterm zone="gtk-main-quit"><primary sortas="main_quit">gtk_main_quit</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_main_quit                       (void);</programlisting>
<para>
Makes the innermost invocation of the main loop return when it regains
control.
</para></refsect2>
<refsect2 id="gtk-main-iteration" role="function">
<title>gtk_main_iteration ()</title>
<indexterm zone="gtk-main-iteration"><primary sortas="main_iteration">gtk_main_iteration</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_main_iteration                  (void);</programlisting>
<para>
Runs a single iteration of the mainloop. If no events are waiting to be
processed GTK+ will block until the next event is noticed. If you don't
want to block look at <link linkend="gtk-main-iteration-do"><function>gtk_main_iteration_do()</function></link> or check if any events are
pending with <link linkend="gtk-events-pending"><function>gtk_events_pending()</function></link> first.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <link linkend="gtk-main-quit"><function>gtk_main_quit()</function></link> has been called for the innermost mainloop.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-main-iteration-do" role="function">
<title>gtk_main_iteration_do ()</title>
<indexterm zone="gtk-main-iteration-do"><primary sortas="main_iteration_do">gtk_main_iteration_do</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_main_iteration_do               (<link linkend="gboolean">gboolean</link> blocking);</programlisting>
<para>
Runs a single iteration of the mainloop. If no events are available either
return or block dependent on the value of <parameter>blocking</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>blocking</parameter>&#160;:</term>
<listitem><simpara>%TRUE if you want GTK+ to block if no events are pending.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <link linkend="gtk-main-quit"><function>gtk_main_quit()</function></link> has been called for the innermost mainloop.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-main-do-event" role="function">
<title>gtk_main_do_event ()</title>
<indexterm zone="gtk-main-do-event"><primary sortas="main_do_event">gtk_main_do_event</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_main_do_event                   (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Processes a single GDK event. This is public only to allow filtering of events
between GDK and GTK+. You will not usually need to call this function directly.
</para>
<para>
While you should not call this function directly, you might want to know
how exactly events are handled. So here is what this function does with
the event:
</para>
<orderedlist>
<listitem><para>
  Compress enter/leave notify events. If the event passed build an
  enter/leave pair together with the next event (peeked from GDK)
  both events are thrown away. This is to avoid a backlog of (de-)highlighting
  widgets crossed by the pointer.
</para></listitem>
<listitem><para>
  Find the widget which got the event. If the widget can't be determined
  the event is thrown away unless it belongs to a INCR transaction. In that
  case it is passed to <link linkend="gtk-selection-incr-event"><function>gtk_selection_incr_event()</function></link>.
</para></listitem>
<listitem><para>
  Then the event is passed on a stack so you can query the currently handled
  event with <link linkend="gtk-get-current-event"><function>gtk_get_current_event()</function></link>.
</para></listitem>
<listitem><para>
  The event is sent to a widget. If a grab is active all events for
  widgets that are not in the contained in the grab widget are sent to the
  latter with a few exceptions:
  <itemizedlist>
  <listitem><para>
    Deletion and destruction events are still sent to the event widget for
    obvious reasons.
  </para></listitem>
  <listitem><para>
    Events which directly relate to the visual representation of the event
    widget.
  </para></listitem>
  <listitem><para>
    Leave events are delivered to the event widget if there was an enter
    event delivered to it before without the paired leave event.
  </para></listitem>
  <listitem><para>
    Drag events are not redirected because it is unclear what the semantics
    of that would be.
  </para></listitem>
  </itemizedlist>
  Another point of interest might be that all key events are first passed
  through the key snooper functions if there are any. Read the description
  of <link linkend="gtk-key-snooper-install"><function>gtk_key_snooper_install()</function></link> if you need this feature.
</para></listitem>
<listitem><para>
  After finishing the delivery the event is popped from the event stack.
</para></listitem>
</orderedlist><variablelist role="params">
<varlistentry><term><parameter>event</parameter>&#160;:</term>
<listitem><simpara>An event to process (normally) passed by GDK.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GtkModuleInitFunc" role="function">
<title>GtkModuleInitFunc ()</title>
<indexterm zone="GtkModuleInitFunc"><primary sortas="ModuleInitFunc">GtkModuleInitFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GtkModuleInitFunc)                (<link linkend="gint">gint</link> *argc,
                                                         <link linkend="gchar">gchar</link> ***argv);</programlisting>
<para>
Each GTK+ module must have a function <link linkend="gtk-module-init"><function>gtk_module_init()</function></link> with this prototype.
This function is called after loading the module with the <parameter>argc</parameter> and <parameter>argv</parameter>
cleaned from any arguments that GTK+ handles itself.
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
<listitem><simpara>Pointer to the number of arguments remaining after <link linkend="gtk-init"><function>gtk_init()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
<listitem><simpara>Points to the argument vector.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GtkModuleDisplayInitFunc" role="function" condition="since:2.2">
<title>GtkModuleDisplayInitFunc ()</title>
<indexterm zone="GtkModuleDisplayInitFunc" role="2.2"><primary sortas="ModuleDisplayInitFunc">GtkModuleDisplayInitFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GtkModuleDisplayInitFunc)         (<link linkend="GdkDisplay">GdkDisplay</link> *display);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>display</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="gtk-true" role="function">
<title>gtk_true ()</title>
<indexterm zone="gtk-true"><primary sortas="true">gtk_true</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_true                            (void);</programlisting>
<para>
All this function does it to return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. This can be useful for example
if you want to inhibit the deletion of a window. Of course you should
not do this as the user expects a reaction from clicking the close
icon of the window...
</para>
<example>
<title>A persistent window</title>
<programlisting>
##include &lt;gtk/gtk.h&gt;
int
main (int argc, char **argv)
{
  GtkWidget     *win, *but;
  gtk_init( &amp;argc, &amp;argv );
  win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  g_signal_connect (win, "delete-event",
                    G_CALLBACK (gtk_true), NULL);
  g_signal_connect (win, "destroy",
		    G_CALLBACK (gtk_main_quit), NULL);
  but = gtk_button_new_with_label ("Close yourself. I mean it!");
  g_signal_connect_swapped (but, "clicked",
		  G_CALLBACK (gtk_object_destroy), win);
  gtk_container_add (GTK_CONTAINER (win), but);
  gtk_widget_show_all (win);
  gtk_main (<!-- -->);
  return 0;
}
</programlisting>
</example><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-false" role="function">
<title>gtk_false ()</title>
<indexterm zone="gtk-false"><primary sortas="false">gtk_false</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_false                           (void);</programlisting>
<para>
Analogical to <link linkend="gtk-true"><function>gtk_true()</function></link> this function does nothing
but always returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%FALSE
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-grab-add" role="function">
<title>gtk_grab_add ()</title>
<indexterm zone="gtk-grab-add"><primary sortas="grab_add">gtk_grab_add</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_grab_add                        (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Makes <parameter>widget</parameter> the current grabbed widget. This means that interaction with
other widgets in the same application is blocked and mouse as well as
keyboard events are delivered to this widget.
</para>
<para>
If <parameter>widget</parameter> is not sensitive, it is not set as the current grabbed
widget and this function does nothing.
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara>The widget that grabs keyboard and pointer events.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-grab-get-current" role="function">
<title>gtk_grab_get_current ()</title>
<indexterm zone="gtk-grab-get-current"><primary sortas="grab_get_current">gtk_grab_get_current</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*          gtk_grab_get_current                (void);</programlisting>
<para>
Queries the current grab of the default window group.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The widget which currently has the grab or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if no grab is active.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-grab-remove" role="function">
<title>gtk_grab_remove ()</title>
<indexterm zone="gtk-grab-remove"><primary sortas="grab_remove">gtk_grab_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_grab_remove                     (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Removes the grab from the given widget. You have to pair calls to <link linkend="gtk-grab-add"><function>gtk_grab_add()</function></link>
and <link linkend="gtk-grab-remove"><function>gtk_grab_remove()</function></link>.
</para>
<para>
If <parameter>widget</parameter> does not have the grab, this function does nothing.
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara>The widget which gives up the grab.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-init-add" role="function">
<title>gtk_init_add ()</title>
<indexterm zone="gtk-init-add"><primary sortas="init_add">gtk_init_add</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_init_add                        (<link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Registers a function to be called when the mainloop is started.
</para><variablelist role="params">
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>Function to invoke when <link linkend="gtk-main"><function>gtk_main()</function></link> is called next.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>Data to pass to that function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-quit-add-destroy" role="function">
<title>gtk_quit_add_destroy ()</title>
<indexterm zone="gtk-quit-add-destroy"><primary sortas="quit_add_destroy">gtk_quit_add_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_quit_add_destroy                (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkObject">GtkObject</link> *object);</programlisting>
<para>
Trigger destruction of <parameter>object</parameter> in case the mainloop at level <parameter>main_level</parameter>
is quit.
</para><variablelist role="params">
<varlistentry><term><parameter>main_level</parameter>&#160;:</term>
<listitem><simpara>Level of the mainloop which shall trigger the destruction.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>Object to be destroyed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-quit-add" role="function">
<title>gtk_quit_add ()</title>
<indexterm zone="gtk-quit-add"><primary sortas="quit_add">gtk_quit_add</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_quit_add                        (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Registers a function to be called when an instance of the mainloop is left.
</para><variablelist role="params">
<varlistentry><term><parameter>main_level</parameter>&#160;:</term>
<listitem><simpara>Level at which termination the function shall be called. You
 can pass 0 here to have the function run at the termination of the current
 mainloop.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call. This should return 0 to be removed from the 
 list of quit handlers. Otherwise the function might be called again.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>Pointer to pass when calling <parameter>function</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A handle for this quit handler (you need this for <link linkend="gtk-quit-remove"><function>gtk_quit_remove()</function></link>)
  or 0 if you passed a <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer in <parameter>function</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-quit-add-full" role="function">
<title>gtk_quit_add_full ()</title>
<indexterm zone="gtk-quit-add-full"><primary sortas="quit_add_full">gtk_quit_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_quit_add_full                   (<link linkend="guint">guint</link> main_level,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<para>
Registers a function to be called when an instance of the mainloop is left.
In comparison to <link linkend="gtk-quit-add"><function>gtk_quit_add()</function></link> this function adds the possibility to
pass a marshaller and a function to be called when the quit handler is freed.
</para>
<para>
The former can be used to run interpreted code instead of a compiled function
while the latter can be used to free the information stored in <parameter>data</parameter> (while
you can do this in <parameter>function</parameter> as well)... So this function will mostly be
used by GTK+ wrappers for languages other than C.
</para><variablelist role="params">
<varlistentry><term><parameter>main_level</parameter>&#160;:</term>
<listitem><simpara>Level at which termination the function shall be called. You
 can pass 0 here to have the function run at the termination of the current
 mainloop.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call. This should return 0 to be removed from the 
 list of quit handlers. Otherwise the function might be called again.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshal</parameter>&#160;:</term>
<listitem><simpara>The marshaller to be used. If this is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, <parameter>function</parameter> is 
 ignored.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>Pointer to pass when calling <parameter>function</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara>Function to call to destruct <parameter>data</parameter>. Gets <parameter>data</parameter> as argument.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A handle for this quit handler (you need this for <link linkend="gtk-quit-remove"><function>gtk_quit_remove()</function></link>)
  or 0 if you passed a <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer in <parameter>function</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-quit-remove" role="function">
<title>gtk_quit_remove ()</title>
<indexterm zone="gtk-quit-remove"><primary sortas="quit_remove">gtk_quit_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_quit_remove                     (<link linkend="guint">guint</link> quit_handler_id);</programlisting>
<para>
Removes a quit handler by its identifier.
</para><variablelist role="params">
<varlistentry><term><parameter>quit_handler_id</parameter>&#160;:</term>
<listitem><simpara>Identifier for the handler returned when installing it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-quit-remove-by-data" role="function">
<title>gtk_quit_remove_by_data ()</title>
<indexterm zone="gtk-quit-remove-by-data"><primary sortas="quit_remove_by_data">gtk_quit_remove_by_data</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_quit_remove_by_data             (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Removes a quit handler identified by its <parameter>data</parameter> field.
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>The pointer passed as <parameter>data</parameter> to <link linkend="gtk-quit-add"><function>gtk_quit_add()</function></link> or <link linkend="gtk-quit-add-full"><function>gtk_quit_add_full()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-timeout-add-full" role="function" condition="deprecated:2.4: Use g_timeout_add_full() instead.">
<title>gtk_timeout_add_full ()</title>
<indexterm zone="gtk-timeout-add-full" role="deprecated"><primary sortas="timeout_add_full">gtk_timeout_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_timeout_add_full                (<link linkend="guint32">guint32</link> interval,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<warning><para><literal>gtk_timeout_add_full</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-timeout-add-full"><function>g_timeout_add_full()</function></link> instead.</para></warning>
<para>
Registers a function to be called periodically. The function will be called
repeatedly after <parameter>interval</parameter> milliseconds until it returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> at which
point the timeout is destroyed and will not be called again.
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter>&#160;:</term>
<listitem><simpara>The time between calls to the function, in milliseconds 
	(1/1000ths of a second.)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call periodically.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshal</parameter>&#160;:</term>
<listitem><simpara>The marshaller to use instead of the function (if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>The data to pass to the function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara>Function to call when the timeout is destroyed or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A unique id for the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-timeout-add" role="function" condition="deprecated:2.4: Use g_timeout_add() instead.">
<title>gtk_timeout_add ()</title>
<indexterm zone="gtk-timeout-add" role="deprecated"><primary sortas="timeout_add">gtk_timeout_add</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_timeout_add                     (<link linkend="guint32">guint32</link> interval,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<warning><para><literal>gtk_timeout_add</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-timeout-add"><function>g_timeout_add()</function></link> instead.</para></warning>
<para>
Registers a function to be called periodically. The function will be called
repeatedly after <parameter>interval</parameter> milliseconds until it returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> at which
point the timeout is destroyed and will not be called again.
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter>&#160;:</term>
<listitem><simpara>The time between calls to the function, in milliseconds 
	(1/1000ths of a second.)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call periodically.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>The data to pass to the function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A unique id for the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-timeout-remove" role="function" condition="deprecated:2.4: Use g_source_remove() instead.">
<title>gtk_timeout_remove ()</title>
<indexterm zone="gtk-timeout-remove" role="deprecated"><primary sortas="timeout_remove">gtk_timeout_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_timeout_remove                  (<link linkend="guint">guint</link> timeout_handler_id);</programlisting>
<warning><para><literal>gtk_timeout_remove</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-source-remove"><function>g_source_remove()</function></link> instead.</para></warning>
<para>
Removes the given timeout destroying all information about it.
</para><variablelist role="params">
<varlistentry><term><parameter>timeout_handler_id</parameter>&#160;:</term>
<listitem><simpara>The identifier returned when installing the timeout.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-idle-add" role="function" condition="deprecated:2.4: Use g_idle_add() instead.">
<title>gtk_idle_add ()</title>
<indexterm zone="gtk-idle-add" role="deprecated"><primary sortas="idle_add">gtk_idle_add</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_idle_add                        (<link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<warning><para><literal>gtk_idle_add</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-idle-add"><function>g_idle_add()</function></link> instead.</para></warning>
<para>
Causes the mainloop to call the given function whenever no events with
higher priority are to be processed. The default priority is
<link linkend="GTK-PRIORITY-DEFAULT--CAPS"><literal>GTK_PRIORITY_DEFAULT</literal></link>, which is rather low.
</para><variablelist role="params">
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>The information to pass to the function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a unique handle for this registration.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-idle-add-priority" role="function" condition="deprecated:2.4: Use g_idle_add_full() instead.">
<title>gtk_idle_add_priority ()</title>
<indexterm zone="gtk-idle-add-priority" role="deprecated"><primary sortas="idle_add_priority">gtk_idle_add_priority</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_idle_add_priority               (<link linkend="gint">gint</link> priority,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<warning><para><literal>gtk_idle_add_priority</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-idle-add-full"><function>g_idle_add_full()</function></link> instead.</para></warning>
<para>
Like <link linkend="gtk-idle-add"><function>gtk_idle_add()</function></link> this function allows you to have a function called
when the event loop is idle. The difference is that you can give a
priority different from <link linkend="GTK-PRIORITY-DEFAULT--CAPS"><literal>GTK_PRIORITY_DEFAULT</literal></link> to the idle function.
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara>The priority which should not be above <link linkend="G-PRIORITY-HIGH-IDLE--CAPS"><literal>G_PRIORITY_HIGH_IDLE</literal></link>.
Note that you will interfere with GTK+ if you use a priority above
<link linkend="GTK-PRIORITY-RESIZE--CAPS"><literal>GTK_PRIORITY_RESIZE</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>Data to pass to that function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A unique id for the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-idle-add-full" role="function" condition="deprecated:2.4: Use g_idle_add_full() instead.">
<title>gtk_idle_add_full ()</title>
<indexterm zone="gtk-idle-add-full" role="deprecated"><primary sortas="idle_add_full">gtk_idle_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_idle_add_full                   (<link linkend="gint">gint</link> priority,
                                                         <link linkend="GtkFunction">GtkFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<warning><para><literal>gtk_idle_add_full</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-idle-add-full"><function>g_idle_add_full()</function></link> instead.</para></warning>
<para>
Like <link linkend="gtk-idle-add"><function>gtk_idle_add()</function></link> this function allows you to have a function called
when the event loop is idle. The difference is that you can give a
priority different from <link linkend="GTK-PRIORITY-DEFAULT--CAPS"><literal>GTK_PRIORITY_DEFAULT</literal></link> to the idle function.
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara>The priority which should not be above <link linkend="G-PRIORITY-HIGH-IDLE--CAPS"><literal>G_PRIORITY_HIGH_IDLE</literal></link>.
Note that you will interfere with GTK+ if you use a priority above
<link linkend="GTK-PRIORITY-RESIZE--CAPS"><literal>GTK_PRIORITY_RESIZE</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshal</parameter>&#160;:</term>
<listitem><simpara>The marshaller to use instead of the function (if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>Data to pass to that function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara>Function to call when the timeout is destroyed or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A unique id for the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-idle-remove" role="function" condition="deprecated:2.4: Use g_source_remove() instead.">
<title>gtk_idle_remove ()</title>
<indexterm zone="gtk-idle-remove" role="deprecated"><primary sortas="idle_remove">gtk_idle_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_idle_remove                     (<link linkend="guint">guint</link> idle_handler_id);</programlisting>
<warning><para><literal>gtk_idle_remove</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-source-remove"><function>g_source_remove()</function></link> instead.</para></warning>
<para>
Removes the idle function with the given id.
</para><variablelist role="params">
<varlistentry><term><parameter>idle_handler_id</parameter>&#160;:</term>
<listitem><simpara>Identifies the idle function to remove.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-idle-remove-by-data" role="function" condition="deprecated:2.4: Use g_idle_remove_by_data() instead.">
<title>gtk_idle_remove_by_data ()</title>
<indexterm zone="gtk-idle-remove-by-data" role="deprecated"><primary sortas="idle_remove_by_data">gtk_idle_remove_by_data</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_idle_remove_by_data             (<link linkend="gpointer">gpointer</link> data);</programlisting>
<warning><para><literal>gtk_idle_remove_by_data</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-idle-remove-by-data"><function>g_idle_remove_by_data()</function></link> instead.</para></warning>
<para>
Removes the idle function identified by the user data.
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>remove the idle function which was registered with this user data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-input-add-full" role="function" condition="deprecated:2.4: Use g_io_add_watch_full() instead.">
<title>gtk_input_add_full ()</title>
<indexterm zone="gtk-input-add-full" role="deprecated"><primary sortas="input_add_full">gtk_input_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_input_add_full                  (<link linkend="gint">gint</link> source,
                                                         <link linkend="GdkInputCondition">GdkInputCondition</link> condition,
                                                         <link linkend="GdkInputFunction">GdkInputFunction</link> function,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> marshal,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<warning><para><literal>gtk_input_add_full</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link> instead.</para></warning>
<para>
Registers a function to be called when a condition becomes true
on a file descriptor.
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara>a file descriptor.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&#160;:</term>
<listitem><simpara>the condition.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara>The function to call.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshal</parameter>&#160;:</term>
<listitem><simpara>The marshaller to use instead of the function (if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>callback data passed to <parameter>function</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara>callback function to call with <parameter>data</parameter> when the input
  handler is removed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A unique id for the event source; to be used with <link linkend="gtk-input-remove"><function>gtk_input_remove()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-input-remove" role="function" condition="deprecated:2.4: Use g_source_remove() instead.">
<title>gtk_input_remove ()</title>
<indexterm zone="gtk-input-remove" role="deprecated"><primary sortas="input_remove">gtk_input_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_input_remove                    (<link linkend="guint">guint</link> input_handler_id);</programlisting>
<warning><para><literal>gtk_input_remove</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="g-source-remove"><function>g_source_remove()</function></link> instead.</para></warning>
<para>
Removes the function with the given id.
</para><variablelist role="params">
<varlistentry><term><parameter>input_handler_id</parameter>&#160;:</term>
<listitem><simpara>Identifies the function to remove.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTK-PRIORITY-REDRAW--CAPS" role="macro" condition="deprecated:2.4: This macro is deprecated. You should use %GDK_PRIORITY_REDRAW instead.">
<title>GTK_PRIORITY_REDRAW</title>
<indexterm zone="GTK-PRIORITY-REDRAW--CAPS" role="deprecated"><primary sortas="PRIORITY_REDRAW">GTK_PRIORITY_REDRAW</primary></indexterm><programlisting>#define GTK_PRIORITY_REDRAW     (G_PRIORITY_HIGH_IDLE + 20)
</programlisting>
<warning><para><literal>GTK_PRIORITY_REDRAW</literal> has been deprecated since version 2.4 and should not be used in newly-written code. This macro is deprecated. You should use <link linkend="GDK-PRIORITY-REDRAW--CAPS"><literal>GDK_PRIORITY_REDRAW</literal></link> instead.</para></warning>
<para>
Use this priority for redrawing related stuff. It is used internally by
GTK+ to do pending redraws. This priority is lower than <link linkend="GTK-PRIORITY-RESIZE--CAPS"><literal>GTK_PRIORITY_RESIZE</literal></link>
to avoid redrawing a widget just before resizing (and therefore redrawing
it again).
</para></refsect2>
<refsect2 id="GTK-PRIORITY-RESIZE--CAPS" role="macro">
<title>GTK_PRIORITY_RESIZE</title>
<indexterm zone="GTK-PRIORITY-RESIZE--CAPS"><primary sortas="PRIORITY_RESIZE">GTK_PRIORITY_RESIZE</primary></indexterm><programlisting>#define GTK_PRIORITY_RESIZE     (G_PRIORITY_HIGH_IDLE + 10)
</programlisting>
<para>
Use this priority for resizing related stuff. It is used internally by
GTK+ to compute the sizes of widgets. This priority is higher than
<link linkend="GTK-PRIORITY-REDRAW--CAPS"><literal>GTK_PRIORITY_REDRAW</literal></link> to avoid resizing a widget which was just redrawn.
</para></refsect2>
<refsect2 id="GTK-PRIORITY-HIGH--CAPS" role="macro" condition="deprecated:2.4: This macro is deprecated. You should use %G_PRIORITY_HIGH instead.">
<title>GTK_PRIORITY_HIGH</title>
<indexterm zone="GTK-PRIORITY-HIGH--CAPS" role="deprecated"><primary sortas="PRIORITY_HIGH">GTK_PRIORITY_HIGH</primary></indexterm><programlisting>#define GTK_PRIORITY_HIGH       G_PRIORITY_HIGH
</programlisting>
<warning><para><literal>GTK_PRIORITY_HIGH</literal> has been deprecated since version 2.4 and should not be used in newly-written code. This macro is deprecated. You should use <link linkend="G-PRIORITY-HIGH--CAPS"><literal>G_PRIORITY_HIGH</literal></link> instead.</para></warning>
<para>
Use this for high priority timeouts. This priority is never used inside
GTK+ so everything running at this priority will be running before anything
inside the toolkit.
</para></refsect2>
<refsect2 id="GTK-PRIORITY-INTERNAL--CAPS" role="macro" condition="deprecated:">
<title>GTK_PRIORITY_INTERNAL</title>
<indexterm zone="GTK-PRIORITY-INTERNAL--CAPS" role="deprecated"><primary sortas="PRIORITY_INTERNAL">GTK_PRIORITY_INTERNAL</primary></indexterm><programlisting>#define GTK_PRIORITY_INTERNAL   GTK_PRIORITY_REDRAW
</programlisting>
<warning><para><literal>GTK_PRIORITY_INTERNAL</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
This priority is for GTK+ internal stuff. Don't use it in your applications.
</para></refsect2>
<refsect2 id="GTK-PRIORITY-DEFAULT--CAPS" role="macro" condition="deprecated:2.4: This macro is deprecated. You should use %G_PRIORITY_DEFAULT_IDLE instead.">
<title>GTK_PRIORITY_DEFAULT</title>
<indexterm zone="GTK-PRIORITY-DEFAULT--CAPS" role="deprecated"><primary sortas="PRIORITY_DEFAULT">GTK_PRIORITY_DEFAULT</primary></indexterm><programlisting>#define GTK_PRIORITY_DEFAULT	G_PRIORITY_DEFAULT_IDLE
</programlisting>
<warning><para><literal>GTK_PRIORITY_DEFAULT</literal> has been deprecated since version 2.4 and should not be used in newly-written code. This macro is deprecated. You should use <link linkend="G-PRIORITY-DEFAULT-IDLE--CAPS"><literal>G_PRIORITY_DEFAULT_IDLE</literal></link> instead.</para></warning>
<para>
Default priority for idle functions.
</para></refsect2>
<refsect2 id="GTK-PRIORITY-LOW--CAPS" role="macro" condition="deprecated:2.4: This macro is deprecated. You should use %G_PRIORITY_LOW instead.">
<title>GTK_PRIORITY_LOW</title>
<indexterm zone="GTK-PRIORITY-LOW--CAPS" role="deprecated"><primary sortas="PRIORITY_LOW">GTK_PRIORITY_LOW</primary></indexterm><programlisting>#define GTK_PRIORITY_LOW	G_PRIORITY_LOW
</programlisting>
<warning><para><literal>GTK_PRIORITY_LOW</literal> has been deprecated since version 2.4 and should not be used in newly-written code. This macro is deprecated. You should use <link linkend="G-PRIORITY-LOW--CAPS"><literal>G_PRIORITY_LOW</literal></link> instead.</para></warning>
<para>
Priority for very unimportant background tasks.
</para></refsect2>
<refsect2 id="gtk-key-snooper-install" role="function">
<title>gtk_key_snooper_install ()</title>
<indexterm zone="gtk-key-snooper-install"><primary sortas="key_snooper_install">gtk_key_snooper_install</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_key_snooper_install             (<link linkend="GtkKeySnoopFunc">GtkKeySnoopFunc</link> snooper,
                                                         <link linkend="gpointer">gpointer</link> func_data);</programlisting>
<para>
Installs a key snooper function, which will get called on all key events
before delivering them normally.
</para><variablelist role="params">
<varlistentry><term><parameter>snooper</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkKeySnoopFunc"><type>GtkKeySnoopFunc</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func_data</parameter>&#160;:</term>
<listitem><simpara>data to pass to <parameter>snooper</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a unique id for this key snooper for use with <link linkend="gtk-key-snooper-remove"><function>gtk_key_snooper_remove()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GtkKeySnoopFunc" role="function">
<title>GtkKeySnoopFunc ()</title>
<indexterm zone="GtkKeySnoopFunc"><primary sortas="KeySnoopFunc">GtkKeySnoopFunc</primary></indexterm><programlisting><link linkend="gint">gint</link>                (*GtkKeySnoopFunc)                  (<link linkend="GtkWidget">GtkWidget</link> *grab_widget,
                                                         <link linkend="GdkEventKey">GdkEventKey</link> *event,
                                                         <link linkend="gpointer">gpointer</link> func_data);</programlisting>
<para>
Key snooper functions are called before normal event delivery.
They can be used to implement custom key event handling.
</para><variablelist role="params">
<varlistentry><term><parameter>grab_widget</parameter>&#160;:</term>
<listitem><simpara>the widget to which the event will be delivered.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter>&#160;:</term>
<listitem><simpara>the key event.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func_data</parameter>&#160;:</term>
<listitem><simpara>the <parameter>func_data</parameter> supplied to <link linkend="gtk-key-snooper-install"><function>gtk_key_snooper_install()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE to stop further processing of <parameter>event</parameter>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to continue.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-key-snooper-remove" role="function">
<title>gtk_key_snooper_remove ()</title>
<indexterm zone="gtk-key-snooper-remove"><primary sortas="key_snooper_remove">gtk_key_snooper_remove</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_key_snooper_remove              (<link linkend="guint">guint</link> snooper_handler_id);</programlisting>
<para>
Removes the key snooper function with the given id.
</para><variablelist role="params">
<varlistentry><term><parameter>snooper_handler_id</parameter>&#160;:</term>
<listitem><simpara>Identifies the key snooper to remove.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-get-current-event" role="function">
<title>gtk_get_current_event ()</title>
<indexterm zone="gtk-get-current-event"><primary sortas="get_current_event">gtk_get_current_event</primary></indexterm><programlisting><link linkend="GdkEvent">GdkEvent</link>*           gtk_get_current_event               (void);</programlisting>
<para>
Obtains a copy of the event currently being processed by GTK+.  For
example, if you get a "clicked" signal from <link linkend="GtkButton"><type>GtkButton</type></link>, the current
event will be the <link linkend="GdkEventButton"><type>GdkEventButton</type></link> that triggered the "clicked"
signal. The returned event must be freed with <link linkend="gdk-event-free"><function>gdk_event_free()</function></link>.
If there is no current event, the function returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a copy of the current event, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if no current event.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-get-current-event-time" role="function">
<title>gtk_get_current_event_time ()</title>
<indexterm zone="gtk-get-current-event-time"><primary sortas="get_current_event_time">gtk_get_current_event_time</primary></indexterm><programlisting><link linkend="guint32">guint32</link>             gtk_get_current_event_time          (void);</programlisting>
<para>
If there is a current event and it has a timestamp, return that
timestamp, otherwise return <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the timestamp from the current event, or <link linkend="GDK-CURRENT-TIME--CAPS"><literal>GDK_CURRENT_TIME</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-get-current-event-state" role="function">
<title>gtk_get_current_event_state ()</title>
<indexterm zone="gtk-get-current-event-state"><primary sortas="get_current_event_state">gtk_get_current_event_state</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_get_current_event_state         (<link linkend="GdkModifierType">GdkModifierType</link> *state);</programlisting>
<para>
If there is a current event and it has a state field, place
that state field in <parameter>state</parameter> and return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, otherwise return
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara> a location to store the state of the current event
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if there was a current event and it had a state field
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-get-event-widget" role="function">
<title>gtk_get_event_widget ()</title>
<indexterm zone="gtk-get-event-widget"><primary sortas="get_event_widget">gtk_get_event_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*          gtk_get_event_widget                (<link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
If <parameter>event</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or the event was not associated with any widget,
returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>, otherwise returns the widget that received the event
originally.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>event</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GdkEvent"><type>GdkEvent</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the widget that originally received <parameter>event</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-propagate-event" role="function">
<title>gtk_propagate_event ()</title>
<indexterm zone="gtk-propagate-event"><primary sortas="propagate_event">gtk_propagate_event</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_propagate_event                 (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                                         <link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Sends an event to a widget, propagating the event to parent widgets
if the event remains unhandled. Events received by GTK+ from GDK
normally begin in <link linkend="gtk-main-do-event"><function>gtk_main_do_event()</function></link>. Depending on the type of
event, existence of modal dialogs, grabs, etc., the event may be
propagated; if so, this function is used. <link linkend="gtk-propagate-event"><function>gtk_propagate_event()</function></link>
calls <link linkend="gtk-widget-event"><function>gtk_widget_event()</function></link> on each widget it decides to send the
event to.  So <link linkend="gtk-widget-event"><function>gtk_widget_event()</function></link> is the lowest-level function; it
simply emits the "event" and possibly an event-specific signal on a
widget.  <link linkend="gtk-propagate-event"><function>gtk_propagate_event()</function></link> is a bit higher-level, and
<link linkend="gtk-main-do-event"><function>gtk_main_do_event()</function></link> is the highest level.
</para>
<para>
All that said, you most likely don't want to use any of these
functions; synthesizing events is rarely needed. Consider asking on
the mailing list for better ways to achieve your goals. For
example, use <link linkend="gdk-window-invalidate-rect"><function>gdk_window_invalidate_rect()</function></link> or
<link linkend="gtk-widget-queue-draw"><function>gtk_widget_queue_draw()</function></link> instead of making up expose events.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkWidget"><type>GtkWidget</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter>&#160;:</term>
<listitem><simpara> an event
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="gtk-General.see-also">
<title>See Also</title>
<para>
See the GLib manual, especially <link linkend="GMainLoop"><type>GMainLoop</type></link> and signal-related
functions such as <link linkend="g-signal-connect"><function>g_signal_connect()</function></link>.
</para>
</refsect1>

</refentry>
