1517 lines
77 KiB
HTML
1517 lines
77 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Main loop and Events: GTK+ 3 Reference Manual</title>
|
||
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
||
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
|
||
<link rel="up" href="gtkbase.html" title="Part III. GTK+ Core Reference">
|
||
<link rel="prev" href="gtkbase.html" title="Part III. GTK+ Core Reference">
|
||
<link rel="next" href="gtk3-Feature-Test-Macros.html" title="Version Information">
|
||
<meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
|
||
<link rel="stylesheet" href="style.css" type="text/css">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
|
||
<td width="100%" align="left" class="shortcuts">
|
||
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
|
||
<a href="#gtk3-General.description" class="shortcut">Description</a></span>
|
||
</td>
|
||
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
|
||
<td><a accesskey="u" href="gtkbase.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
|
||
<td><a accesskey="p" href="gtkbase.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
|
||
<td><a accesskey="n" href="gtk3-Feature-Test-Macros.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
|
||
</tr></table>
|
||
<div class="refentry">
|
||
<a name="gtk3-General"></a><div class="titlepage"></div>
|
||
<div class="refnamediv"><table width="100%"><tr>
|
||
<td valign="top">
|
||
<h2><span class="refentrytitle"><a name="gtk3-General.top_of_page"></a>Main loop and Events</span></h2>
|
||
<p>Main loop and Events — Library initialization, main event loop, and events</p>
|
||
</td>
|
||
<td class="gallery_image" valign="top" align="right"></td>
|
||
</tr></table></div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.functions"></a><h2>Functions</h2>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="functions_proto_type">
|
||
<col class="functions_proto_name">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-disable-setlocale" title="gtk_disable_setlocale ()">gtk_disable_setlocale</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<a href="https://developer.gnome.org/pango/pango-Scripts-and-Languages.html#PangoLanguage-struct"><span class="returnvalue">PangoLanguage</span></a> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-default-language" title="gtk_get_default_language ()">gtk_get_default_language</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<a class="link" href="GtkWidget.html#GtkTextDirection" title="enum GtkTextDirection"><span class="returnvalue">GtkTextDirection</span></a>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-locale-direction" title="gtk_get_locale_direction ()">gtk_get_locale_direction</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-parse-args" title="gtk_parse_args ()">gtk_parse_args</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()">gtk_init</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()">gtk_init_check</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-init-with-args" title="gtk_init_with_args ()">gtk_init_with_args</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">GOptionGroup</span> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-option-group" title="gtk_get_option_group ()">gtk_get_option_group</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-events-pending" title="gtk_events_pending ()">gtk_events_pending</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main" title="gtk_main ()">gtk_main</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">guint</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main-level" title="gtk_main_level ()">gtk_main_level</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()">gtk_main_quit</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main-iteration" title="gtk_main_iteration ()">gtk_main_iteration</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main-iteration-do" title="gtk_main_iteration_do ()">gtk_main_iteration_do</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-main-do-event" title="gtk_main_do_event ()">gtk_main_do_event</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<span class="c_punctuation">(</span><a class="link" href="gtk3-General.html#GtkModuleInitFunc" title="GtkModuleInitFunc ()">*GtkModuleInitFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<span class="c_punctuation">(</span><a class="link" href="gtk3-General.html#GtkModuleDisplayInitFunc" title="GtkModuleDisplayInitFunc ()">*GtkModuleDisplayInitFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-true" title="gtk_true ()">gtk_true</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-false" title="gtk_false ()">gtk_false</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-grab-add" title="gtk_grab_add ()">gtk_grab_add</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-grab-get-current" title="gtk_grab_get_current ()">gtk_grab_get_current</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-grab-remove" title="gtk_grab_remove ()">gtk_grab_remove</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-device-grab-add" title="gtk_device_grab_add ()">gtk_device_grab_add</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-device-grab-remove" title="gtk_device_grab_remove ()">gtk_device_grab_remove</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">guint</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-key-snooper-install" title="gtk_key_snooper_install ()">gtk_key_snooper_install</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gint</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<span class="c_punctuation">(</span><a class="link" href="gtk3-General.html#GtkKeySnoopFunc" title="GtkKeySnoopFunc ()">*GtkKeySnoopFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-key-snooper-remove" title="gtk_key_snooper_remove ()">gtk_key_snooper_remove</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">GdkEvent</span> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-current-event" title="gtk_get_current_event ()">gtk_get_current_event</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">guint32</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-current-event-time" title="gtk_get_current_event_time ()">gtk_get_current_event_time</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">gboolean</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-current-event-state" title="gtk_get_current_event_state ()">gtk_get_current_event_state</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">GdkDevice</span> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-current-event-device" title="gtk_get_current_event_device ()">gtk_get_current_event_device</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-get-event-widget" title="gtk_get_event_widget ()">gtk_get_event_widget</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="function_type">
|
||
<span class="returnvalue">void</span>
|
||
</td>
|
||
<td class="function_name">
|
||
<a class="link" href="gtk3-General.html#gtk-propagate-event" title="gtk_propagate_event ()">gtk_propagate_event</a> <span class="c_punctuation">()</span>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.other"></a><h2>Types and Values</h2>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="other_proto_type">
|
||
<col class="other_proto_name">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="define_keyword">#define</td>
|
||
<td class="function_name"><a class="link" href="gtk3-General.html#GTK-PRIORITY-RESIZE:CAPS" title="GTK_PRIORITY_RESIZE">GTK_PRIORITY_RESIZE</a></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.includes"></a><h2>Includes</h2>
|
||
<pre class="synopsis">#include <gtk/gtk.h>
|
||
</pre>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.description"></a><h2>Description</h2>
|
||
<p>Before using GTK+, you need to initialize it; initialization connects to the
|
||
window system display, and parses some standard command line arguments. The
|
||
<a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a> macro initializes GTK+. <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a> exits the application if errors
|
||
occur; to avoid this, use <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a>. <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a> allows you to
|
||
recover from a failed GTK+ initialization - you might start up your
|
||
application in text mode instead.</p>
|
||
<p>Like all GUI toolkits, GTK+ uses an event-driven programming model. When the
|
||
user is doing nothing, GTK+ sits in the “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.</p>
|
||
<p>When widgets receive an event, they frequently emit one or more
|
||
“signals”. Signals notify your program that "something
|
||
interesting happened" by invoking functions you’ve connected to the signal
|
||
with <code class="function">g_signal_connect()</code>. Functions connected to a signal are often termed
|
||
“callbacks”.</p>
|
||
<p>When your callbacks are invoked, you would typically take some action - for
|
||
example, when an Open button is clicked you might display a
|
||
<a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a>. After a callback finishes, GTK+ will return to the
|
||
main loop and await more user input.</p>
|
||
<div class="refsect3">
|
||
<a name="id-1.4.2.6.6"></a><h4>Typical <code class="function">main()</code> function for a GTK+ application</h4>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14
|
||
15
|
||
16
|
||
17
|
||
18
|
||
19
|
||
20
|
||
21
|
||
22
|
||
23
|
||
24
|
||
25
|
||
26
|
||
27</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="kt">int</span>
|
||
<span class="nf">main</span> <span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="n">GtkWidget</span> <span class="o">*</span><span class="n">mainwin</span><span class="p">;</span>
|
||
<span class="c1">// Initialize i18n support with bindtextdomain(), etc.</span>
|
||
|
||
<span class="c1">// ...</span>
|
||
|
||
<span class="c1">// Initialize the widget set</span>
|
||
<span class="n">gtk_init</span> <span class="p">(</span><span class="o">&</span><span class="n">argc</span><span class="p">,</span> <span class="o">&</span><span class="n">argv</span><span class="p">);</span>
|
||
|
||
<span class="c1">// Create the main window</span>
|
||
<span class="n">mainwin</span> <span class="o">=</span> <span class="n">gtk_window_new</span> <span class="p">(</span><span class="n">GTK_WINDOW_TOPLEVEL</span><span class="p">);</span>
|
||
|
||
<span class="c1">// Set up our GUI elements</span>
|
||
|
||
<span class="c1">// ...</span>
|
||
|
||
<span class="c1">// Show the application window</span>
|
||
<span class="n">gtk_widget_show_all</span> <span class="p">(</span><span class="n">mainwin</span><span class="p">);</span>
|
||
|
||
<span class="c1">// Enter the main event loop, and wait for user interaction</span>
|
||
<span class="n">gtk_main</span> <span class="p">();</span>
|
||
|
||
<span class="c1">// The user lost interest</span>
|
||
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
|
||
<span class="p">}</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p></p>
|
||
<p>It’s OK to use the GLib main loop directly instead of <a class="link" href="gtk3-General.html#gtk-main" title="gtk_main ()"><code class="function">gtk_main()</code></a>, though it
|
||
involves slightly more typing. See <span class="type">GMainLoop</span> in the GLib documentation.</p>
|
||
</div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.functions_details"></a><h2>Functions</h2>
|
||
<div class="refsect2">
|
||
<a name="gtk-disable-setlocale"></a><h3>gtk_disable_setlocale ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_disable_setlocale (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Prevents <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>, <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a>, <a class="link" href="gtk3-General.html#gtk-init-with-args" title="gtk_init_with_args ()"><code class="function">gtk_init_with_args()</code></a> and
|
||
<a class="link" href="gtk3-General.html#gtk-parse-args" title="gtk_parse_args ()"><code class="function">gtk_parse_args()</code></a> from automatically
|
||
calling <code class="literal">setlocale (LC_ALL, "")</code>. You would
|
||
want to use this function if you wanted to set the locale for
|
||
your program to something other than the user’s locale, or if
|
||
you wanted to set different values for different locale categories.</p>
|
||
<p>Most programs should not need to call this function.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-default-language"></a><h3>gtk_get_default_language ()</h3>
|
||
<pre class="programlisting"><a href="https://developer.gnome.org/pango/pango-Scripts-and-Languages.html#PangoLanguage-struct"><span class="returnvalue">PangoLanguage</span></a> *
|
||
gtk_get_default_language (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Returns the <a href="https://developer.gnome.org/pango/pango-Scripts-and-Languages.html#PangoLanguage-struct"><span class="type">PangoLanguage</span></a> for the default language currently in
|
||
effect. (Note that this can change over the life of an
|
||
application.) The default language is derived from the current
|
||
locale. It determines, for example, whether GTK+ uses the
|
||
right-to-left or left-to-right text direction.</p>
|
||
<p>This function is equivalent to <a href="https://developer.gnome.org/pango/pango-Scripts-and-Languages.html#pango-language-get-default"><code class="function">pango_language_get_default()</code></a>.
|
||
See that function for details.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-default-language.returns"></a><h4>Returns</h4>
|
||
<p>the default language as a <a href="https://developer.gnome.org/pango/pango-Scripts-and-Languages.html#PangoLanguage-struct"><span class="type">PangoLanguage</span></a>,
|
||
must not be freed. </p>
|
||
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-locale-direction"></a><h3>gtk_get_locale_direction ()</h3>
|
||
<pre class="programlisting"><a class="link" href="GtkWidget.html#GtkTextDirection" title="enum GtkTextDirection"><span class="returnvalue">GtkTextDirection</span></a>
|
||
gtk_get_locale_direction (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Get the direction of the current locale. This is the expected
|
||
reading direction for text and UI.</p>
|
||
<p>This function depends on the current locale being set with
|
||
<code class="function">setlocale()</code> and will default to setting the <a class="link" href="GtkWidget.html#GTK-TEXT-DIR-LTR:CAPS"><code class="literal">GTK_TEXT_DIR_LTR</code></a>
|
||
direction otherwise. <a class="link" href="GtkWidget.html#GTK-TEXT-DIR-NONE:CAPS"><code class="literal">GTK_TEXT_DIR_NONE</code></a> will never be returned.</p>
|
||
<p>GTK+ sets the default text direction according to the locale
|
||
during <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>, and you should normally use
|
||
<a class="link" href="GtkWidget.html#gtk-widget-get-direction" title="gtk_widget_get_direction ()"><code class="function">gtk_widget_get_direction()</code></a> or <a class="link" href="GtkWidget.html#gtk-widget-get-default-direction" title="gtk_widget_get_default_direction ()"><code class="function">gtk_widget_get_default_direction()</code></a>
|
||
to obtain the current direcion.</p>
|
||
<p>This function is only needed rare cases when the locale is
|
||
changed after GTK+ has already been initialized. In this case,
|
||
you can use it to update the default text direction as follows:</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">setlocale</span> <span class="p">(</span><span class="n">LC_ALL</span><span class="p">,</span> <span class="n">new_locale</span><span class="p">);</span>
|
||
<span class="n">direction</span> <span class="o">=</span> <span class="n">gtk_get_locale_direction</span> <span class="p">();</span>
|
||
<span class="n">gtk_widget_set_default_direction</span> <span class="p">(</span><span class="n">direction</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p></p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-locale-direction.returns"></a><h4>Returns</h4>
|
||
<p> the <a class="link" href="GtkWidget.html#GtkTextDirection" title="enum GtkTextDirection"><span class="type">GtkTextDirection</span></a> of the current locale</p>
|
||
</div>
|
||
<p class="since">Since: <a class="link" href="api-index-3-12.html#api-index-3.12">3.12</a></p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-parse-args"></a><h3>gtk_parse_args ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_parse_args (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
|
||
<em class="parameter"><code><span class="type">char</span> ***argv</code></em>);</pre>
|
||
<p>Parses command line arguments, and initializes global
|
||
attributes of GTK+, but does not actually open a connection
|
||
to a display. (See <a href="https://developer.gnome.org/gdk4/GdkDisplay.html#gdk-display-open"><code class="function">gdk_display_open()</code></a>, <code class="function">gdk_get_display_arg_name()</code>)</p>
|
||
<p>Any arguments used by GTK+ or GDK are removed from the array and
|
||
<em class="parameter"><code>argc</code></em>
|
||
and <em class="parameter"><code>argv</code></em>
|
||
are updated accordingly.</p>
|
||
<p>There is no need to call this function explicitly if you are using
|
||
<a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>, or <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a>.</p>
|
||
<p>Note that many aspects of GTK+ require a display connection to
|
||
function, so this way of initializing GTK+ is really only useful
|
||
for specialized use cases.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-parse-args.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>argc</p></td>
|
||
<td class="parameter_description"><p>a pointer to the number of command line arguments. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>argv</p></td>
|
||
<td class="parameter_description"><p>a pointer to the array of
|
||
command line arguments. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-parse-args.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if initialization succeeded, otherwise <code class="literal">FALSE</code></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-init"></a><h3>gtk_init ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_init (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
|
||
<em class="parameter"><code><span class="type">char</span> ***argv</code></em>);</pre>
|
||
<p>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.</p>
|
||
<p>Although you are expected to pass the <em class="parameter"><code>argc</code></em>
|
||
, <em class="parameter"><code>argv</code></em>
|
||
parameters from <code class="function">main()</code> to
|
||
this function, it is possible to pass <code class="literal">NULL</code> if <em class="parameter"><code>argv</code></em>
|
||
is not available or
|
||
commandline handling is not required.</p>
|
||
<p><em class="parameter"><code>argc</code></em>
|
||
and <em class="parameter"><code>argv</code></em>
|
||
are adjusted accordingly so your own code will
|
||
never see those standard arguments.</p>
|
||
<p>Note that there are some alternative ways to initialize GTK+:
|
||
if you are calling <a class="link" href="gtk3-General.html#gtk-parse-args" title="gtk_parse_args ()"><code class="function">gtk_parse_args()</code></a>, <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a>,
|
||
<a class="link" href="gtk3-General.html#gtk-init-with-args" title="gtk_init_with_args ()"><code class="function">gtk_init_with_args()</code></a> or <code class="function">g_option_context_parse()</code> with
|
||
the option group returned by <a class="link" href="gtk3-General.html#gtk-get-option-group" title="gtk_get_option_group ()"><code class="function">gtk_get_option_group()</code></a>,
|
||
you don’t have to call <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>.</p>
|
||
<p>And if you are using <a class="link" href="GtkApplication.html" title="GtkApplication"><span class="type">GtkApplication</span></a>, you don't have to call any of the
|
||
initialization functions either; the <span class="type">“startup”</span> handler
|
||
does it for you.</p>
|
||
<p>This function will terminate your program if it was unable to
|
||
initialize the windowing system for some reason. If you want
|
||
your program to fall back to a textual interface you want to
|
||
call <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a> instead.</p>
|
||
<p>Since 2.18, GTK+ calls <code class="literal">signal (SIGPIPE, SIG_IGN)</code>
|
||
during initialization, to ignore SIGPIPE signals, since these are
|
||
almost never wanted in graphical applications. If you do need to
|
||
handle SIGPIPE for some reason, reset the handler after <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>,
|
||
but notice that other libraries (e.g. libdbus or gvfs) might do
|
||
similar things.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-init.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>argc</p></td>
|
||
<td class="parameter_description"><p>Address of the <code class="literal">argc</code> parameter of
|
||
your <code class="function">main()</code> function (or 0 if <em class="parameter"><code>argv</code></em>
|
||
is <code class="literal">NULL</code>). This will be changed if
|
||
any arguments were handled. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>argv</p></td>
|
||
<td class="parameter_description"><p>Address of the
|
||
<code class="literal">argv</code> parameter of <code class="function">main()</code>, or <code class="literal">NULL</code>. Any options
|
||
understood by GTK+ are stripped before return. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-init-check"></a><h3>gtk_init_check ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_init_check (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
|
||
<em class="parameter"><code><span class="type">char</span> ***argv</code></em>);</pre>
|
||
<p>This function does the same work as <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a> with only a single
|
||
change: It does not terminate the program if the commandline
|
||
arguments couldn’t be parsed or the windowing system can’t be
|
||
initialized. Instead it returns <code class="literal">FALSE</code> on failure.</p>
|
||
<p>This way the application can fall back to some other means of
|
||
communication with the user - for example a curses or command line
|
||
interface.</p>
|
||
<p>Note that calling any GTK function or instantiating any GTK type after
|
||
this function returns <code class="literal">FALSE</code> results in undefined behavior.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-init-check.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>argc</p></td>
|
||
<td class="parameter_description"><p>Address of the <code class="literal">argc</code> parameter of
|
||
your <code class="function">main()</code> function (or 0 if <em class="parameter"><code>argv</code></em>
|
||
is <code class="literal">NULL</code>). This will be changed if
|
||
any arguments were handled. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>argv</p></td>
|
||
<td class="parameter_description"><p>Address of the
|
||
<code class="literal">argv</code> parameter of <code class="function">main()</code>, or <code class="literal">NULL</code>. Any options
|
||
understood by GTK+ are stripped before return. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-init-check.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if the commandline arguments (if any) were valid and
|
||
the windowing system has been successfully initialized, <code class="literal">FALSE</code>
|
||
otherwise</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-init-with-args"></a><h3>gtk_init_with_args ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_init_with_args (<em class="parameter"><code><span class="type">gint</span> *argc</code></em>,
|
||
<em class="parameter"><code><span class="type">gchar</span> ***argv</code></em>,
|
||
<em class="parameter"><code>const <span class="type">gchar</span> *parameter_string</code></em>,
|
||
<em class="parameter"><code>const <span class="type">GOptionEntry</span> *entries</code></em>,
|
||
<em class="parameter"><code>const <span class="type">gchar</span> *translation_domain</code></em>,
|
||
<em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
|
||
<p>This function does the same work as <a class="link" href="gtk3-General.html#gtk-init-check" title="gtk_init_check ()"><code class="function">gtk_init_check()</code></a>.
|
||
Additionally, it allows you to add your own commandline options,
|
||
and it automatically generates nicely formatted
|
||
<code class="literal">--help</code> output. Note that your program will
|
||
be terminated after writing out the help output.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-init-with-args.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>argc</p></td>
|
||
<td class="parameter_description"><p>Address of the <code class="literal">argc</code> parameter of
|
||
your <code class="function">main()</code> function (or 0 if <em class="parameter"><code>argv</code></em>
|
||
is <code class="literal">NULL</code>). This will be changed if
|
||
any arguments were handled. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>argv</p></td>
|
||
<td class="parameter_description"><p>Address of the
|
||
<code class="literal">argv</code> parameter of <code class="function">main()</code>, or <code class="literal">NULL</code>. Any options
|
||
understood by GTK+ are stripped before return. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>parameter_string</p></td>
|
||
<td class="parameter_description"><p>a string which is displayed in
|
||
the first line of <code class="literal">--help</code> output, after
|
||
<code class="literal">programname [OPTION...]</code>. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>entries</p></td>
|
||
<td class="parameter_description"><p>a <code class="literal">NULL</code>-terminated array
|
||
of <span class="type">GOptionEntrys</span> describing the options of your program. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>translation_domain</p></td>
|
||
<td class="parameter_description"><p>a translation domain to use for translating
|
||
the <code class="literal">--help</code> output for the options in <em class="parameter"><code>entries</code></em>
|
||
and the <em class="parameter"><code>parameter_string</code></em>
|
||
with <code class="function">gettext()</code>, or <code class="literal">NULL</code>. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>error</p></td>
|
||
<td class="parameter_description"><p>a return location for errors</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-init-with-args.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if the commandline arguments (if any) were valid and
|
||
if the windowing system has been successfully initialized,
|
||
<code class="literal">FALSE</code> otherwise</p>
|
||
</div>
|
||
<p class="since">Since: 2.6</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-option-group"></a><h3>gtk_get_option_group ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">GOptionGroup</span> *
|
||
gtk_get_option_group (<em class="parameter"><code><span class="type">gboolean</span> open_default_display</code></em>);</pre>
|
||
<p>Returns a <span class="type">GOptionGroup</span> for the commandline arguments recognized
|
||
by GTK+ and GDK.</p>
|
||
<p>You should add this group to your <span class="type">GOptionContext</span>
|
||
with <code class="function">g_option_context_add_group()</code>, if you are using
|
||
<code class="function">g_option_context_parse()</code> to parse your commandline arguments.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-option-group.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>open_default_display</p></td>
|
||
<td class="parameter_description"><p>whether to open the default display
|
||
when parsing the commandline arguments</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-option-group.returns"></a><h4>Returns</h4>
|
||
<p>a <span class="type">GOptionGroup</span> for the commandline
|
||
arguments recognized by GTK+. </p>
|
||
<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
|
||
</div>
|
||
<p class="since">Since: 2.6</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-events-pending"></a><h3>gtk_events_pending ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_events_pending (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Checks if any events are pending.</p>
|
||
<p>This can be used to update the UI and invoke timeouts etc.
|
||
while doing some time intensive computation.</p>
|
||
<div class="refsect3">
|
||
<a name="id-1.4.2.7.10.6"></a><h4>Updating the UI during a long computation</h4>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="c1">// computation going on...</span>
|
||
|
||
<span class="k">while</span> <span class="p">(</span><span class="n">gtk_events_pending</span> <span class="p">())</span>
|
||
<span class="n">gtk_main_iteration</span> <span class="p">();</span>
|
||
|
||
<span class="c1">// ...computation continued</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p></p>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-events-pending.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if any events are pending, <code class="literal">FALSE</code> otherwise</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main"></a><h3>gtk_main ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_main (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Runs the main loop until <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a> is called.</p>
|
||
<p>You can nest calls to <a class="link" href="gtk3-General.html#gtk-main" title="gtk_main ()"><code class="function">gtk_main()</code></a>. In that case <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a>
|
||
will make the innermost invocation of the main loop return.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main-level"></a><h3>gtk_main_level ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">guint</span>
|
||
gtk_main_level (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Asks for the current nesting level of the main loop.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-main-level.returns"></a><h4>Returns</h4>
|
||
<p> the nesting level of the current invocation
|
||
of the main loop</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main-quit"></a><h3>gtk_main_quit ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_main_quit (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Makes the innermost invocation of the main loop return
|
||
when it regains control.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main-iteration"></a><h3>gtk_main_iteration ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_main_iteration (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Runs a single iteration of the mainloop.</p>
|
||
<p>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 <a class="link" href="gtk3-General.html#gtk-main-iteration-do" title="gtk_main_iteration_do ()"><code class="function">gtk_main_iteration_do()</code></a> or check if any events are
|
||
pending with <a class="link" href="gtk3-General.html#gtk-events-pending" title="gtk_events_pending ()"><code class="function">gtk_events_pending()</code></a> first.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-main-iteration.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a> has been called for the
|
||
innermost mainloop</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main-iteration-do"></a><h3>gtk_main_iteration_do ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_main_iteration_do (<em class="parameter"><code><span class="type">gboolean</span> blocking</code></em>);</pre>
|
||
<p>Runs a single iteration of the mainloop.
|
||
If no events are available either return or block depending on
|
||
the value of <em class="parameter"><code>blocking</code></em>
|
||
.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-main-iteration-do.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>blocking</p></td>
|
||
<td class="parameter_description"><p><code class="literal">TRUE</code> if you want GTK+ to block if no events are pending</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-main-iteration-do.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a> has been called for the
|
||
innermost mainloop</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-main-do-event"></a><h3>gtk_main_do_event ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_main_do_event (<em class="parameter"><code><span class="type">GdkEvent</span> *event</code></em>);</pre>
|
||
<p>Processes a single GDK event.</p>
|
||
<p>This is public only to allow filtering of events between GDK and GTK+.
|
||
You will not usually need to call this function directly.</p>
|
||
<p>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:</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||
<li class="listitem"><p>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.</p></li>
|
||
<li class="listitem"><p>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.</p></li>
|
||
<li class="listitem"><p>Then the event is pushed onto a stack so you can query the currently
|
||
handled event with <a class="link" href="gtk3-General.html#gtk-get-current-event" title="gtk_get_current_event ()"><code class="function">gtk_get_current_event()</code></a>.</p></li>
|
||
<li class="listitem">
|
||
<p>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:</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem"><p>Deletion and destruction events are still sent to the event widget for
|
||
obvious reasons.</p></li>
|
||
<li class="listitem"><p>Events which directly relate to the visual representation of the event
|
||
widget.</p></li>
|
||
<li class="listitem"><p>Leave events are delivered to the event widget if there was an enter
|
||
event delivered to it before without the paired leave event.</p></li>
|
||
<li class="listitem"><p>Drag events are not redirected because it is unclear what the semantics
|
||
of that would be.
|
||
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 <a class="link" href="gtk3-General.html#gtk-key-snooper-install" title="gtk_key_snooper_install ()"><code class="function">gtk_key_snooper_install()</code></a> if you need this feature.</p></li>
|
||
</ul></div>
|
||
</li>
|
||
<li class="listitem"><p>After finishing the delivery the event is popped from the event stack.</p></li>
|
||
</ol></div>
|
||
<div class="refsect3">
|
||
<a name="gtk-main-do-event.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>event</p></td>
|
||
<td class="parameter_description"><p>An event to process (normally passed by GDK)</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="GtkModuleInitFunc"></a><h3>GtkModuleInitFunc ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
<span class="c_punctuation">(</span>*GtkModuleInitFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><span class="type">gint</span> *argc</code></em>,
|
||
<em class="parameter"><code><span class="type">gchar</span> ***argv</code></em>);</pre>
|
||
<p>Each GTK+ module must have a function <code class="function">gtk_module_init()</code> with this prototype.
|
||
This function is called after loading the module.</p>
|
||
<div class="refsect3">
|
||
<a name="GtkModuleInitFunc.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>argc</p></td>
|
||
<td class="parameter_description"><p>GTK+ always passes <code class="literal">NULL</code> for this argument. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>argv</p></td>
|
||
<td class="parameter_description"><p>GTK+ always passes <code class="literal">NULL</code> for this argument. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="GtkModuleDisplayInitFunc"></a><h3>GtkModuleDisplayInitFunc ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
<span class="c_punctuation">(</span>*GtkModuleDisplayInitFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><span class="type">GdkDisplay</span> *display</code></em>);</pre>
|
||
<p>A multihead-aware GTK+ module may have a <code class="function">gtk_module_display_init()</code> function
|
||
with this prototype. GTK+ calls this function for each opened display.</p>
|
||
<div class="refsect3">
|
||
<a name="GtkModuleDisplayInitFunc.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>display</p></td>
|
||
<td class="parameter_description"><p>an open <span class="type">GdkDisplay</span></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<p class="since">Since: 2.2</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-true"></a><h3>gtk_true ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_true (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>All this function does it to return <code class="literal">TRUE</code>.</p>
|
||
<p>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...</p>
|
||
<div class="refsect3">
|
||
<a name="id-1.4.2.7.19.6"></a><h4>A persistent window</h4>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14
|
||
15
|
||
16
|
||
17
|
||
18
|
||
19
|
||
20
|
||
21
|
||
22
|
||
23
|
||
24
|
||
25
|
||
26
|
||
27
|
||
28
|
||
29
|
||
30
|
||
31</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="cp">#include</span> <span class="cpf"><gtk/gtk.h></span><span class="cp"></span>
|
||
|
||
<span class="kt">int</span>
|
||
<span class="nf">main</span> <span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="n">GtkWidget</span> <span class="o">*</span><span class="n">win</span><span class="p">,</span> <span class="o">*</span><span class="n">but</span><span class="p">;</span>
|
||
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">text</span> <span class="o">=</span> <span class="s">"Close yourself. I mean it!"</span><span class="p">;</span>
|
||
|
||
<span class="n">gtk_init</span> <span class="p">(</span><span class="o">&</span><span class="n">argc</span><span class="p">,</span> <span class="o">&</span><span class="n">argv</span><span class="p">);</span>
|
||
|
||
<span class="n">win</span> <span class="o">=</span> <span class="n">gtk_window_new</span> <span class="p">(</span><span class="n">GTK_WINDOW_TOPLEVEL</span><span class="p">);</span>
|
||
<span class="n">g_signal_connect</span> <span class="p">(</span><span class="n">win</span><span class="p">,</span>
|
||
<span class="s">"delete-event"</span><span class="p">,</span>
|
||
<span class="n">G_CALLBACK</span> <span class="p">(</span><span class="n">gtk_true</span><span class="p">),</span>
|
||
<span class="nb">NULL</span><span class="p">);</span>
|
||
<span class="n">g_signal_connect</span> <span class="p">(</span><span class="n">win</span><span class="p">,</span> <span class="s">"destroy"</span><span class="p">,</span>
|
||
<span class="n">G_CALLBACK</span> <span class="p">(</span><span class="n">gtk_main_quit</span><span class="p">),</span>
|
||
<span class="nb">NULL</span><span class="p">);</span>
|
||
|
||
<span class="n">but</span> <span class="o">=</span> <span class="n">gtk_button_new_with_label</span> <span class="p">(</span><span class="n">text</span><span class="p">);</span>
|
||
<span class="n">g_signal_connect_swapped</span> <span class="p">(</span><span class="n">but</span><span class="p">,</span> <span class="s">"clicked"</span><span class="p">,</span>
|
||
<span class="n">G_CALLBACK</span> <span class="p">(</span><span class="n">gtk_object_destroy</span><span class="p">),</span>
|
||
<span class="n">win</span><span class="p">);</span>
|
||
<span class="n">gtk_container_add</span> <span class="p">(</span><span class="n">GTK_CONTAINER</span> <span class="p">(</span><span class="n">win</span><span class="p">),</span> <span class="n">but</span><span class="p">);</span>
|
||
|
||
<span class="n">gtk_widget_show_all</span> <span class="p">(</span><span class="n">win</span><span class="p">);</span>
|
||
|
||
<span class="n">gtk_main</span> <span class="p">();</span>
|
||
|
||
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
|
||
<span class="p">}</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p></p>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-true.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-false"></a><h3>gtk_false ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_false (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Analogical to <a class="link" href="gtk3-General.html#gtk-true" title="gtk_true ()"><code class="function">gtk_true()</code></a>, this function does nothing
|
||
but always returns <code class="literal">FALSE</code>.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-false.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">FALSE</code></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-grab-add"></a><h3>gtk_grab_add ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_grab_add (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *widget</code></em>);</pre>
|
||
<p>Makes <em class="parameter"><code>widget</code></em>
|
||
the current grabbed widget.</p>
|
||
<p>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.</p>
|
||
<p>If <em class="parameter"><code>widget</code></em>
|
||
is not sensitive, it is not set as the current
|
||
grabbed widget and this function does nothing.</p>
|
||
<p><span class="annotation">[<acronym title="This is a method"><span class="acronym">method</span></acronym>]</span></p>
|
||
<div class="refsect3">
|
||
<a name="gtk-grab-add.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>widget</p></td>
|
||
<td class="parameter_description"><p>The widget that grabs keyboard and pointer events</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-grab-get-current"></a><h3>gtk_grab_get_current ()</h3>
|
||
<pre class="programlisting"><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *
|
||
gtk_grab_get_current (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Queries the current grab of the default window group.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-grab-get-current.returns"></a><h4>Returns</h4>
|
||
<p>The widget which currently
|
||
has the grab or <code class="literal">NULL</code> if no grab is active. </p>
|
||
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-grab-remove"></a><h3>gtk_grab_remove ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_grab_remove (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *widget</code></em>);</pre>
|
||
<p>Removes the grab from the given widget.</p>
|
||
<p>You have to pair calls to <a class="link" href="gtk3-General.html#gtk-grab-add" title="gtk_grab_add ()"><code class="function">gtk_grab_add()</code></a> and <a class="link" href="gtk3-General.html#gtk-grab-remove" title="gtk_grab_remove ()"><code class="function">gtk_grab_remove()</code></a>.</p>
|
||
<p>If <em class="parameter"><code>widget</code></em>
|
||
does not have the grab, this function does nothing.</p>
|
||
<p><span class="annotation">[<acronym title="This is a method"><span class="acronym">method</span></acronym>]</span></p>
|
||
<div class="refsect3">
|
||
<a name="gtk-grab-remove.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>widget</p></td>
|
||
<td class="parameter_description"><p>The widget which gives up the grab</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-device-grab-add"></a><h3>gtk_device_grab_add ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_device_grab_add (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *widget</code></em>,
|
||
<em class="parameter"><code><span class="type">GdkDevice</span> *device</code></em>,
|
||
<em class="parameter"><code><span class="type">gboolean</span> block_others</code></em>);</pre>
|
||
<p>Adds a GTK+ grab on <em class="parameter"><code>device</code></em>
|
||
, so all the events on <em class="parameter"><code>device</code></em>
|
||
and its
|
||
associated pointer or keyboard (if any) are delivered to <em class="parameter"><code>widget</code></em>
|
||
.
|
||
If the <em class="parameter"><code>block_others</code></em>
|
||
parameter is <code class="literal">TRUE</code>, any other devices will be
|
||
unable to interact with <em class="parameter"><code>widget</code></em>
|
||
during the grab.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-device-grab-add.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>widget</p></td>
|
||
<td class="parameter_description"><p>a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>device</p></td>
|
||
<td class="parameter_description"><p>a <span class="type">GdkDevice</span> to grab on.</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>block_others</p></td>
|
||
<td class="parameter_description"><p><code class="literal">TRUE</code> to prevent other devices to interact with <em class="parameter"><code>widget</code></em>
|
||
.</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-device-grab-remove"></a><h3>gtk_device_grab_remove ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_device_grab_remove (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *widget</code></em>,
|
||
<em class="parameter"><code><span class="type">GdkDevice</span> *device</code></em>);</pre>
|
||
<p>Removes a device grab from the given widget.</p>
|
||
<p>You have to pair calls to <a class="link" href="gtk3-General.html#gtk-device-grab-add" title="gtk_device_grab_add ()"><code class="function">gtk_device_grab_add()</code></a> and
|
||
<a class="link" href="gtk3-General.html#gtk-device-grab-remove" title="gtk_device_grab_remove ()"><code class="function">gtk_device_grab_remove()</code></a>.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-device-grab-remove.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>widget</p></td>
|
||
<td class="parameter_description"><p>a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>device</p></td>
|
||
<td class="parameter_description"><p>a <span class="type">GdkDevice</span></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-key-snooper-install"></a><h3>gtk_key_snooper_install ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">guint</span>
|
||
gtk_key_snooper_install (<em class="parameter"><code><a class="link" href="gtk3-General.html#GtkKeySnoopFunc" title="GtkKeySnoopFunc ()"><span class="type">GtkKeySnoopFunc</span></a> snooper</code></em>,
|
||
<em class="parameter"><code><span class="type">gpointer</span> func_data</code></em>);</pre>
|
||
<div class="warning">
|
||
<p><code class="literal">gtk_key_snooper_install</code> has been deprecated since version 3.4 and should not be used in newly-written code.</p>
|
||
<p>Key snooping should not be done. Events should
|
||
be handled by widgets.</p>
|
||
</div>
|
||
<p>Installs a key snooper function, which will get called on all
|
||
key events before delivering them normally.</p>
|
||
<p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p>
|
||
<div class="refsect3">
|
||
<a name="gtk-key-snooper-install.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>snooper</p></td>
|
||
<td class="parameter_description"><p>a <a class="link" href="gtk3-General.html#GtkKeySnoopFunc" title="GtkKeySnoopFunc ()"><span class="type">GtkKeySnoopFunc</span></a></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>func_data</p></td>
|
||
<td class="parameter_description"><p>data to pass to <em class="parameter"><code>snooper</code></em>
|
||
. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-key-snooper-install.returns"></a><h4>Returns</h4>
|
||
<p> a unique id for this key snooper for use with
|
||
<a class="link" href="gtk3-General.html#gtk-key-snooper-remove" title="gtk_key_snooper_remove ()"><code class="function">gtk_key_snooper_remove()</code></a>.</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="GtkKeySnoopFunc"></a><h3>GtkKeySnoopFunc ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gint</span>
|
||
<span class="c_punctuation">(</span>*GtkKeySnoopFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *grab_widget</code></em>,
|
||
<em class="parameter"><code><span class="type">GdkEventKey</span> *event</code></em>,
|
||
<em class="parameter"><code><span class="type">gpointer</span> func_data</code></em>);</pre>
|
||
<p>Key snooper functions are called before normal event delivery.
|
||
They can be used to implement custom key event handling.</p>
|
||
<div class="refsect3">
|
||
<a name="GtkKeySnoopFunc.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>grab_widget</p></td>
|
||
<td class="parameter_description"><p>the widget to which the event will be delivered</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>event</p></td>
|
||
<td class="parameter_description"><p>the key event</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>func_data</p></td>
|
||
<td class="parameter_description"><p>data supplied to <a class="link" href="gtk3-General.html#gtk-key-snooper-install" title="gtk_key_snooper_install ()"><code class="function">gtk_key_snooper_install()</code></a>. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="GtkKeySnoopFunc.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> to stop further processing of <em class="parameter"><code>event</code></em>
|
||
, <code class="literal">FALSE</code> to continue.</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-key-snooper-remove"></a><h3>gtk_key_snooper_remove ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_key_snooper_remove (<em class="parameter"><code><span class="type">guint</span> snooper_handler_id</code></em>);</pre>
|
||
<div class="warning">
|
||
<p><code class="literal">gtk_key_snooper_remove</code> has been deprecated since version 3.4 and should not be used in newly-written code.</p>
|
||
<p>Key snooping should not be done. Events should
|
||
be handled by widgets.</p>
|
||
</div>
|
||
<p>Removes the key snooper function with the given id.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-key-snooper-remove.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>snooper_handler_id</p></td>
|
||
<td class="parameter_description"><p>Identifies the key snooper to remove</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-current-event"></a><h3>gtk_get_current_event ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">GdkEvent</span> *
|
||
gtk_get_current_event (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>Obtains a copy of the event currently being processed by GTK+.</p>
|
||
<p>For example, if you are handling a <a class="link" href="GtkButton.html#GtkButton-clicked" title="The “clicked” signal"><span class="type">“clicked”</span></a> signal,
|
||
the current event will be the <span class="type">GdkEventButton</span> that triggered
|
||
the ::clicked signal.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-current-event.returns"></a><h4>Returns</h4>
|
||
<p>a copy of the current event, or
|
||
<code class="literal">NULL</code> if there is no current event. The returned event must be
|
||
freed with <code class="function">gdk_event_free()</code>. </p>
|
||
<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-current-event-time"></a><h3>gtk_get_current_event_time ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">guint32</span>
|
||
gtk_get_current_event_time (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>If there is a current event and it has a timestamp,
|
||
return that timestamp, otherwise return <code class="literal">GDK_CURRENT_TIME</code>.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-current-event-time.returns"></a><h4>Returns</h4>
|
||
<p> the timestamp from the current event,
|
||
or <code class="literal">GDK_CURRENT_TIME</code>.</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-current-event-state"></a><h3>gtk_get_current_event_state ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">gboolean</span>
|
||
gtk_get_current_event_state (<em class="parameter"><code><span class="type">GdkModifierType</span> *state</code></em>);</pre>
|
||
<p>If there is a current event and it has a state field, place
|
||
that state field in <em class="parameter"><code>state</code></em>
|
||
and return <code class="literal">TRUE</code>, otherwise return
|
||
<code class="literal">FALSE</code>.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-current-event-state.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>state</p></td>
|
||
<td class="parameter_description"><p>a location to store the state of the current event. </p></td>
|
||
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-current-event-state.returns"></a><h4>Returns</h4>
|
||
<p> <code class="literal">TRUE</code> if there was a current event and it
|
||
had a state field</p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-current-event-device"></a><h3>gtk_get_current_event_device ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">GdkDevice</span> *
|
||
gtk_get_current_event_device (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
|
||
<p>If there is a current event and it has a device, return that
|
||
device, otherwise return <code class="literal">NULL</code>.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-current-event-device.returns"></a><h4>Returns</h4>
|
||
<p>a <span class="type">GdkDevice</span>, or <code class="literal">NULL</code>. </p>
|
||
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-get-event-widget"></a><h3>gtk_get_event_widget ()</h3>
|
||
<pre class="programlisting"><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *
|
||
gtk_get_event_widget (<em class="parameter"><code><span class="type">GdkEvent</span> *event</code></em>);</pre>
|
||
<p>If <em class="parameter"><code>event</code></em>
|
||
is <code class="literal">NULL</code> or the event was not associated with any widget,
|
||
returns <code class="literal">NULL</code>, otherwise returns the widget that received the event
|
||
originally.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-event-widget.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td class="parameter_name"><p>event</p></td>
|
||
<td class="parameter_description"><p>a <span class="type">GdkEvent</span></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
</div>
|
||
<div class="refsect3">
|
||
<a name="gtk-get-event-widget.returns"></a><h4>Returns</h4>
|
||
<p>the widget that originally
|
||
received <em class="parameter"><code>event</code></em>
|
||
, or <code class="literal">NULL</code>. </p>
|
||
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="gtk-propagate-event"></a><h3>gtk_propagate_event ()</h3>
|
||
<pre class="programlisting"><span class="returnvalue">void</span>
|
||
gtk_propagate_event (<em class="parameter"><code><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> *widget</code></em>,
|
||
<em class="parameter"><code><span class="type">GdkEvent</span> *event</code></em>);</pre>
|
||
<p>Sends an event to a widget, propagating the event to parent widgets
|
||
if the event remains unhandled.</p>
|
||
<p>Events received by GTK+ from GDK normally begin in <a class="link" href="gtk3-General.html#gtk-main-do-event" title="gtk_main_do_event ()"><code class="function">gtk_main_do_event()</code></a>.
|
||
Depending on the type of event, existence of modal dialogs, grabs, etc.,
|
||
the event may be propagated; if so, this function is used.</p>
|
||
<p>gtk_propagate_event() calls <a class="link" href="GtkWidget.html#gtk-widget-event" title="gtk_widget_event ()"><code class="function">gtk_widget_event()</code></a> on each widget it
|
||
decides to send the event to. So <a class="link" href="GtkWidget.html#gtk-widget-event" title="gtk_widget_event ()"><code class="function">gtk_widget_event()</code></a> is the lowest-level
|
||
function; it simply emits the <a class="link" href="GtkWidget.html#GtkWidget-event" title="The “event” signal"><span class="type">“event”</span></a> and possibly an
|
||
event-specific signal on a widget. <a class="link" href="gtk3-General.html#gtk-propagate-event" title="gtk_propagate_event ()"><code class="function">gtk_propagate_event()</code></a> is a bit
|
||
higher-level, and <a class="link" href="gtk3-General.html#gtk-main-do-event" title="gtk_main_do_event ()"><code class="function">gtk_main_do_event()</code></a> is the highest level.</p>
|
||
<p>All that said, you most likely don’t want to use any of these
|
||
functions; synthesizing events is rarely needed. There are almost
|
||
certainly better ways to achieve your goals. For example, use
|
||
<code class="function">gdk_window_invalidate_rect()</code> or <a class="link" href="GtkWidget.html#gtk-widget-queue-draw" title="gtk_widget_queue_draw ()"><code class="function">gtk_widget_queue_draw()</code></a> instead
|
||
of making up expose events.</p>
|
||
<div class="refsect3">
|
||
<a name="gtk-propagate-event.parameters"></a><h4>Parameters</h4>
|
||
<div class="informaltable"><table class="informaltable" width="100%" border="0">
|
||
<colgroup>
|
||
<col width="150px" class="parameters_name">
|
||
<col class="parameters_description">
|
||
<col width="200px" class="parameters_annotations">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="parameter_name"><p>widget</p></td>
|
||
<td class="parameter_description"><p>a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a></p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
<tr>
|
||
<td class="parameter_name"><p>event</p></td>
|
||
<td class="parameter_description"><p>an event</p></td>
|
||
<td class="parameter_annotations"> </td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.other_details"></a><h2>Types and Values</h2>
|
||
<div class="refsect2">
|
||
<a name="GTK-PRIORITY-RESIZE:CAPS"></a><h3>GTK_PRIORITY_RESIZE</h3>
|
||
<pre class="programlisting">#define GTK_PRIORITY_RESIZE (G_PRIORITY_HIGH_IDLE + 10)
|
||
</pre>
|
||
<p>Use this priority for functionality related to size allocation.</p>
|
||
<p>It is used internally by GTK+ to compute the sizes of widgets.
|
||
This priority is higher than <code class="literal">GDK_PRIORITY_REDRAW</code> to avoid
|
||
resizing a widget which was just redrawn.</p>
|
||
</div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="gtk3-General.see-also"></a><h2>See Also</h2>
|
||
<p>See the GLib manual, especially <span class="type">GMainLoop</span> and signal-related
|
||
functions such as <code class="function">g_signal_connect()</code></p>
|
||
</div>
|
||
</div>
|
||
<div class="footer">
|
||
<hr>Generated by GTK-Doc V1.32.1</div>
|
||
</body>
|
||
</html> |