gtkmain.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<!-- ##### SECTION Title ##### -->
Main loop and Events

<!-- ##### SECTION Short_Description ##### -->
Library initialization, main event loop, and events

<!-- ##### SECTION Long_Description ##### -->

<para>
Before using GTK+, you need to initialize it; initialization connects
to the window system display, and parses some standard command line
arguments. The gtk_init() function initializes GTK+. gtk_init() exits
the application if errors occur; to avoid this, use gtk_init_check(). 
gtk_init_check() 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 g_signal_connect(). 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 
#GtkFileSelectionDialog. 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 gtk_main(),
though it involves slightly more typing. See #GMainLoop in the GLib
documentation.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
See the GLib manual, especially #GMainLoop and signal-related
functions such as g_signal_connect().
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### FUNCTION gtk_set_locale ##### -->

<para>
</para>

@Returns: 


<!-- ##### FUNCTION gtk_disable_setlocale ##### -->
<para>

</para>



<!-- ##### FUNCTION gtk_get_default_language ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_parse_args ##### -->
<para>

</para>

@argc: 
@argv: 
@Returns: 


<!-- ##### FUNCTION gtk_init ##### -->
<para>
</para>

<note>
<para>
</para>
</note>

@argc: 
@argv: 


<!-- ##### FUNCTION gtk_init_check ##### -->
<para>
</para>

@argc: 
@argv: 
@Returns: 


<!-- ##### FUNCTION gtk_init_with_args ##### -->
<para>

</para>

@argc: 
@argv: 
@parameter_string: 
@entries: 
@translation_domain: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_get_option_group ##### -->
<para>

</para>

@open_default_display: 
@Returns: 


<!-- ##### FUNCTION gtk_exit ##### -->
<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>

@error_code: Return value to pass to the caller. This is dependent on the
target system but at least on Unix systems %0 means success.
@Deprecated: Use the standard exit() function instead.


<!-- ##### FUNCTION gtk_events_pending ##### -->
<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>

@Returns: %TRUE if any events are pending, %FALSE otherwise.


<!-- ##### FUNCTION gtk_main ##### -->
<para>
Runs the main loop until gtk_main_quit() is called. You can nest calls to
gtk_main(). In that case gtk_main_quit() will make the innermost invocation
of the main loop return.
</para>



<!-- ##### FUNCTION gtk_main_level ##### -->
<para>
Asks for the current nesting level of the main loop. This can be useful
when calling gtk_quit_add().
</para>

@Returns: the nesting level of the current invocation of the main loop.


<!-- ##### FUNCTION gtk_main_quit ##### -->
<para>
Makes the innermost invocation of the main loop return when it regains 
control.
</para>



<!-- ##### FUNCTION gtk_main_iteration ##### -->
<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 gtk_main_iteration_do() or check if any events are
pending with gtk_events_pending() first.
</para>

@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop.


<!-- ##### FUNCTION gtk_main_iteration_do ##### -->
<para>
Runs a single iteration of the mainloop. If no events are available either
return or block dependent on the value of @blocking. 
</para>

@blocking: %TRUE if you want GTK+ to block if no events are pending.
@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop.


<!-- ##### FUNCTION gtk_main_do_event ##### -->
<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 gtk_selection_incr_event().
</para></listitem>
<listitem><para>
  Then the event is passed on a stack so you can query the currently handled
  event with gtk_get_current_event(). 
</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 gtk_key_snooper_install() if you need this feature.
</para></listitem>
<listitem><para>
  After finishing the delivery the event is popped from the event stack.
</para></listitem>
</orderedlist>

@event: An event to process (normally) passed by GDK.


<!-- ##### USER_FUNCTION GtkModuleInitFunc ##### -->
<para>
Each GTK+ module must have a function gtk_module_init() with this prototype.
This function is called after loading the module with the @argc and @argv 
cleaned from any arguments that GTK+ handles itself.
</para>

@argc: Pointer to the number of arguments remaining after gtk_init().
@argv: Points to the argument vector.


<!-- ##### USER_FUNCTION GtkModuleDisplayInitFunc ##### -->
<para>

</para>

@display: 
@Since: 2.2


<!-- ##### FUNCTION gtk_true ##### -->
<para>
All this function does it to return %TRUE. 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>

@Returns: %TRUE


<!-- ##### FUNCTION gtk_false ##### -->
<para>