callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move docs for gtkmain inline

Browse Source 
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
This commit is contained in:
Matthias Clasen 2011-01-04 17:32:12 -05:00
parent 98440ad031
commit b123bc41fd
28 changed files with 923 additions and 1202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -23,6 +23,7 @@ gtkentry.sgml
gtkentrybuffer.sgml gtkentrybuffer.sgml
gtkeventbox.sgml gtkeventbox.sgml
gtkexpander.sgml gtkexpander.sgml
gtkfeatures.sgml
gtkhbox.sgml gtkhbox.sgml
gtkiconview.sgml gtkiconview.sgml
gtkimcontextsimple.sgml gtkimcontextsimple.sgml
@ -30,6 +31,7 @@ gtkimmulticontext.sgml
gtkitemfactory.sgml gtkitemfactory.sgml
gtklayout.sgml gtklayout.sgml
gtklinkbutton.sgml gtklinkbutton.sgml
gtkmain.sgml
gtkmessagedialog.sgml gtkmessagedialog.sgml
gtknotebook.sgml gtknotebook.sgml
gtkobject.sgml gtkobject.sgml

135
docs/reference/gtk/tmpl/gtkfeatures.sgml
View File

@ -1,135 +0,0 @@
<!-- ##### 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)

554
docs/reference/gtk/tmpl/gtkmain.sgml
View File

@ -1,554 +0,0 @@
<!-- ##### 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:

1
gtk/Makefile.am
View File

@ -394,6 +394,7 @@ gtk_private_h_sources = \
gtkimcontextsimpleseqs.h \ gtkimcontextsimpleseqs.h \
gtkintl.h \ gtkintl.h \
gtkkeyhash.h \ gtkkeyhash.h \
gtkmainprivate.h \
gtkmenuprivate.h \ gtkmenuprivate.h \
gtkmenuitemprivate.h \ gtkmenuitemprivate.h \
gtkmenushellprivate.h \ gtkmenushellprivate.h \

2
gtk/gtkaboutdialog.c
View File

@ -51,7 +51,7 @@
#include "gtkvbox.h" #include "gtkvbox.h"
#include "gtkiconfactory.h" #include "gtkiconfactory.h"
#include "gtkshow.h" #include "gtkshow.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmessagedialog.h" #include "gtkmessagedialog.h"
#include "gtktogglebutton.h" #include "gtktogglebutton.h"
#include "gtktypebuiltins.h" #include "gtktypebuiltins.h"

4
gtk/gtkaccelgroup.c
View File

@ -30,10 +30,10 @@
#include "gtkaccelgroup.h" #include "gtkaccelgroup.h"
#include "gtkaccelgroupprivate.h" #include "gtkaccelgroupprivate.h"
#include "gtkaccellabel.h" /* For _gtk_accel_label_class_get_accelerator_label */ #include "gtkaccellabel.h"
#include "gtkaccelmap.h" #include "gtkaccelmap.h"
#include "gtkintl.h" #include "gtkintl.h"
#include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */ #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"

2
gtk/gtkentrycompletion.c
View File

@ -35,7 +35,7 @@
#include "gtkvbox.h" #include "gtkvbox.h"
#include "gtkwindow.h" #include "gtkwindow.h"
#include "gtkentry.h" #include "gtkentry.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkprivate.h" #include "gtkprivate.h"

2
gtk/gtkimcontext.c
View File

@ -20,7 +20,7 @@
#include "config.h" #include "config.h"
#include <string.h> #include <string.h>
#include "gtkimcontext.h" #include "gtkimcontext.h"
#include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */ #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkintl.h" #include "gtkintl.h"

2
gtk/gtkimmodule.c
View File

@ -35,7 +35,7 @@
#include "gtkimmodule.h" #include "gtkimmodule.h"
#include "gtkimcontextsimple.h" #include "gtkimcontextsimple.h"
#include "gtksettings.h" #include "gtksettings.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkrc.h" #include "gtkrc.h"
#include "gtkintl.h" #include "gtkintl.h"

2
gtk/gtklabel.c
View File

@ -31,7 +31,7 @@
#include "gtklabel.h" #include "gtklabel.h"
#include "gtkaccellabel.h" #include "gtkaccellabel.h"
#include "gtkdnd.h" #include "gtkdnd.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkpango.h" #include "gtkpango.h"
#include "gtkwindow.h" #include "gtkwindow.h"

2
gtk/gtklinkbutton.c
View File

@ -55,7 +55,7 @@
#include "gtkdnd.h" #include "gtkdnd.h"
#include "gtkimagemenuitem.h" #include "gtkimagemenuitem.h"
#include "gtklabel.h" #include "gtklabel.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkmenu.h" #include "gtkmenu.h"
#include "gtkmenuitem.h" #include "gtkmenuitem.h"

483
gtk/gtkmain.c
View File

@ -24,9 +24,74 @@
* GTK+ at ftp://ftp.gtk.org/pub/gtk/. * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/ */
/**
* SECTION:gtkmain
* @Short_description: Library initialization, main event loop, and events
* @Title: Main loop and Events
* @See_also:See the GLib manual, especially #GMainLoop and signal-related
* functions such as g_signal_connect()
*
* 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() macro 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.
*
* 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.
*
* 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>.
*
* 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><![CDATA[
* int
* main (int argc, char **argv)
* {
* /&ast; Initialize i18n support &ast;/
* gtk_set_locale ();
*
* /&ast; Initialize the widget set &ast;/
* gtk_init (&argc, &argv);
*
* /&ast; Create the main window &ast;/
* mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL);
*
* /&ast; Set up our GUI elements &ast;/
* ...
*
* /&ast; Show the application window &ast;/
* gtk_widget_show_all (mainwin);
*
* /&ast; Enter the main event loop, and wait for user interaction &ast;/
* gtk_main ();
*
* /&ast; The user lost interest &ast;/
* 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.
*/
#include "config.h" #include "config.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include <glib.h> #include <glib.h>
#include "gdk/gdk.h" #include "gdk/gdk.h"
@ -189,8 +254,8 @@ static const GDebugKey gtk_debug_keys[] = {
/** /**
* gtk_get_major_version: * gtk_get_major_version:
* *
* Returns the major version number of the GTK+ library. (e.g. in GTK+ version * Returns the major version number of the GTK+ library.
* 3.1.5 this is 3.) * (e.g. in GTK+ version 3.1.5 this is 3.)
* *
* This function is in the library, so it represents the GTK+ library * This function is in the library, so it represents the GTK+ library
* your code is running against. Contrast with the #GTK_MAJOR_VERSION * your code is running against. Contrast with the #GTK_MAJOR_VERSION
@ -210,8 +275,8 @@ gtk_get_major_version (void)
/** /**
* gtk_get_minor_version: * gtk_get_minor_version:
* *
* Returns the minor version number of the GTK+ library. (e.g. in GTK+ version * Returns the minor version number of the GTK+ library.
* 3.1.5 this is 1.) * (e.g. in GTK+ version 3.1.5 this is 1.)
* *
* This function is in the library, so it represents the GTK+ library * This function is in the library, so it represents the GTK+ library
* your code is are running against. Contrast with the * your code is are running against. Contrast with the
@ -231,8 +296,8 @@ gtk_get_minor_version (void)
/** /**
* gtk_get_micro_version: * gtk_get_micro_version:
* *
* Returns the micro version number of the GTK+ library. (e.g. in GTK+ version * Returns the micro version number of the GTK+ library.
* 3.1.5 this is 5.) * (e.g. in GTK+ version 3.1.5 this is 5.)
* *
* This function is in the library, so it represents the GTK+ library * This function is in the library, so it represents the GTK+ library
* your code is are running against. Contrast with the * your code is are running against. Contrast with the
@ -252,10 +317,9 @@ gtk_get_micro_version (void)
/** /**
* gtk_get_binary_age: * gtk_get_binary_age:
* *
* Returns the binary age as passed to * Returns the binary age as passed to <application>libtool</application>
* <application>libtool</application> when building the GTK+ library * when building the GTK+ library the process is running against.
* the process is running against. If * If <application>libtool</application> means nothing to you, don't
* <application>libtool</application> means nothing to you, don't
* worry about it. * worry about it.
* *
* Returns: the binary age of the GTK+ library. * Returns: the binary age of the GTK+ library.
@ -271,10 +335,9 @@ gtk_get_binary_age (void)
/** /**
* gtk_get_interface_age: * gtk_get_interface_age:
* *
* Returns the interface age as passed to * Returns the interface age as passed to <application>libtool</application>
* <application>libtool</application> when building the GTK+ library * when building the GTK+ library the process is running against.
* the process is running against. If * If <application>libtool</application> means nothing to you, don't
* <application>libtool</application> means nothing to you, don't
* worry about it. * worry about it.
* *
* Returns: the interface age of the GTK+ library. * Returns: the interface age of the GTK+ library.
@ -289,9 +352,9 @@ gtk_get_interface_age (void)
/** /**
* gtk_check_version: * gtk_check_version:
* @required_major: the required major version. * @required_major: the required major version
* @required_minor: the required minor version. * @required_minor: the required minor version
* @required_micro: the required micro version. * @required_micro: the required micro version
* *
* Checks that the GTK+ library in use is compatible with the * Checks that the GTK+ library in use is compatible with the
* given version. Generally you would pass in the constants * given version. Generally you would pass in the constants
@ -320,7 +383,7 @@ gtk_get_interface_age (void)
* given version, or a string describing the version mismatch. * given version, or a string describing the version mismatch.
* The returned string is owned by GTK+ and should not be modified * The returned string is owned by GTK+ and should not be modified
* or freed. * or freed.
**/ */
const gchar* const gchar*
gtk_check_version (guint required_major, gtk_check_version (guint required_major,
guint required_minor, guint required_minor,
@ -877,7 +940,9 @@ gtk_set_debug_flags (guint flags)
* when parsing the commandline arguments * when parsing the commandline arguments
* *
* Returns a #GOptionGroup for the commandline arguments recognized * Returns a #GOptionGroup for the commandline arguments recognized
* by GTK+ and GDK. You should add this group to your #GOptionContext * by GTK+ and GDK.
*
* You should add this group to your #GOptionContext
* with g_option_context_add_group(), if you are using * with g_option_context_add_group(), if you are using
* g_option_context_parse() to parse your commandline arguments. * g_option_context_parse() to parse your commandline arguments.
* *
@ -909,12 +974,12 @@ gtk_get_option_group (gboolean open_default_display)
/** /**
* gtk_init_with_args: * gtk_init_with_args:
* @argc: a pointer to the number of command line arguments. * @argc: a pointer to the number of command line arguments
* @argv: a pointer to the array of command line arguments. * @argv: a pointer to the array of command line arguments
* @parameter_string: a string which is displayed in * @parameter_string: a string which is displayed in
* the first line of <option>--help</option> output, after * the first line of <option>--help</option> output, after
* <literal><replaceable>programname</replaceable> [OPTION...]</literal> * <literal><replaceable>programname</replaceable> [OPTION...]</literal>
* @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s * @entries: a %NULL-terminated array of #GOptionEntrys
* describing the options of your program * describing the options of your program
* @translation_domain: a translation domain to use for translating * @translation_domain: a translation domain to use for translating
* the <option>--help</option> output for the options in @entries * the <option>--help</option> output for the options in @entries
@ -927,8 +992,8 @@ gtk_get_option_group (gboolean open_default_display)
* <option>--help</option> output. Note that your program will * <option>--help</option> output. Note that your program will
* be terminated after writing out the help output. * be terminated after writing out the help output.
* *
* Returns: %TRUE if the GUI has been successfully initialized, * Returns: %TRUE if the windowing system has been successfully
* %FALSE otherwise. * initialized, %FALSE otherwise
* *
* Since: 2.6 * Since: 2.6
*/ */
@ -983,8 +1048,8 @@ gtk_init_with_args (gint *argc,
* There is no need to call this function explicitely if you are using * There is no need to call this function explicitely if you are using
* gtk_init(), or gtk_init_check(). * gtk_init(), or gtk_init_check().
* *
* Return value: %TRUE if initialization succeeded, otherwise %FALSE. * Return value: %TRUE if initialization succeeded, otherwise %FALSE
**/ */
gboolean gboolean
gtk_parse_args (int *argc, gtk_parse_args (int *argc,
char ***argv) char ***argv)
@ -1023,21 +1088,23 @@ gtk_parse_args (int *argc,
/** /**
* gtk_init_check: * gtk_init_check:
* @argc: (inout): Address of the <parameter>argc</parameter> parameter of your * @argc: (inout): Address of the <parameter>argc</parameter> parameter of
* main() function. Changed if any arguments were handled. * your main() function. Changed if any arguments were handled
* @argv: (array length=argc) (inout) (allow-none): Address of the <parameter>argv</parameter> parameter of main(). * @argv: (array length=argc) (inout) (allow-none): Address of the
* Any parameters understood by gtk_init() are stripped before return. * <parameter>argv</parameter> parameter of main()
* Any parameters understood by gtk_init() are stripped before return
* *
* This function does the same work as gtk_init() with only * This function does the same work as gtk_init() with only a single
* a single change: It does not terminate the program if the GUI can't be * change: It does not terminate the program if the windowing system
* initialized. Instead it returns %FALSE on failure. * can't be initialized. Instead it returns %FALSE on failure.
* *
* This way the application can fall back to some other means of communication * This way the application can fall back to some other means of
* with the user - for example a curses or command line interface. * communication with the user - for example a curses or command line
* interface.
* *
* Return value: %TRUE if the GUI has been successfully initialized, * Return value: %TRUE if the windowing system has been successfully
* %FALSE otherwise. * initialized, %FALSE otherwise
**/ */
gboolean gboolean
gtk_init_check (int *argc, gtk_init_check (int *argc,
char ***argv) char ***argv)
@ -1157,7 +1224,7 @@ gtk_init_check_abi_check (int *argc, char ***argv, int num_checks, size_t sizeof
#endif #endif
/** /*
* _gtk_get_lc_ctype: * _gtk_get_lc_ctype:
* *
* Return the Unix-style locale string for the language currently in * Return the Unix-style locale string for the language currently in
@ -1226,18 +1293,26 @@ _gtk_get_lc_ctype (void)
* locale. It determines, for example, whether GTK+ uses the * locale. It determines, for example, whether GTK+ uses the
* right-to-left or left-to-right text direction. * right-to-left or left-to-right text direction.
* *
* This function is equivalent to pango_language_get_default(). See * This function is equivalent to pango_language_get_default().
* that function for details. * See that function for details.
* *
* Return value: the default language as a #PangoLanguage, must not be * Return value: the default language as a #PangoLanguage,
* freed * must not be freed
**/ */
PangoLanguage * PangoLanguage *
gtk_get_default_language (void) gtk_get_default_language (void)
{ {
return pango_language_get_default (); return pango_language_get_default ();
} }
/**
* gtk_main:
*
* 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.
*/
void void
gtk_main (void) gtk_main (void)
{ {
@ -1272,12 +1347,26 @@ gtk_main (void)
} }
} }
/**
* gtk_main_level:
*
* Asks for the current nesting level of the main loop.
*
* Returns: the nesting level of the current invocation
* of the main loop
*/
guint guint
gtk_main_level (void) gtk_main_level (void)
{ {
return gtk_main_loop_level; return gtk_main_loop_level;
} }
/**
* gtk_main_quit:
*
* Makes the innermost invocation of the main loop return
* when it regains control.
*/
void void
gtk_main_quit (void) gtk_main_quit (void)
{ {
@ -1286,6 +1375,28 @@ gtk_main_quit (void)
g_main_loop_quit (main_loops->data); g_main_loop_quit (main_loops->data);
} }
/**
* gtk_events_pending:
*
* Checks if any events are pending.
*
* This can be used to update the UI and invoke timeouts etc.
* while doing some time intensive computation.
*
* <example>
* <title>Updating the UI during a long computation</title>
* <programlisting><![CDATA[
* /&ast; computation going on &ast;/
* ...
* while (gtk_events_pending ())
* gtk_main_iteration ();
* ...
* /&ast; computation continued &ast;/
* ]]></programlisting>
* </example>
*
* Returns: %TRUE if any events are pending, %FALSE otherwise
*/
gboolean gboolean
gtk_events_pending (void) gtk_events_pending (void)
{ {
@ -1298,6 +1409,19 @@ gtk_events_pending (void)
return result; return result;
} }
/**
* gtk_main_iteration:
*
* 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.
*
* Returns: %TRUE if gtk_main_quit() has been called for the
* innermost mainloop
*/
gboolean gboolean
gtk_main_iteration (void) gtk_main_iteration (void)
{ {
@ -1311,6 +1435,17 @@ gtk_main_iteration (void)
return TRUE; return TRUE;
} }
/**
* gtk_main_iteration_do:
* @blocking: %TRUE if you want GTK+ to block if no events are pending
*
* Runs a single iteration of the mainloop.
* If no events are available either return or block depending on
* the value of @blocking.
*
* Returns: %TRUE if gtk_main_quit() has been called for the
* innermost mainloop
*/
gboolean gboolean
gtk_main_iteration_do (gboolean blocking) gtk_main_iteration_do (gboolean blocking)
{ {
@ -1324,8 +1459,7 @@ gtk_main_iteration_do (gboolean blocking)
return TRUE; return TRUE;
} }
/* private libgtk to libgdk interfaces /* private libgtk to libgdk interfaces */
*/
gboolean gdk_device_grab_info_libgtk_only (GdkDisplay *display, gboolean gdk_device_grab_info_libgtk_only (GdkDisplay *display,
GdkDevice *device, GdkDevice *device,
GdkWindow **grab_window, GdkWindow **grab_window,
@ -1440,6 +1574,66 @@ rewrite_event_for_grabs (GdkEvent *event)
return NULL; return NULL;
} }
/**
* gtk_main_do_event:
* @event: An event to process (normally passed by GDK)
*
* 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.
*
* 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:
*
* <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 pushed onto 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>
*/
void void
gtk_main_do_event (GdkEvent *event) gtk_main_do_event (GdkEvent *event)
{ {
@ -1463,19 +1657,18 @@ gtk_main_do_event (GdkEvent *event)
} }
/* Find the widget which got the event. We store the widget /* Find the widget which got the event. We store the widget
* in the user_data field of GdkWindow's. * in the user_data field of GdkWindow's. Ignore the event
* Ignore the event if we don't have a widget for it, except * if we don't have a widget for it, except for GDK_PROPERTY_NOTIFY
* for GDK_PROPERTY_NOTIFY events which are handled specialy. * events which are handled specially. Though this happens rarely,
* Though this happens rarely, bogus events can occour * bogus events can occur for e.g. destroyed GdkWindows.
* for e.g. destroyed GdkWindows.
*/ */
event_widget = gtk_get_event_widget (event); event_widget = gtk_get_event_widget (event);
if (!event_widget) if (!event_widget)
{ {
/* To handle selection INCR transactions, we select /* To handle selection INCR transactions, we select
* PropertyNotify events on the requestor window and create * PropertyNotify events on the requestor window and create
* a corresponding (fake) GdkWindow so that events get * a corresponding (fake) GdkWindow so that events get here.
* here. There won't be a widget though, so we have to handle * There won't be a widget though, so we have to handle
* them specially * them specially
*/ */
if (event->type == GDK_PROPERTY_NOTIFY) if (event->type == GDK_PROPERTY_NOTIFY)
@ -1498,8 +1691,7 @@ gtk_main_do_event (GdkEvent *event)
window_group = gtk_main_get_window_group (event_widget); window_group = gtk_main_get_window_group (event_widget);
device = gdk_event_get_device (event); device = gdk_event_get_device (event);
/* check whether there is a (device) grab in effect... /* check whether there is a (device) grab in effect... */
*/
if (device) if (device)
grab_widget = gtk_window_group_get_current_device_grab (window_group, device); grab_widget = gtk_window_group_get_current_device_grab (window_group, device);
@ -1515,7 +1707,9 @@ gtk_main_do_event (GdkEvent *event)
gtk_widget_is_ancestor (event_widget, grab_widget))) gtk_widget_is_ancestor (event_widget, grab_widget)))
grab_widget = event_widget; grab_widget = event_widget;
/* If the widget receiving events is actually blocked by another device GTK+ grab */ /* If the widget receiving events is actually blocked by another
* device GTK+ grab
*/
if (device && if (device &&
_gtk_window_group_widget_is_blocked_for_device (window_group, grab_widget, device)) _gtk_window_group_widget_is_blocked_for_device (window_group, grab_widget, device))
{ {
@ -1577,10 +1771,11 @@ gtk_main_do_event (GdkEvent *event)
else else
{ {
/* The app may paint with a previously allocated cairo_t, /* The app may paint with a previously allocated cairo_t,
which will draw directly to the window. We can't catch cairo * which will draw directly to the window. We can't catch cairo
draw operations to automatically flush the window, thus we * draw operations to automatically flush the window, thus we
need to explicitly flush any outstanding moves or double * need to explicitly flush any outstanding moves or double
buffering */ * buffering
*/
gdk_window_flush (event->any.window); gdk_window_flush (event->any.window);
gtk_widget_send_expose (event_widget, event); gtk_widget_send_expose (event_widget, event);
} }
@ -1701,12 +1896,63 @@ gtk_main_do_event (GdkEvent *event)
gdk_event_free (rewritten_event); gdk_event_free (rewritten_event);
} }
/**
* gtk_true:
*
* 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...
*
* <example>
* <title>A persistent window</title>
* <programlisting><![CDATA[
* #include <gtk/gtk.h>
*
* 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
*/
gboolean gboolean
gtk_true (void) gtk_true (void)
{ {
return TRUE; return TRUE;
} }
/**
* gtk_false:
*
* Analogical to gtk_true(), this function does nothing
* but always returns %FALSE.
*
* Returns: %FALSE
*/
gboolean gboolean
gtk_false (void) gtk_false (void)
{ {
@ -1895,6 +2141,19 @@ gtk_grab_notify (GtkWindowGroup *group,
g_object_unref (group); g_object_unref (group);
} }
/**
* gtk_grab_add:
* @widget: The widget that grabs keyboard and pointer events
*
* 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.
*
* If @widget is not sensitive, it is not set as the current
* grabbed widget and this function does nothing.
*/
void void
gtk_grab_add (GtkWidget *widget) gtk_grab_add (GtkWidget *widget)
{ {
@ -1936,6 +2195,16 @@ gtk_grab_get_current (void)
return gtk_window_group_get_current_grab (group); return gtk_window_group_get_current_grab (group);
} }
/**
* gtk_grab_remove:
* @widget: The widget which gives up the grab
*
* Removes the grab from the given widget.
*
* You have to pair calls to gtk_grab_add() and gtk_grab_remove().
*
* If @widget does not have the grab, this function does nothing.
*/
void void
gtk_grab_remove (GtkWidget *widget) gtk_grab_remove (GtkWidget *widget)
{ {
@ -1970,7 +2239,7 @@ gtk_grab_remove (GtkWidget *widget)
* unable to interact with @widget during the grab. * unable to interact with @widget during the grab.
* *
* Since: 3.0 * Since: 3.0
**/ */
void void
gtk_device_grab_add (GtkWidget *widget, gtk_device_grab_add (GtkWidget *widget,
GdkDevice *device, GdkDevice *device,
@ -1996,11 +2265,13 @@ gtk_device_grab_add (GtkWidget *widget,
* @widget: a #GtkWidget * @widget: a #GtkWidget
* @device: a #GdkDevice * @device: a #GdkDevice
* *
* Removes a device grab from the given widget. You have to pair calls * Removes a device grab from the given widget.
* to gtk_device_grab_add() and gtk_device_grab_remove(). *
* You have to pair calls to gtk_device_grab_add() and
* gtk_device_grab_remove().
* *
* Since: 3.0 * Since: 3.0
**/ */
void void
gtk_device_grab_remove (GtkWidget *widget, gtk_device_grab_remove (GtkWidget *widget,
GdkDevice *device) GdkDevice *device)
@ -2018,6 +2289,17 @@ gtk_device_grab_remove (GtkWidget *widget,
gtk_grab_notify (group, device, widget, new_grab_widget, FALSE); gtk_grab_notify (group, device, widget, new_grab_widget, FALSE);
} }
/**
* gtk_key_snooper_install:
* @snooper: a #GtkKeySnoopFunc
* @func_data: data to pass to @snooper
*
* Installs a key snooper function, which will get called on all
* key events before delivering them normally.
*
* Returns: a unique id for this key snooper for use with
* gtk_key_snooper_remove().
*/
guint guint
gtk_key_snooper_install (GtkKeySnoopFunc snooper, gtk_key_snooper_install (GtkKeySnoopFunc snooper,
gpointer func_data) gpointer func_data)
@ -2036,6 +2318,12 @@ gtk_key_snooper_install (GtkKeySnoopFunc snooper,
return data->id; return data->id;
} }
/**
* gtk_key_snooper_remove:
* @snooper_handler_id: Identifies the key snooper to remove
*
* Removes the key snooper function with the given id.
*/
void void
gtk_key_snooper_remove (guint snooper_id) gtk_key_snooper_remove (guint snooper_id)
{ {
@ -2082,14 +2370,16 @@ gtk_invoke_key_snoopers (GtkWidget *grab_widget,
/** /**
* gtk_get_current_event: * gtk_get_current_event:
* *
* Obtains a copy of the event currently being processed by GTK+. For * Obtains a copy of the event currently being processed by GTK+.
* example, if you get a "clicked" signal from #GtkButton, the current
* event will be the #GdkEventButton that triggered the "clicked"
* signal. The returned event must be freed with gdk_event_free().
* If there is no current event, the function returns %NULL.
* *
* Return value: a copy of the current event, or %NULL if no current event. * For example, if you are handling a #GtkButton::clicked signal,
**/ * the current event will be the #GdkEventButton that triggered
* the ::clicked signal.
*
* Return value: a copy of the current event, or %NULL if there is
* no current event. The returned event must be freed with
* gdk_event_free().
*/
GdkEvent* GdkEvent*
gtk_get_current_event (void) gtk_get_current_event (void)
{ {
@ -2102,11 +2392,12 @@ gtk_get_current_event (void)
/** /**
* gtk_get_current_event_time: * gtk_get_current_event_time:
* *
* If there is a current event and it has a timestamp, return that * If there is a current event and it has a timestamp,
* timestamp, otherwise return %GDK_CURRENT_TIME. * return that timestamp, otherwise return %GDK_CURRENT_TIME.
* *
* Return value: the timestamp from the current event, or %GDK_CURRENT_TIME. * Return value: the timestamp from the current event,
**/ * or %GDK_CURRENT_TIME.
*/
guint32 guint32
gtk_get_current_event_time (void) gtk_get_current_event_time (void)
{ {
@ -2124,8 +2415,9 @@ gtk_get_current_event_time (void)
* that state field in @state and return %TRUE, otherwise return * that state field in @state and return %TRUE, otherwise return
* %FALSE. * %FALSE.
* *
* Return value: %TRUE if there was a current event and it had a state field * Return value: %TRUE if there was a current event and it
**/ * had a state field
*/
gboolean gboolean
gtk_get_current_event_state (GdkModifierType *state) gtk_get_current_event_state (GdkModifierType *state)
{ {
@ -2147,7 +2439,7 @@ gtk_get_current_event_state (GdkModifierType *state)
* device, otherwise return %NULL. * device, otherwise return %NULL.
* *
* Returns: (transfer none): a #GdkDevice, or %NULL * Returns: (transfer none): a #GdkDevice, or %NULL
**/ */
GdkDevice * GdkDevice *
gtk_get_current_event_device (void) gtk_get_current_event_device (void)
{ {
@ -2167,7 +2459,7 @@ gtk_get_current_event_device (void)
* *
* Return value: (transfer none): the widget that originally * Return value: (transfer none): the widget that originally
* received @event, or %NULL * received @event, or %NULL
**/ */
GtkWidget* GtkWidget*
gtk_get_event_widget (GdkEvent *event) gtk_get_event_widget (GdkEvent *event)
{ {
@ -2191,23 +2483,24 @@ gtk_get_event_widget (GdkEvent *event)
* @event: an event * @event: an event
* *
* Sends an event to a widget, propagating the event to parent widgets * Sends an event to a widget, propagating the event to parent widgets
* if the event remains unhandled. Events received by GTK+ from GDK * if the event remains unhandled.
* normally begin in gtk_main_do_event(). Depending on the type of *
* event, existence of modal dialogs, grabs, etc., the event may be * Events received by GTK+ from GDK normally begin in gtk_main_do_event().
* propagated; if so, this function is used. gtk_propagate_event() * Depending on the type of event, existence of modal dialogs, grabs, etc.,
* calls gtk_widget_event() on each widget it decides to send the * the event may be propagated; if so, this function is used.
* event to. So gtk_widget_event() is the lowest-level function; it *
* simply emits the "event" and possibly an event-specific signal on a * gtk_propagate_event() calls gtk_widget_event() on each widget it
* widget. gtk_propagate_event() is a bit higher-level, and * decides to send the event to. So gtk_widget_event() is the lowest-level
* gtk_main_do_event() is the highest level. * function; it simply emits the #GtkWidget::event and possibly an
* event-specific signal on a widget. gtk_propagate_event() is a bit
* higher-level, and gtk_main_do_event() is the highest level.
* *
* All that said, you most likely don't want to use any of these * All that said, you most likely don't want to use any of these
* functions; synthesizing events is rarely needed. Consider asking on * functions; synthesizing events is rarely needed. There are almost
* the mailing list for better ways to achieve your goals. For * certainly better ways to achieve your goals. For example, use
* example, use gdk_window_invalidate_rect() or * gdk_window_invalidate_rect() or gtk_widget_queue_draw() instead
* gtk_widget_queue_draw() instead of making up expose events. * of making up expose events.
* */
**/
void void
gtk_propagate_event (GtkWidget *widget, gtk_propagate_event (GtkWidget *widget,
GdkEvent *event) GdkEvent *event)

37
gtk/gtkmain.h
View File

@ -41,15 +41,33 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/* Priorities for redrawing and resizing /**
* GTK_PRIORITY_RESIZE:
*
* Use this priority for functionality related to size allocation.
*
* 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.
*/ */
#define GTK_PRIORITY_RESIZE (G_PRIORITY_HIGH_IDLE + 10) #define GTK_PRIORITY_RESIZE (G_PRIORITY_HIGH_IDLE + 10)
/**
* GtkKeySnoopFunc:
* @grab_widget: the widget to which the event will be delivered
* @event: the key event
* @func_data: data supplied to gtk_key_snooper_install()
*
* Key snooper functions are called before normal event delivery.
* They can be used to implement custom key event handling.
*
* Returns: %TRUE to stop further processing of @event, %FALSE to continue.
*/
typedef gint (*GtkKeySnoopFunc) (GtkWidget *grab_widget, typedef gint (*GtkKeySnoopFunc) (GtkWidget *grab_widget,
GdkEventKey *event, GdkEventKey *event,
gpointer func_data); gpointer func_data);
/* Gtk version. /* GTK+ version
*/ */
guint gtk_get_major_version (void) G_GNUC_CONST; guint gtk_get_major_version (void) G_GNUC_CONST;
guint gtk_get_minor_version (void) G_GNUC_CONST; guint gtk_get_minor_version (void) G_GNUC_CONST;
@ -114,17 +132,11 @@ void gtk_disable_setlocale (void);
PangoLanguage *gtk_get_default_language (void); PangoLanguage *gtk_get_default_language (void);
gboolean gtk_events_pending (void); gboolean gtk_events_pending (void);
/* The following is the event func GTK+ registers with GDK
* we expose it mainly to allow filtering of events between
* GDK and GTK+.
*/
void gtk_main_do_event (GdkEvent *event); void gtk_main_do_event (GdkEvent *event);
void gtk_main (void); void gtk_main (void);
guint gtk_main_level (void); guint gtk_main_level (void);
void gtk_main_quit (void); void gtk_main_quit (void);
gboolean gtk_main_iteration (void); gboolean gtk_main_iteration (void);
/* gtk_main_iteration() calls gtk_main_iteration_do(TRUE) */
gboolean gtk_main_iteration_do (gboolean blocking); gboolean gtk_main_iteration_do (gboolean blocking);
gboolean gtk_true (void) G_GNUC_CONST; gboolean gtk_true (void) G_GNUC_CONST;
@ -151,18 +163,9 @@ GdkDevice * gtk_get_current_event_device (void);
GtkWidget *gtk_get_event_widget (GdkEvent *event); GtkWidget *gtk_get_event_widget (GdkEvent *event);
/* Private routines internal to GTK+
*/
void gtk_propagate_event (GtkWidget *widget, void gtk_propagate_event (GtkWidget *widget,
GdkEvent *event); GdkEvent *event);
gboolean _gtk_boolean_handled_accumulator (GSignalInvocationHint *ihint,
GValue *return_accu,
const GValue *handler_return,
gpointer dummy);
gchar *_gtk_get_lc_ctype (void);
G_END_DECLS G_END_DECLS

35
gtk/gtkmainprivate.h Normal file
View File

@ -0,0 +1,35 @@
/* GTK - The GIMP Toolkit
* Copyright (C) 2011 Red Hat, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#ifndef __GTK_MAIN_PRIVATE_H__
#define __GTK_MAIN_PRIVATE_H__
#include "gtkmain.h"
G_BEGIN_DECLS
gboolean _gtk_boolean_handled_accumulator (GSignalInvocationHint *ihint,
GValue *return_accu,
const GValue *handler_return,
gpointer dummy);
gchar *_gtk_get_lc_ctype (void);
G_END_DECLS
#endif /* __GTK_MAIN_PRIVATE_H__ */

2
gtk/gtkmenushell.c
View File

@ -29,7 +29,7 @@
#include "gtkbindings.h" #include "gtkbindings.h"
#include "gtkkeyhash.h" #include "gtkkeyhash.h"
#include "gtklabel.h" #include "gtklabel.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkmenubar.h" #include "gtkmenubar.h"
#include "gtkmenuitemprivate.h" #include "gtkmenuitemprivate.h"

32
gtk/gtkmodules.h
View File

@ -30,21 +30,29 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/**
/* Functions for use within GTK+ * GtkModuleInitFunc:
* @argc: Pointer to the number of arguments remaining after gtk_init()
* @argv: Points to the argument vector
*
* 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.
*/ */
gchar * _gtk_find_module (const gchar *name,
const gchar *type);
gchar **_gtk_get_module_path (const gchar *type);
void _gtk_modules_init (gint *argc,
gchar ***argv,
const gchar *gtk_modules_args);
void _gtk_modules_settings_changed (GtkSettings *settings,
const gchar *modules);
typedef void (*GtkModuleInitFunc) (gint *argc, typedef void (*GtkModuleInitFunc) (gint *argc,
gchar ***argv); gchar ***argv);
/**
* GtkModuleDisplayInitFunc:
* @display: an open #GdkDisplay
*
* A multihead-aware GTK+ module may have a gtk_module_display_init()
* function with this prototype. GTK+ calls this function for each
* opened display.
*
* Since: 2.2
*/
typedef void (*GtkModuleDisplayInitFunc) (GdkDisplay *display); typedef void (*GtkModuleDisplayInitFunc) (GdkDisplay *display);

1
gtk/gtkprintoperation.c
View File

@ -31,6 +31,7 @@
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkintl.h" #include "gtkintl.h"
#include "gtkprivate.h" #include "gtkprivate.h"
#include "gtkmainprivate.h"
#include "gtkmessagedialog.h" #include "gtkmessagedialog.h"
#include "gtktypebuiltins.h" #include "gtktypebuiltins.h"

14
gtk/gtkprivate.h
View File

@ -29,6 +29,8 @@
#include <glib.h> #include <glib.h>
#include "gtksettings.h"
G_BEGIN_DECLS G_BEGIN_DECLS
#ifdef G_OS_WIN32 #ifdef G_OS_WIN32
@ -69,6 +71,18 @@ gboolean _gtk_fnmatch (const char *pattern,
const char *string, const char *string,
gboolean no_leading_period); gboolean no_leading_period);
gchar *_gtk_get_lc_ctype (void);
gchar * _gtk_find_module (const gchar *name,
const gchar *type);
gchar **_gtk_get_module_path (const gchar *type);
void _gtk_modules_init (gint *argc,
gchar ***argv,
const gchar *gtk_modules_args);
void _gtk_modules_settings_changed (GtkSettings *settings,
const gchar *modules);
G_END_DECLS G_END_DECLS
#endif /* __GTK_PRIVATE_H__ */ #endif /* __GTK_PRIVATE_H__ */

2
gtk/gtkrange.c
View File

@ -30,7 +30,7 @@
#include <stdio.h> #include <stdio.h>
#include <math.h> #include <math.h>
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkorientable.h" #include "gtkorientable.h"
#include "gtkrange.h" #include "gtkrange.h"

2
gtk/gtksocket.c
View File

@ -31,7 +31,7 @@
#include <string.h> #include <string.h>
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtksizerequest.h" #include "gtksizerequest.h"
#include "gtkwindowprivate.h" #include "gtkwindowprivate.h"

2
gtk/gtkspinbutton.c
View File

@ -38,7 +38,7 @@
#include "gtkbindings.h" #include "gtkbindings.h"
#include "gtkspinbutton.h" #include "gtkspinbutton.h"
#include "gtkentryprivate.h" #include "gtkentryprivate.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtksettings.h" #include "gtksettings.h"
#include "gtkprivate.h" #include "gtkprivate.h"

2
gtk/gtktexttag.c
View File

@ -52,7 +52,7 @@
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtktexttag.h" #include "gtktexttag.h"
#include "gtktexttypes.h" #include "gtktexttypes.h"
#include "gtktexttagtable.h" #include "gtktexttagtable.h"

2
gtk/gtktoolbar.c
View File

@ -42,7 +42,7 @@
#include "gtkhbox.h" #include "gtkhbox.h"
#include "gtkimage.h" #include "gtkimage.h"
#include "gtklabel.h" #include "gtklabel.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkmenu.h" #include "gtkmenu.h"
#include "gtkorientable.h" #include "gtkorientable.h"

2
gtk/gtktoolitem.c
View File

@ -32,7 +32,7 @@
#include "gtksizerequest.h" #include "gtksizerequest.h"
#include "gtkactivatable.h" #include "gtkactivatable.h"
#include "gtkintl.h" #include "gtkintl.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkprivate.h" #include "gtkprivate.h"

2
gtk/gtktreeview.c
View File

@ -28,7 +28,7 @@
#include "gtktreednd.h" #include "gtktreednd.h"
#include "gtktreeprivate.h" #include "gtktreeprivate.h"
#include "gtkcellrenderer.h" #include "gtkcellrenderer.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkbuildable.h" #include "gtkbuildable.h"
#include "gtkbutton.h" #include "gtkbutton.h"

59
gtk/gtkversion.h.in
View File

@ -24,6 +24,16 @@
* GTK+ at ftp://ftp.gtk.org/pub/gtk/. * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/ */
/**
* SECTION:gtkfeatures
* @Short_description: Variables and functions to check the GTK+ version
* @Title: Version Information
*
* 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.
*/
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION) #if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
#error "Only <gtk/gtk.h> can be included directly." #error "Only <gtk/gtk.h> can be included directly."
#endif #endif
@ -31,16 +41,59 @@
#ifndef __GTK_VERSION_H__ #ifndef __GTK_VERSION_H__
#define __GTK_VERSION_H__ #define __GTK_VERSION_H__
/* compile time version /**
* GTK_MAJOR_VERSION:
*
* Like gtk_get_major_version(), but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/ */
#define GTK_MAJOR_VERSION (@GTK_MAJOR_VERSION@) #define GTK_MAJOR_VERSION (@GTK_MAJOR_VERSION@)
/**
* GTK_MINOR_VERSION:
*
* Like gtk_get_minor_version(), but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
#define GTK_MINOR_VERSION (@GTK_MINOR_VERSION@) #define GTK_MINOR_VERSION (@GTK_MINOR_VERSION@)
/**
* GTK_MICRO_VERSION:
*
* Like gtk_get_micro_version(), but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
#define GTK_MICRO_VERSION (@GTK_MICRO_VERSION@) #define GTK_MICRO_VERSION (@GTK_MICRO_VERSION@)
/**
* GTK_BINARY_AGE:
*
* Like gtk_get_binary_age(), but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
#define GTK_BINARY_AGE (@GTK_BINARY_AGE@) #define GTK_BINARY_AGE (@GTK_BINARY_AGE@)
/**
* GTK_INTERFACE_AGE:
*
* Like gtk_get_interface_age(), but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
#define GTK_INTERFACE_AGE (@GTK_INTERFACE_AGE@) #define GTK_INTERFACE_AGE (@GTK_INTERFACE_AGE@)
/* check whether a Gtk+ version equal to or greater than /**
* major.minor.micro is present. * GTK_CHECK_VERSION:
* @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)
*
* Returns %TRUE if the version of the GTK+ header files
* is the same as or newer than the passed-in version.
*/ */
#define GTK_CHECK_VERSION(major,minor,micro) \ #define GTK_CHECK_VERSION(major,minor,micro) \
(GTK_MAJOR_VERSION > (major) || \ (GTK_MAJOR_VERSION > (major) || \

2
gtk/gtkwidget.c
View File

@ -39,7 +39,7 @@
#include "gtkclipboard.h" #include "gtkclipboard.h"
#include "gtkiconfactory.h" #include "gtkiconfactory.h"
#include "gtkintl.h" #include "gtkintl.h"
#include "gtkmain.h" #include "gtkmainprivate.h"
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
#include "gtkrc.h" #include "gtkrc.h"
#include "gtkselection.h" #include "gtkselection.h"