<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="gtk4-General">
<refmeta>
<refentrytitle role="top_of_page" id="gtk4-General.top_of_page">Initialization</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Initialization</refname>
<refpurpose>Library initialization and main loop</refpurpose>
</refnamediv>

<refsect1 id="gtk4-General.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-disable-setlocale">gtk_disable_setlocale</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="PangoLanguage"><returnvalue>PangoLanguage</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-get-default-language">gtk_get_default_language</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkTextDirection"><returnvalue>GtkTextDirection</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-get-locale-direction">gtk_get_locale_direction</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-init">gtk_init</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-init-check">gtk_init_check</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="gtk4-General.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="GTK-PRIORITY-RESIZE:CAPS">GTK_PRIORITY_RESIZE</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="gtk4-General.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="gtk4-General.description" role="desc">
<title role="desc.title">Description</title>
<para>Before using GTK, you need to initialize it using <link linkend="gtk-init"><function>gtk_init()</function></link>; this
connects to the windowing system, sets up the locale and performs other
initialization tasks. <link linkend="gtk-init"><function>gtk_init()</function></link> exits the application if errors occur;
to avoid this, you can use <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>, which 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 “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.</para>
<para>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 <link linkend="g-signal-connect"><function>g_signal_connect()</function></link>. Functions
connected to a signal are often called “callbacks”.</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
<link linkend="GtkFileChooserDialog"><type>GtkFileChooserDialog</type></link>. After a callback finishes, GTK will return to the
main loop and await more user input.</para>
<refsect3><title>Typical <link linkend="main"><function>main()</function></link> function for a GTK application</title><informalexample><programlisting role="example"><![CDATA[
int
main (int argc, char **argv)
{
 GtkWidget *window;
  // Initialize i18n support with bindtextdomain(), etc.

  // ...

  // Initialize the widget set
  gtk_init ();

  // Create the main window
  window = gtk_window_new ();

  // Set up our GUI elements

  // ...

  // Show the application window
  gtk_widget_show (window);

  // Enter the main event loop, and wait for user interaction
  while (!done)
    g_main_context_iteration (NULL, TRUE);

  // The user lost interest
  return 0;
}
]]></programlisting></informalexample>
<para></para>
<para>See <link linkend="GMainLoop"><type>GMainLoop</type></link> in the GLib documentation to learn more about
main loops and their features.</para>
</refsect3>

</refsect1>
<refsect1 id="gtk4-General.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-disable-setlocale" role="function">
<title>gtk_disable_setlocale&#160;()</title>
<indexterm zone="gtk-disable-setlocale"><primary>gtk_disable_setlocale</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_disable_setlocale (<parameter><type>void</type></parameter>);</programlisting>
<para>Prevents <link linkend="gtk-init"><function>gtk_init()</function></link>, <link linkend="gtk-init-check"><function>gtk_init_check()</function></link> and
<link linkend="gtk-parse-args"><function>gtk_parse_args()</function></link> from automatically
calling <literal>setlocale (LC_ALL, "")</literal>. 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.</para>
<para>Most programs should not need to call this function.</para>
</refsect2>
<refsect2 id="gtk-get-default-language" role="function">
<title>gtk_get_default_language&#160;()</title>
<indexterm zone="gtk-get-default-language"><primary>gtk_get_default_language</primary></indexterm>
<programlisting language="C"><link linkend="PangoLanguage"><returnvalue>PangoLanguage</returnvalue></link>&#160;*
gtk_get_default_language (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns the <link linkend="PangoLanguage"><type>PangoLanguage</type></link> 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.</para>
<para>This function is equivalent to <link linkend="pango-language-get-default"><function>pango_language_get_default()</function></link>.
See that function for details.</para>
<refsect3 id="gtk-get-default-language.returns" role="returns">
<title>Returns</title>
<para>the default language as a <link linkend="PangoLanguage"><type>PangoLanguage</type></link>,
must not be freed. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-get-locale-direction" role="function">
<title>gtk_get_locale_direction&#160;()</title>
<indexterm zone="gtk-get-locale-direction"><primary>gtk_get_locale_direction</primary></indexterm>
<programlisting language="C"><link linkend="GtkTextDirection"><returnvalue>GtkTextDirection</returnvalue></link>
gtk_get_locale_direction (<parameter><type>void</type></parameter>);</programlisting>
<para>Get the direction of the current locale. This is the expected
reading direction for text and UI.</para>
<para>This function depends on the current locale being set with
<link linkend="setlocale"><function>setlocale()</function></link> and will default to setting the <link linkend="GTK-TEXT-DIR-LTR:CAPS"><literal>GTK_TEXT_DIR_LTR</literal></link>
direction otherwise. <link linkend="GTK-TEXT-DIR-NONE:CAPS"><literal>GTK_TEXT_DIR_NONE</literal></link> will never be returned.</para>
<para>GTK sets the default text direction according to the locale
during <link linkend="gtk-init"><function>gtk_init()</function></link>, and you should normally use
<link linkend="gtk-widget-get-direction"><function>gtk_widget_get_direction()</function></link> or <link linkend="gtk-widget-get-default-direction"><function>gtk_widget_get_default_direction()</function></link>
to obtain the current direcion.</para>
<para>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:</para>
<informalexample><programlisting role="example"><![CDATA[
setlocale (LC_ALL, new_locale);
direction = gtk_get_locale_direction ();
gtk_widget_set_default_direction (direction);
]]></programlisting></informalexample>
<para></para>
<refsect3 id="gtk-get-locale-direction.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GtkTextDirection"><type>GtkTextDirection</type></link> of the current locale</para>
</refsect3></refsect2>
<refsect2 id="gtk-init" role="function">
<title>gtk_init&#160;()</title>
<indexterm zone="gtk-init"><primary>gtk_init</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_init (<parameter><type>void</type></parameter>);</programlisting>
<para>Call this function before using any other GTK functions in your GUI
applications.  It will initialize everything needed to operate the
toolkit and parses some standard command line options.</para>
<para>If you are using <link linkend="GtkApplication"><type>GtkApplication</type></link>, you don't have to call <link linkend="gtk-init"><function>gtk_init()</function></link>
or <link linkend="gtk-init-check"><function>gtk_init_check()</function></link>; the <link linkend="GApplication-startup"><type>“startup”</type></link> handler
does it for you.</para>
<para>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 <link linkend="gtk-init-check"><function>gtk_init_check()</function></link> instead.</para>
<para>GTK calls <literal>signal (SIGPIPE, SIG_IGN)</literal>
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 <link linkend="gtk-init"><function>gtk_init()</function></link>,
but notice that other libraries (e.g. libdbus or gvfs) might do
similar things.</para>
</refsect2>
<refsect2 id="gtk-init-check" role="function">
<title>gtk_init_check&#160;()</title>
<indexterm zone="gtk-init-check"><primary>gtk_init_check</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_init_check (<parameter><type>void</type></parameter>);</programlisting>
<para>This function does the same work as <link linkend="gtk-init"><function>gtk_init()</function></link> with only a single
change: It does not terminate the program if the windowing system
can’t be initialized. Instead it returns <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on failure.</para>
<para>This way the application can fall back to some other means of
communication with the user - for example a curses or command line
interface.</para>
<refsect3 id="gtk-init-check.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the windowing system has been successfully
initialized, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="gtk4-General.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GTK-PRIORITY-RESIZE:CAPS" role="macro">
<title>GTK_PRIORITY_RESIZE</title>
<indexterm zone="GTK-PRIORITY-RESIZE:CAPS"><primary>GTK_PRIORITY_RESIZE</primary></indexterm>
<programlisting language="C">#define GTK_PRIORITY_RESIZE (G_PRIORITY_HIGH_IDLE + 10)
</programlisting>
<para>Use this priority for functionality related to size allocation.</para>
<para>It is used internally by GTK+ to compute the sizes of widgets.
This priority is higher than <link linkend="GDK-PRIORITY-REDRAW:CAPS"><literal>GDK_PRIORITY_REDRAW</literal></link> to avoid
resizing a widget which was just redrawn.</para>
</refsect2>

</refsect1>
<refsect1 id="gtk4-General.see-also">
<title>See Also</title>
<para>See the GLib manual, especially <link linkend="GMainLoop"><type>GMainLoop</type></link> and signal-related
functions such as <link linkend="g-signal-connect"><function>g_signal_connect()</function></link></para>

</refsect1>

</refentry>
