gtk2/docs/reference/gtk/tmpl/gtkmain.sgml

<!-- ##### SECTION Title ##### -->
General

<!-- ##### SECTION Short_Description ##### -->
Mainloop and event handling

<!-- ##### SECTION Long_Description ##### -->
<para>
GTK uses an event oriented programming model. While conventional C programs
have control over the program flow all the time this does not apply to 
applications written using GTK. Instead you set up some objects and 
register some functions (<quote>callbacks</quote>) to be called whenever 
some event occurs and give control to the GTK mainloop (e.g. by calling 
<function>gtk_main</function>).
</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_showall (mainwin);

  /* Let the user interact with our application */
  gtk_main ();

  /* The user lost interest */
  gtk_exit (0);
}
</programlisting>
</example>

<!-- ##### SECTION See_Also ##### -->
<para>
</para>

<!-- ##### FUNCTION gtk_set_locale ##### -->
<para>
Sets the current locale according to the program environment. This is the 
same as calling the libc function setlocale(LC_ALL, "") but also takes 
care of the locale specific setup of the windowing system used by GDK.
</para>

<para> 
You should call this function before <function>gtk_init</function> to 
support internationalization of your GTK+ applications.
</para>

@Returns: A string corresponding to the locale set. 


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

<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 <function>gtk_init_check</function> 
instead.
</para>
</note>

@argc: Address of the <parameter>argc</parameter> parameter of your 
<function>main</function> function. Changed if any arguments were 
handled.
@argv: Address of the <parameter>argv</parameter> parameter of 
<function>main</function>. Any parameters understood by <function>
gtk_init</function> are stripped before return.


<!-- ##### FUNCTION gtk_init_check ##### -->
<para>
This function does the same work as <function>gtk_init</function> with only 
a single change: It does not terminate the program if the GUI can't be 
initialized. Instead it returns %FALSE 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>

@argc: A reference to the <parameter>argc</parameter> of the <function>main
</function> function.
@argv: A reference to the <parameter>argv</parameter> of the <function>main
</function> function.
@Returns: %TRUE if the GUI has been successful initialized, 
%FALSE otherwise.


<!-- ##### FUNCTION gtk_exit ##### -->
<para>
Terminate the program and return 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 dependend on the
target system but at least on Unix systems %0 means 
success.


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

</para>



<!-- ##### FUNCTION gtk_main_level ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_main_quit ##### -->
<para>

</para>



<!-- ##### FUNCTION gtk_main_iteration ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_main_iteration_do ##### -->
<para>

</para>

@blocking: 
@Returns: 


<!-- ##### FUNCTION gtk_main_do_event ##### -->
<para>

</para>

@event: 


<!-- ##### USER_FUNCTION GtkModuleInitFunc ##### -->
<para>

</para>

@argc: 
@argv: 


<!-- ##### 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);
  gtk_signal_connect (GTK_OBJECT(win), "delete-event", 
                      (GtkSignalFunc) gtk_true, NULL);
  gtk_signal_connect (GTK_OBJECT(win), "destroy", 
		      (GtkSignalFunc) gtk_main_quit, NULL);

  but = gtk_button_new_with_label ("Close yourself. I mean it!");
  gtk_signal_connect_object (
		  GTK_OBJECT (but), "clicked", 
		  (GtkSignalFunc) gtk_object_destroy, (gpointer) 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>
Analogical to <function>gtk_true</function> this function does nothing 
but always returns %FALSE.
</para>

@Returns: %FALSE


<!-- ##### FUNCTION gtk_grab_add ##### -->
<para>

</para>

@widget: 


<!-- ##### FUNCTION gtk_grab_get_current ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_grab_remove ##### -->
<para>

</para>

@widget: 


<!-- ##### FUNCTION gtk_init_add ##### -->
<para>

</para>

@function: 
@data: 


<!-- ##### FUNCTION gtk_quit_add_destroy ##### -->
<para>

</para>

@main_level: 
@object: 


<!-- ##### FUNCTION gtk_quit_add ##### -->
<para>

</para>

@main_level: 
@function: 
@data: 
@Returns: 


<!-- ##### FUNCTION gtk_quit_add_full ##### -->
<para>

</para>

@main_level: 
@function: 
@marshal: 
@data: 
@destroy: 
@Returns: 


<!-- ##### FUNCTION gtk_quit_remove ##### -->
<para>

</para>

@quit_handler_id: 


<!-- ##### FUNCTION gtk_quit_remove_by_data ##### -->
<para>

</para>

@data: 


<!-- ##### FUNCTION gtk_timeout_add_full ##### -->
<para>

</para>

@interval: 
@function: 
@marshal: 
@data: 
@destroy: 
@Returns: 


<!-- ##### FUNCTION gtk_timeout_add ##### -->
<para>

</para>

@interval: 
@function: 
@data: 
@Returns: 


<!-- ##### FUNCTION gtk_timeout_remove ##### -->
<para>

</para>

@timeout_handler_id: 


<!-- ##### FUNCTION gtk_idle_add ##### -->
<para>

</para>

@function: 
@data: 
@Returns: 


<!-- ##### FUNCTION gtk_idle_add_priority ##### -->
<para>

</para>

@priority: 
@function: 
@data: 
@Returns: 


<!-- ##### FUNCTION gtk_idle_add_full ##### -->
<para>

</para>

@priority: 
@function: 
@marshal: 
@data: 
@destroy: 
@Returns: 


<!-- ##### FUNCTION gtk_idle_remove ##### -->
<para>

</para>

@idle_handler_id: 


<!-- ##### FUNCTION gtk_idle_remove_by_data ##### -->
<para>

</para>

@data: 


<!-- ##### FUNCTION gtk_input_add_full ##### -->
<para>

</para>

@source: 
@condition: 
@function: 
@marshal: 
@data: 
@destroy: 
@Returns: 


<!-- ##### FUNCTION gtk_input_remove ##### -->
<para>

</para>

@input_handler_id: 


<!-- ##### MACRO GTK_PRIORITY_REDRAW ##### -->
<para>

</para>



<!-- ##### MACRO GTK_PRIORITY_RESIZE ##### -->
<para>

</para>



<!-- ##### MACRO GTK_PRIORITY_HIGH ##### -->
<para>

</para>



<!-- ##### MACRO GTK_PRIORITY_INTERNAL ##### -->
<para>

</para>



<!-- ##### MACRO GTK_PRIORITY_DEFAULT ##### -->
<para>

</para>



<!-- ##### MACRO GTK_PRIORITY_LOW ##### -->
<para>

</para>



<!-- ##### FUNCTION gtk_key_snooper_install ##### -->
<para>

</para>

@snooper: 
@func_data: 
@Returns: 


<!-- ##### USER_FUNCTION GtkKeySnoopFunc ##### -->
<para>

</para>

@grab_widget: 
@event: 
@func_data: 
@Returns: 


<!-- ##### FUNCTION gtk_key_snooper_remove ##### -->
<para>

</para>

@snooper_handler_id: 


<!-- ##### FUNCTION gtk_get_current_event ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_get_event_widget ##### -->
<para>

</para>

@event: 
@Returns: 


<!-- ##### FUNCTION gtk_propagate_event ##### -->
<para>

</para>

@widget: 
@event: