diff --git a/docs/reference/gtk/tmpl/gtkmain.sgml b/docs/reference/gtk/tmpl/gtkmain.sgml
index d75ab873c3..5ef24dce3e 100644
--- a/docs/reference/gtk/tmpl/gtkmain.sgml
+++ b/docs/reference/gtk/tmpl/gtkmain.sgml
@@ -2,59 +2,143 @@
General
-
+Mainloop and event handling
-
+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 (callbacks
) to be called whenever
+some event occurs and give control to the GTK mainloop (e.g. by calling
+gtk_main).
+
+ Typical <function>main</function> function for a GTK application
+
+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_showall (mainwin);
+
+ /* Let the user interact with our application */
+ gtk_main ();
+
+ /* The user lost interest */
+ gtk_exit (0);
+}
+
+
+
-
-
+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.
-@Returns:
+
+You should call this function before gtk_init to
+support internationalization of your GTK+ applications.
+
+
+@Returns: A string corresponding to the locale set.
-
+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. argc and
+argv are adjusted accordingly so your own code will
+never see those standard arguments.
-@argc:
-@argv:
+
+
+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 gtk_init_check
+instead.
+
+
+
+@argc: Address of the argc parameter of your
+main function. Changed if any arguments were
+handled.
+@argv: Address of the argv parameter of
+main. Any parameters understood by
+gtk_init are stripped before return.
-
+This function does the same work as gtk_init with only
+a single change: It does not terminate the program if the GUI can't be
+initialized. Instead it returns %FALSE on failure.
+
+
+This way the application can fall back to some other means of communication
+with the user - for example a curses or command line interface.
-@argc:
-@argv:
-@Returns:
+@argc: A reference to the argc of the main
+ function.
+@argv: A reference to the argv of the main
+ function.
+@Returns: %TRUE if the GUI has been successful initialized,
+%FALSE otherwise.
-
+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.
-@error_code:
+@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.
-
+Check if any events are pending. This can be used to update the GUI
+and invoke timeouts etc. while doing some time intensive computation.
-@Returns:
+
+ Updating the GUI during a long computation
+
+ /* computation going on */
+...
+ while (gtk_events_pending ())
+ gtk_main_iteration ();
+...
+ /* computation continued */
+
+
+
+@Returns: %TRUE if any events are pending, %FALSE otherwise.
@@ -115,18 +199,53 @@ General
-
+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...
-@Returns:
+
+ A persistent window
+
+##include <gtk/gtk.h>
+
+int
+main (int argc, char **argv)
+{
+ GtkWidget *win, *but;
+
+ gtk_init( &argc, &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;
+}
+
+
+
+@Returns: %TRUE
-
+Analogical to gtk_true this function does nothing
+but always returns %FALSE.
-@Returns:
+@Returns: %FALSE