
@c %start of fragment

@node Main loop and Events
@chapter Main loop and Events
Library initialization, main event loop, and events

@section Overview
Before using GTK+, you need to initialize it; initialization connects to the
window system display, and parses some standard command line arguments. The
@code{gtk-init} function initializes GTK+. @code{gtk-init} exits the application
if errors occur; to avoid this, use @code{gtk-init-check}. @code{gtk-init-check}
allows you to recover from a failed GTK+ initialization - you might start up
your application in text mode instead.

Like all GUI toolkits, GTK+ uses an event-driven programming model. When the
user is doing nothing, GTK+ sits in the @dfn{main loop} 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.

When widgets receive an event, they frequently emit one or more @dfn{signals}.
Signals notify your program that "something interesting happened" by invoking
functions you've connected to the signal with @code{g-signal-connect}. Functions
connected to a signal are often termed @dfn{callbacks}.

When your callbacks are invoked, you would typically take some action - for
example, when an Open button is clicked you might display a
@code{<gtk-file-selection-dialog>}. After a callback finishes, GTK+ will return
to the main loop and await more user input.

@example 

int 
main (int argc, char **argv)
@{
  /* Initialize i18n support */
  gtk_set_locale ();

  /* Initialize the widget set */
  gtk_init (&argc, &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;
@}
@end example

It's OK to use the GLib main loop directly instead of @code{gtk-main}, though it
involves slightly more typing. See @code{<g-main-loop>} in the GLib
documentation.

@section Usage
@include defuns-gtkmain.xml.texi

@c %end of fragment
