Commit b123bc41 authored by Matthias Clasen's avatar Matthias Clasen

Move docs for gtkmain inline

At the same time, introduce a gtkmainprivate.h header
and various other cleanups.

Based on a patch by Tadej Borovšak.
https://bugzilla.gnome.org/show_bug.cgi?id=617471
parent 98440ad0
......@@ -23,6 +23,7 @@ gtkentry.sgml
gtkentrybuffer.sgml
gtkeventbox.sgml
gtkexpander.sgml
gtkfeatures.sgml
gtkhbox.sgml
gtkiconview.sgml
gtkimcontextsimple.sgml
......@@ -30,6 +31,7 @@ gtkimmulticontext.sgml
gtkitemfactory.sgml
gtklayout.sgml
gtklinkbutton.sgml
gtkmain.sgml
gtkmessagedialog.sgml
gtknotebook.sgml
gtkobject.sgml
......
<!-- ##### SECTION Title ##### -->
Version Information
<!-- ##### SECTION Short_Description ##### -->
Variables and functions to check the GTK+ version
<!-- ##### SECTION Long_Description ##### -->
<para>
GTK+ provides version information, primarily useful in configure checks
for builds that have a configure script. Applications will not
typically use the features described here.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION gtk_get_major_version ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_minor_version ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_micro_version ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_binary_age ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_interface_age ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_check_version ##### -->
<para>
</para>
@required_major:
@required_minor:
@required_micro:
@Returns:
<!-- ##### MACRO GTK_MAJOR_VERSION ##### -->
<para>
Like #gtk_major_version, but from the headers used at
application compile time, rather than from the library linked against
at application run time.
</para>
<!-- ##### MACRO GTK_MINOR_VERSION ##### -->
<para>
Like #gtk_minor_version, but from the headers used at
application compile time, rather than from the library linked against
at application run time.
</para>
<!-- ##### MACRO GTK_MICRO_VERSION ##### -->
<para>
Like #gtk_micro_version, but from the headers used at
application compile time, rather than from the library linked against
at application run time.
</para>
<!-- ##### MACRO GTK_BINARY_AGE ##### -->
<para>
Like #gtk_binary_age, but from the headers used at
application compile time, rather than from the library linked against
at application run time.
</para>
<!-- ##### MACRO GTK_INTERFACE_AGE ##### -->
<para>
Like #gtk_interface_age, but from the headers used at
application compile time, rather than from the library linked against
at application run time.
</para>
<!-- ##### MACRO GTK_CHECK_VERSION ##### -->
<para>
Returns %TRUE if the version of the GTK+ header files is the same
as or newer than the passed-in version.
</para>
@major: major version (e.g. 1 for version 1.2.5)
@minor: minor version (e.g. 2 for version 1.2.5)
@micro: micro version (e.g. 5 for version 1.2.5)
<!-- ##### 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 ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION gtk_set_locale ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_disable_setlocale ##### -->
<para>
</para>
@void:
<!-- ##### FUNCTION gtk_get_default_language ##### -->
<para>
</para>
@void:
@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_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>
@void:
@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>
@void:
<!-- ##### FUNCTION gtk_main_level ##### -->
<para>
Asks for the current nesting level of the main loop.
</para>
@void:
@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>
@void:
<!-- ##### 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>
@void:
@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>
@void:
@Returns: %TRUE
<!-- ##### FUNCTION gtk_false ##### -->
<para>
Analogical to gtk_true() this function does nothing
but always returns %FALSE.
</para>
@void:
@Returns: %FALSE
<!-- ##### FUNCTION gtk_grab_add ##### -->
<para>
Makes @widget 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 @widget is not sensitive, it is not set as the current grabbed
widget and this function does nothing.
</para>
@widget: The widget that grabs keyboard and pointer events.
<!-- ##### FUNCTION gtk_grab_get_current ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_grab_remove ##### -->
<para>
Removes the grab from the given widget. You have to pair calls to gtk_grab_add()
and gtk_grab_remove().
</para>
<para>
If @widget does not have the grab, this function does nothing.
</para>
@widget: The widget which gives up the grab.
<!-- ##### FUNCTION gtk_device_grab_add ##### -->
<para>
</para>
@widget:
@device:
@block_others:
<!-- ##### FUNCTION gtk_device_grab_remove ##### -->
<para>
</para>
@widget:
@device:
<!-- ##### USER_FUNCTION GtkFunction ##### -->
<para>
</para>
@data:
@Returns:
<!-- ##### USER_FUNCTION GtkCallbackMarshal ##### -->
<para>
</para>
@object:
@data:
@n_args:
@args:
<!-- ##### STRUCT GtkArg ##### -->
<para>
</para>
@type:
@name:
<!-- ##### MACRO GTK_PRIORITY_RESIZE ##### -->
<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
%GDK_PRIORITY_REDRAW to avoid resizing a widget which was just redrawn.
</para>
<!-- ##### FUNCTION gtk_key_snooper_install ##### -->
<para>
Installs a key snooper function, which will get called on all key events
before delivering them normally.
</para>
@snooper: a #GtkKeySnoopFunc.
@func_data: data to pass to @snooper.
@Returns: a unique id for this key snooper for use with gtk_key_snooper_remove().
<!-- ##### USER_FUNCTION GtkKeySnoopFunc ##### -->
<para>
Key snooper functions are called before normal event delivery.
They can be used to implement custom key event handling.
</para>
@grab_widget: the widget to which the event will be delivered.
@event: the key event.
@func_data: the @func_data supplied to gtk_key_snooper_install().
@Returns: %TRUE to stop further processing of @event, %FALSE to continue.
<!-- ##### FUNCTION gtk_key_snooper_remove ##### -->
<para>
Removes the key snooper function with the given id.
</para>
@snooper_handler_id: Identifies the key snooper to remove.
<!-- ##### FUNCTION gtk_get_current_event ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_current_event_time ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_current_event_state ##### -->
<para>
</para>
@state:
@Returns:
<!-- ##### FUNCTION gtk_get_current_event_device ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_get_event_widget ##### -->
<para>
</para>
@event:
@Returns:
<!-- ##### FUNCTION gtk_propagate_event ##### -->
<para>
</para>
@widget:
@event:
......@@ -394,6 +394,7 @@ gtk_private_h_sources = \
gtkimcontextsimpleseqs.h \
gtkintl.h \
gtkkeyhash.h \
gtkmainprivate.h \
gtkmenuprivate.h \
gtkmenuitemprivate.h \
gtkmenushellprivate.h \
......
......@@ -51,7 +51,7 @@
#include "gtkvbox.h"
#include "gtkiconfactory.h"
#include "gtkshow.h"
#include "gtkmain.h"
#include "gtkmainprivate.h"
#include "gtkmessagedialog.h"
#include "gtktogglebutton.h"
#include "gtktypebuiltins.h"
......
......@@ -30,10 +30,10 @@
#include "gtkaccelgroup.h"
#include "gtkaccelgroupprivate.h"
#include "gtkaccellabel.h" /* For _gtk_accel_label_class_get_accelerator_label */
#include "gtkaccellabel.h"
#include "gtkaccelmap.h"
#include "gtkintl.h"
#include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */
#include "gtkmainprivate.h"
#include "gtkmarshalers.h"
......@@ -43,7 +43,7 @@
* @Title: Accelerator Groups
* @See_also:gtk_window_add_accel_group(), gtk_accel_map_change_entry(),
* gtk_item_factory_new(), gtk_label_new_with_mnemonic()
*
*
* A #GtkAccelGroup represents a group of keyboard accelerators,
* typically attached to a toplevel #GtkWindow (with
* gtk_window_add_accel_group()). Usually you won't need to create a
......
......@@ -35,7 +35,7 @@
#include "gtkvbox.h"
#include "gtkwindow.h"
#include "gtkentry.h"
#include "gtkmain.h"
#include "gtkmainprivate.h"
#include "gtkmarshalers.h"
#include "gtkprivate.h"
......
......@@ -20,7 +20,7 @@
#include "config.h"
#include <string.h>
#include "gtkimcontext.h"
#include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */
#include "gtkmainprivate.h"
#include "gtkmarshalers.h"
#include "gtkintl.h"
......