<?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="GtkApplication">
<refmeta>
<refentrytitle role="top_of_page" id="GtkApplication.top_of_page">GtkApplication</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkApplication</refname>
<refpurpose>Application class</refpurpose>
</refnamediv>

<refsect1 id="GtkApplication.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="GtkApplication"><returnvalue>GtkApplication</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-new">gtk_application_new</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-application-add-window">gtk_application_add_window</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-application-remove-window">gtk_application_remove_window</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-windows">gtk_application_get_windows</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkWindow"><returnvalue>GtkWindow</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-window-by-id">gtk_application_get_window_by_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkWindow"><returnvalue>GtkWindow</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-active-window">gtk_application_get_active_window</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-application-inhibit">gtk_application_inhibit</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-application-uninhibit">gtk_application_uninhibit</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-application-prefers-app-menu">gtk_application_prefers_app_menu</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMenuModel"><returnvalue>GMenuModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-app-menu">gtk_application_get_app_menu</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-application-set-app-menu">gtk_application_set_app_menu</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMenuModel"><returnvalue>GMenuModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-menubar">gtk_application_get_menubar</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-application-set-menubar">gtk_application_set_menubar</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMenu"><returnvalue>GMenu</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-application-get-menu-by-id">gtk_application_get_menu_by_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="gtk-application-list-action-descriptions">gtk_application_list_action_descriptions</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="gtk-application-get-accels-for-action">gtk_application_get_accels_for_action</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-application-set-accels-for-action">gtk_application_set_accels_for_action</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="gtk-application-get-actions-for-accel">gtk_application_get_actions_for_accel</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkApplication.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="GtkWindow"><type>GtkWindow</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkApplication--active-window">active-window</link></entry><entry role="property_flags">Read</entry></row>
<row><entry role="property_type"><link linkend="GMenuModel"><type>GMenuModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkApplication--app-menu">app-menu</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="GMenuModel"><type>GMenuModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkApplication--menubar">menubar</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkApplication--register-session">register-session</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkApplication--screensaver-active">screensaver-active</link></entry><entry role="property_flags">Read</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkApplication.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="signal_proto_type" colwidth="150px"/>
<colspec colname="signal_proto_name" colwidth="300px"/>
<colspec colname="signal_proto_flags" colwidth="200px"/>
<tbody>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkApplication-query-end">query-end</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></entry></row>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkApplication-window-added">window-added</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></entry></row>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkApplication-window-removed">window-removed</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkApplication.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="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkApplication-struct">GtkApplication</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkApplicationClass">GtkApplicationClass</link></entry></row>

<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GtkApplicationInhibitFlags">GtkApplicationInhibitFlags</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkApplication.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GApplication">GApplication</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkApplication
</screen>
</refsect1>
<refsect1 id="GtkApplication.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkApplication implements
 <link linkend="GActionGroup">GActionGroup</link> and  <link linkend="GActionMap">GActionMap</link>.</para>

</refsect1>

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

<refsect1 id="GtkApplication.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkApplication"><type>GtkApplication</type></link> is a class that handles many important aspects
of a GTK+ application in a convenient fashion, without enforcing
a one-size-fits-all application model.</para>
<para>Currently, GtkApplication handles GTK initialization, application
uniqueness, session management, provides some basic scriptability and
desktop shell integration by exporting actions and menus and manages a
list of toplevel windows whose life-cycle is automatically tied to the
life-cycle of your application.</para>
<para>While GtkApplication works fine with plain <link linkend="GtkWindows"><type>GtkWindows</type></link>, it is recommended
to use it together with <link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link>.</para>
<para>When GDK threads are enabled, GtkApplication will acquire the GDK
lock when invoking actions that arrive from other processes.  The GDK
lock is not touched for local action invocations.  In order to have
actions invoked in a predictable context it is therefore recommended
that the GDK lock be held while invoking actions locally with
<link linkend="g-action-group-activate-action"><function>g_action_group_activate_action()</function></link>.  The same applies to actions
associated with <link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> and to the “activate” and
“open” <link linkend="GApplication"><type>GApplication</type></link> methods.</para>
<refsect3 id="automatic-resources"><title>Automatic resources</title><para><link linkend="GtkApplication"><type>GtkApplication</type></link> will automatically load menus from the <link linkend="GtkBuilder"><type>GtkBuilder</type></link>
resource located at "gtk/menus.ui", relative to the application's
resource base path (see <link linkend="g-application-set-resource-base-path"><function>g_application_set_resource_base_path()</function></link>).  The
menu with the ID "app-menu" is taken as the application's app menu
and the menu with the ID "menubar" is taken as the application's
menubar.  Additional menus (most interesting submenus) can be named
and accessed via <link linkend="gtk-application-get-menu-by-id"><function>gtk_application_get_menu_by_id()</function></link> which allows for
dynamic population of a part of the menu structure.</para>
<para>If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are
present then these files will be used in preference, depending on the value
of <link linkend="gtk-application-prefers-app-menu"><function>gtk_application_prefers_app_menu()</function></link>. If the resource "gtk/menus-common.ui"
is present it will be loaded as well. This is useful for storing items that
are referenced from both "gtk/menus-appmenu.ui" and
"gtk/menus-traditional.ui".</para>
<para>It is also possible to provide the menus manually using
<link linkend="gtk-application-set-app-menu"><function>gtk_application_set_app_menu()</function></link> and <link linkend="gtk-application-set-menubar"><function>gtk_application_set_menubar()</function></link>.</para>
<para><link linkend="GtkApplication"><type>GtkApplication</type></link> will also automatically setup an icon search path for
the default icon theme by appending "icons" to the resource base
path.  This allows your application to easily store its icons as
resources.  See <link linkend="gtk-icon-theme-add-resource-path"><function>gtk_icon_theme_add_resource_path()</function></link> for more
information.</para>
<para>If there is a resource located at "gtk/help-overlay.ui" which
defines a <link linkend="GtkShortcutsWindow"><type>GtkShortcutsWindow</type></link> with ID "help_overlay" then GtkApplication
associates an instance of this shortcuts window with each
<link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> and sets up the keyboard accelerator Control-?
to open it. To create a menu item that displays the
shortcuts window, associate the item with the action win.show-help-overlay.</para>
</refsect3>
<refsect3 id="gtkapplication"><title>A simple application</title><para><ulink url="https://gitlab.gnome.org/GNOME/gtk/tree/master/examples/bp/bloatpad.c">A simple example</ulink></para>
<para>GtkApplication optionally registers with a session manager
of the users session (if you set the <link linkend="GtkApplication--register-session"><type>“register-session”</type></link>
property) and offers various functionality related to the session
life-cycle.</para>
<para>An application can block various ways to end the session with
the <link linkend="gtk-application-inhibit"><function>gtk_application_inhibit()</function></link> function. Typical use cases for
this kind of inhibiting are long-running, uninterruptible operations,
such as burning a CD or performing a disk backup. The session
manager may not honor the inhibitor, but it can be expected to
inform the user about the negative consequences of ending the
session while inhibitors are present.</para>
</refsect3>
<refsect3 id="seealso"><title>See Also</title><para><ulink url="https://wiki.gnome.org/HowDoI/GtkApplication">HowDoI: Using GtkApplication</ulink>,
<ulink url="https://developer.gnome.org/gtk3/stable/gtk-getting-started.html#id-1.2.3.3">Getting Started with GTK: Basics</ulink></para>
</refsect3>

</refsect1>
<refsect1 id="GtkApplication.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-application-new" role="function">
<title>gtk_application_new&#160;()</title>
<indexterm zone="gtk-application-new"><primary>gtk_application_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkApplication"><returnvalue>GtkApplication</returnvalue></link>&#160;*
gtk_application_new (<parameter>const <link linkend="gchar"><type>gchar</type></link> *application_id</parameter>,
                     <parameter><link linkend="GApplicationFlags"><type>GApplicationFlags</type></link> flags</parameter>);</programlisting>
<para>Creates a new <link linkend="GtkApplication"><type>GtkApplication</type></link> instance.</para>
<para>When using <link linkend="GtkApplication"><type>GtkApplication</type></link>, it is not necessary to call <link linkend="gtk-init"><function>gtk_init()</function></link>
manually. It is called as soon as the application gets registered as
the primary instance.</para>
<para>Concretely, <link linkend="gtk-init"><function>gtk_init()</function></link> is called in the default handler for the
<link linkend="GApplication-startup"><type>“startup”</type></link> signal. Therefore, <link linkend="GtkApplication"><type>GtkApplication</type></link> subclasses should
chain up in their <link linkend="GApplication-startup"><type>“startup”</type></link> handler before using any GTK+ API.</para>
<para>Note that commandline arguments are not passed to <link linkend="gtk-init"><function>gtk_init()</function></link>.
All GTK+ functionality that is available via commandline arguments
can also be achieved by setting suitable environment variables
such as <literal>G_DEBUG</literal>, so this should not be a big
problem. If you absolutely must support GTK+ commandline arguments,
you can explicitly call <link linkend="gtk-init"><function>gtk_init()</function></link> before creating the application
instance.</para>
<para>If non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, the application ID must be valid.  See
<link linkend="g-application-id-is-valid"><function>g_application_id_is_valid()</function></link>.</para>
<para>If no application ID is given then some features (most notably application 
uniqueness) will be disabled.</para>
<refsect3 id="gtk-application-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application_id</para></entry>
<entry role="parameter_description"><para>The application ID. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>the application flags</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GtkApplication"><type>GtkApplication</type></link> instance</para>
</refsect3></refsect2>
<refsect2 id="gtk-application-add-window" role="function">
<title>gtk_application_add_window&#160;()</title>
<indexterm zone="gtk-application-add-window"><primary>gtk_application_add_window</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_add_window (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                            <parameter><link linkend="GtkWindow"><type>GtkWindow</type></link> *window</parameter>);</programlisting>
<para>Adds a window to <parameter>application</parameter>
.</para>
<para>This call can only happen after the <parameter>application</parameter>
 has started;
typically, you should add new application windows in response
to the emission of the <link linkend="GApplication-activate"><type>“activate”</type></link> signal.</para>
<para>This call is equivalent to setting the <link linkend="GtkWindow--application"><type>“application”</type></link>
property of <parameter>window</parameter>
 to <parameter>application</parameter>
.</para>
<para>Normally, the connection between the application and the window
will remain until the window is destroyed, but you can explicitly
remove it with <link linkend="gtk-application-remove-window"><function>gtk_application_remove_window()</function></link>.</para>
<para>GTK+ will keep the <parameter>application</parameter>
 running as long as it has
any windows.</para>
<refsect3 id="gtk-application-add-window.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>window</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkWindow"><type>GtkWindow</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-remove-window" role="function">
<title>gtk_application_remove_window&#160;()</title>
<indexterm zone="gtk-application-remove-window"><primary>gtk_application_remove_window</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_remove_window (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                               <parameter><link linkend="GtkWindow"><type>GtkWindow</type></link> *window</parameter>);</programlisting>
<para>Remove a window from <parameter>application</parameter>
.</para>
<para>If <parameter>window</parameter>
 belongs to <parameter>application</parameter>
 then this call is equivalent to
setting the <link linkend="GtkWindow--application"><type>“application”</type></link> property of <parameter>window</parameter>
 to
<link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<para>The application may stop running as a result of a call to this
function.</para>
<refsect3 id="gtk-application-remove-window.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>window</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkWindow"><type>GtkWindow</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-windows" role="function">
<title>gtk_application_get_windows&#160;()</title>
<indexterm zone="gtk-application-get-windows"><primary>gtk_application_get_windows</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
gtk_application_get_windows (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Gets a list of the <link linkend="GtkWindows"><type>GtkWindows</type></link> associated with <parameter>application</parameter>
.</para>
<para>The list is sorted by most recently focused window, such that the first
element is the currently focused window. (Useful for choosing a parent
for a transient window.)</para>
<para>The list that is returned should not be modified in any way. It will
only remain valid until the next focus change or window creation or
deletion.</para>
<refsect3 id="gtk-application-get-windows.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-windows.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GList"><type>GList</type></link> of <link linkend="GtkWindow"><type>GtkWindow</type></link>. </para>
<para><emphasis role="annotation">[<acronym>element-type</acronym> GtkWindow][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-window-by-id" role="function">
<title>gtk_application_get_window_by_id&#160;()</title>
<indexterm zone="gtk-application-get-window-by-id"><primary>gtk_application_get_window_by_id</primary></indexterm>
<programlisting language="C"><link linkend="GtkWindow"><returnvalue>GtkWindow</returnvalue></link>&#160;*
gtk_application_get_window_by_id (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                                  <parameter><link linkend="guint"><type>guint</type></link> id</parameter>);</programlisting>
<para>Returns the <link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> with the given ID.</para>
<para>The ID of a <link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> can be retrieved with
<link linkend="gtk-application-window-get-id"><function>gtk_application_window_get_id()</function></link>.</para>
<refsect3 id="gtk-application-get-window-by-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>id</para></entry>
<entry role="parameter_description"><para>an identifier number</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-window-by-id.returns" role="returns">
<title>Returns</title>
<para>the window with ID <parameter>id</parameter>
, or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> if there is no window with this ID. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-active-window" role="function">
<title>gtk_application_get_active_window&#160;()</title>
<indexterm zone="gtk-application-get-active-window"><primary>gtk_application_get_active_window</primary></indexterm>
<programlisting language="C"><link linkend="GtkWindow"><returnvalue>GtkWindow</returnvalue></link>&#160;*
gtk_application_get_active_window (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Gets the “active” window for the application.</para>
<para>The active window is the one that was most recently focused (within
the application).  This window may not have the focus at the moment
if another application has it — this is just the most
recently-focused window within this application.</para>
<refsect3 id="gtk-application-get-active-window.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-active-window.returns" role="returns">
<title>Returns</title>
<para>the active window, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
there isn't one. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-inhibit" role="function">
<title>gtk_application_inhibit&#160;()</title>
<indexterm zone="gtk-application-inhibit"><primary>gtk_application_inhibit</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gtk_application_inhibit (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                         <parameter><link linkend="GtkWindow"><type>GtkWindow</type></link> *window</parameter>,
                         <parameter><link linkend="GtkApplicationInhibitFlags"><type>GtkApplicationInhibitFlags</type></link> flags</parameter>,
                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *reason</parameter>);</programlisting>
<para>Inform the session manager that certain types of actions should be
inhibited. This is not guaranteed to work on all platforms and for
all types of actions.</para>
<para>Applications should invoke this method when they begin an operation
that should not be interrupted, such as creating a CD or DVD. The
types of actions that may be blocked are specified by the <parameter>flags</parameter>

parameter. When the application completes the operation it should
call <link linkend="gtk-application-uninhibit"><function>gtk_application_uninhibit()</function></link> to remove the inhibitor. Note that
an application can have multiple inhibitors, and all of them must
be individually removed. Inhibitors are also cleared when the
application exits.</para>
<para>Applications should not expect that they will always be able to block
the action. In most cases, users will be given the option to force
the action to take place.</para>
<para>Reasons should be short and to the point.</para>
<para>If <parameter>window</parameter>
 is given, the session manager may point the user to
this window to find out more about why the action is inhibited.</para>
<refsect3 id="gtk-application-inhibit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>window</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkWindow"><type>GtkWindow</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>what types of actions should be inhibited</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>reason</para></entry>
<entry role="parameter_description"><para>a short, human-readable string that explains
why these operations are inhibited. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-inhibit.returns" role="returns">
<title>Returns</title>
<para> A non-zero cookie that is used to uniquely identify this
request. It should be used as an argument to <link linkend="gtk-application-uninhibit"><function>gtk_application_uninhibit()</function></link>
in order to remove the request. If the platform does not support
inhibiting or the request failed for some reason, 0 is returned.</para>
</refsect3></refsect2>
<refsect2 id="gtk-application-uninhibit" role="function">
<title>gtk_application_uninhibit&#160;()</title>
<indexterm zone="gtk-application-uninhibit"><primary>gtk_application_uninhibit</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_uninhibit (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                           <parameter><link linkend="guint"><type>guint</type></link> cookie</parameter>);</programlisting>
<para>Removes an inhibitor that has been established with <link linkend="gtk-application-inhibit"><function>gtk_application_inhibit()</function></link>.
Inhibitors are also cleared when the application exits.</para>
<refsect3 id="gtk-application-uninhibit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>cookie</para></entry>
<entry role="parameter_description"><para>a cookie that was returned by <link linkend="gtk-application-inhibit"><function>gtk_application_inhibit()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-prefers-app-menu" role="function">
<title>gtk_application_prefers_app_menu&#160;()</title>
<indexterm zone="gtk-application-prefers-app-menu"><primary>gtk_application_prefers_app_menu</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_application_prefers_app_menu (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Determines if the desktop environment in which the application is
running would prefer an application menu be shown.</para>
<para>If this function returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> then the application should call
<link linkend="gtk-application-set-app-menu"><function>gtk_application_set_app_menu()</function></link> with the contents of an application
menu, which will be shown by the desktop environment.  If it returns
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> then you should consider using an alternate approach, such as
a menubar.</para>
<para>The value returned by this function is purely advisory and you are
free to ignore it.  If you call <link linkend="gtk-application-set-app-menu"><function>gtk_application_set_app_menu()</function></link> even
if the desktop environment doesn't support app menus, then a fallback
will be provided.</para>
<para>Applications are similarly free not to set an app menu even if the
desktop environment wants to show one.  In that case, a fallback will
also be created by the desktop environment (GNOME, for example, uses
a menu with only a "Quit" item in it).</para>
<para>The value returned by this function never changes.  Once it returns a
particular value, it is guaranteed to always return the same value.</para>
<para>You may only call this function after the application has been
registered and after the base startup handler has run.  You're most
likely to want to use this from your own startup handler.  It may
also make sense to consult this function while constructing UI (in
activate, open or an action activation handler) in order to determine
if you should show a gear menu or not.</para>
<para>This function will return <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on Mac OS and a default app menu
will be created automatically with the "usual" contents of that menu
typical to most Mac OS applications.  If you call
<link linkend="gtk-application-set-app-menu"><function>gtk_application_set_app_menu()</function></link> anyway, then this menu will be
replaced with your own.</para>
<refsect3 id="gtk-application-prefers-app-menu.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-prefers-app-menu.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if you should set an app menu</para>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-app-menu" role="function">
<title>gtk_application_get_app_menu&#160;()</title>
<indexterm zone="gtk-application-get-app-menu"><primary>gtk_application_get_app_menu</primary></indexterm>
<programlisting language="C"><link linkend="GMenuModel"><returnvalue>GMenuModel</returnvalue></link>&#160;*
gtk_application_get_app_menu (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Returns the menu model that has been set with
<link linkend="gtk-application-set-app-menu"><function>gtk_application_set_app_menu()</function></link>.</para>
<refsect3 id="gtk-application-get-app-menu.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-app-menu.returns" role="returns">
<title>Returns</title>
<para>the application menu of <parameter>application</parameter>
or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no application menu has been set. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-set-app-menu" role="function">
<title>gtk_application_set_app_menu&#160;()</title>
<indexterm zone="gtk-application-set-app-menu"><primary>gtk_application_set_app_menu</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_set_app_menu (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                              <parameter><link linkend="GMenuModel"><type>GMenuModel</type></link> *app_menu</parameter>);</programlisting>
<para>Sets or unsets the application menu for <parameter>application</parameter>
.</para>
<para>This can only be done in the primary instance of the application,
after it has been registered.  <link linkend="GApplication-startup"><type>“startup”</type></link> is a good place
to call this.</para>
<para>The application menu is a single menu containing items that typically
impact the application as a whole, rather than acting on a specific
window or document.  For example, you would expect to see
“Preferences” or “Quit” in an application menu, but not “Save” or
“Print”.</para>
<para>If supported, the application menu will be rendered by the desktop
environment.</para>
<para>Use the base <link linkend="GActionMap"><type>GActionMap</type></link> interface to add actions, to respond to the user
selecting these menu items.</para>
<refsect3 id="gtk-application-set-app-menu.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>app_menu</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMenuModel"><type>GMenuModel</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-menubar" role="function">
<title>gtk_application_get_menubar&#160;()</title>
<indexterm zone="gtk-application-get-menubar"><primary>gtk_application_get_menubar</primary></indexterm>
<programlisting language="C"><link linkend="GMenuModel"><returnvalue>GMenuModel</returnvalue></link>&#160;*
gtk_application_get_menubar (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Returns the menu model that has been set with
<link linkend="gtk-application-set-menubar"><function>gtk_application_set_menubar()</function></link>.</para>
<refsect3 id="gtk-application-get-menubar.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-menubar.returns" role="returns">
<title>Returns</title>
<para>the menubar for windows of <parameter>application</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-set-menubar" role="function">
<title>gtk_application_set_menubar&#160;()</title>
<indexterm zone="gtk-application-set-menubar"><primary>gtk_application_set_menubar</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_set_menubar (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                             <parameter><link linkend="GMenuModel"><type>GMenuModel</type></link> *menubar</parameter>);</programlisting>
<para>Sets or unsets the menubar for windows of <parameter>application</parameter>
.</para>
<para>This is a menubar in the traditional sense.</para>
<para>This can only be done in the primary instance of the application,
after it has been registered.  <link linkend="GApplication-startup"><type>“startup”</type></link> is a good place
to call this.</para>
<para>Depending on the desktop environment, this may appear at the top of
each window, or at the top of the screen.  In some environments, if
both the application menu and the menubar are set, the application
menu will be presented as if it were the first item of the menubar.
Other environments treat the two as completely separate — for example,
the application menu may be rendered by the desktop shell while the
menubar (if set) remains in each individual window.</para>
<para>Use the base <link linkend="GActionMap"><type>GActionMap</type></link> interface to add actions, to respond to the
user selecting these menu items.</para>
<refsect3 id="gtk-application-set-menubar.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>menubar</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMenuModel"><type>GMenuModel</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-menu-by-id" role="function">
<title>gtk_application_get_menu_by_id&#160;()</title>
<indexterm zone="gtk-application-get-menu-by-id"><primary>gtk_application_get_menu_by_id</primary></indexterm>
<programlisting language="C"><link linkend="GMenu"><returnvalue>GMenu</returnvalue></link>&#160;*
gtk_application_get_menu_by_id (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                                <parameter>const <link linkend="gchar"><type>gchar</type></link> *id</parameter>);</programlisting>
<para>Gets a menu from automatically loaded resources.
See <link linkend="automatic-resources">Automatic resources</link>
for more information.</para>
<refsect3 id="gtk-application-get-menu-by-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>id</para></entry>
<entry role="parameter_description"><para>the id of the menu to look up</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-menu-by-id.returns" role="returns">
<title>Returns</title>
<para>Gets the menu with the
given id from the automatically loaded resources. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-list-action-descriptions" role="function">
<title>gtk_application_list_action_descriptions&#160;()</title>
<indexterm zone="gtk-application-list-action-descriptions"><primary>gtk_application_list_action_descriptions</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
gtk_application_list_action_descriptions
                               (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>);</programlisting>
<para>Lists the detailed action names which have associated accelerators.
See <link linkend="gtk-application-set-accels-for-action"><function>gtk_application_set_accels_for_action()</function></link>.</para>
<refsect3 id="gtk-application-list-action-descriptions.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-list-action-descriptions.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings,
free with <link linkend="g-strfreev"><function>g_strfreev()</function></link> when done. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-accels-for-action" role="function">
<title>gtk_application_get_accels_for_action&#160;()</title>
<indexterm zone="gtk-application-get-accels-for-action"><primary>gtk_application_get_accels_for_action</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
gtk_application_get_accels_for_action (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                                       <parameter>const <link linkend="gchar"><type>gchar</type></link> *detailed_action_name</parameter>);</programlisting>
<para>Gets the accelerators that are currently associated with
the given action.</para>
<refsect3 id="gtk-application-get-accels-for-action.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>detailed_action_name</para></entry>
<entry role="parameter_description"><para>a detailed action name, specifying an action
and target to obtain accelerators for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-accels-for-action.returns" role="returns">
<title>Returns</title>
<para>accelerators for <parameter>detailed_action_name</parameter>
, as
a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array. Free with <link linkend="g-strfreev"><function>g_strfreev()</function></link> when no longer needed. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-application-set-accels-for-action" role="function">
<title>gtk_application_set_accels_for_action&#160;()</title>
<indexterm zone="gtk-application-set-accels-for-action"><primary>gtk_application_set_accels_for_action</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_application_set_accels_for_action (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                                       <parameter>const <link linkend="gchar"><type>gchar</type></link> *detailed_action_name</parameter>,
                                       <parameter>const <link linkend="gchar"><type>gchar</type></link> * const *accels</parameter>);</programlisting>
<para>Sets zero or more keyboard accelerators that will trigger the
given action. The first item in <parameter>accels</parameter>
 will be the primary
accelerator, which may be displayed in the UI.</para>
<para>To remove all accelerators for an action, use an empty, zero-terminated
array for <parameter>accels</parameter>
.</para>
<para>For the <parameter>detailed_action_name</parameter>
, see <link linkend="g-action-parse-detailed-name"><function>g_action_parse_detailed_name()</function></link> and
<link linkend="g-action-print-detailed-name"><function>g_action_print_detailed_name()</function></link>.</para>
<refsect3 id="gtk-application-set-accels-for-action.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>detailed_action_name</para></entry>
<entry role="parameter_description"><para>a detailed action name, specifying an action
and target to associate accelerators with</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accels</para></entry>
<entry role="parameter_description"><para>a list of accelerators in the format
understood by <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-application-get-actions-for-accel" role="function">
<title>gtk_application_get_actions_for_accel&#160;()</title>
<indexterm zone="gtk-application-get-actions-for-accel"><primary>gtk_application_get_actions_for_accel</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
gtk_application_get_actions_for_accel (<parameter><link linkend="GtkApplication"><type>GtkApplication</type></link> *application</parameter>,
                                       <parameter>const <link linkend="gchar"><type>gchar</type></link> *accel</parameter>);</programlisting>
<para>Returns the list of actions (possibly empty) that <parameter>accel</parameter>
 maps to.
Each item in the list is a detailed action name in the usual form.</para>
<para>This might be useful to discover if an accel already exists in
order to prevent installation of a conflicting accelerator (from
an accelerator editor or a plugin system, for example). Note that
having more than one action per accelerator may not be a bad thing
and might make sense in cases where the actions never appear in the
same context.</para>
<para>In case there are no actions for a given accelerator, an empty array
is returned.  <link linkend="NULL:CAPS"><literal>NULL</literal></link> is never returned.</para>
<para>It is a programmer error to pass an invalid accelerator string.
If you are unsure, check it with <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link> first.</para>
<refsect3 id="gtk-application-get-actions-for-accel.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkApplication"><type>GtkApplication</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accel</para></entry>
<entry role="parameter_description"><para>an accelerator that can be parsed by <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-application-get-actions-for-accel.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of actions for <parameter>accel</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkApplication.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkApplication-struct" role="struct">
<title>struct GtkApplication</title>
<indexterm zone="GtkApplication-struct"><primary>GtkApplication</primary></indexterm>
<programlisting language="C">struct GtkApplication;</programlisting>
</refsect2>
<refsect2 id="GtkApplicationClass" role="struct">
<title>struct GtkApplicationClass</title>
<indexterm zone="GtkApplicationClass"><primary>GtkApplicationClass</primary></indexterm>
<programlisting language="C">struct GtkApplicationClass {
  GApplicationClass parent_class;

  void (*window_added)   (GtkApplication *application,
                          GtkWindow      *window);
  void (*window_removed) (GtkApplication *application,
                          GtkWindow      *window);
};
</programlisting>
<refsect3 id="GtkApplicationClass.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkApplicationClass.window-added">window_added</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Signal emitted when a <link linkend="GtkWindow"><type>GtkWindow</type></link> is added to
application through <link linkend="gtk-application-add-window"><function>gtk_application_add_window()</function></link>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkApplicationClass.window-removed">window_removed</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Signal emitted when a <link linkend="GtkWindow"><type>GtkWindow</type></link> is removed from
application, either as a side-effect of being destroyed or
explicitly through <link linkend="gtk-application-remove-window"><function>gtk_application_remove_window()</function></link>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="GtkApplicationInhibitFlags" role="enum">
<title>enum GtkApplicationInhibitFlags</title>
<indexterm zone="GtkApplicationInhibitFlags"><primary>GtkApplicationInhibitFlags</primary></indexterm>
<para>Types of user actions that may be blocked by <link linkend="gtk-application-inhibit"><function>gtk_application_inhibit()</function></link>.</para>
<refsect3 id="GtkApplicationInhibitFlags.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GTK-APPLICATION-INHIBIT-LOGOUT:CAPS">GTK_APPLICATION_INHIBIT_LOGOUT</para></entry>
<entry role="enum_member_description"><para>Inhibit ending the user session
by logging out or by shutting down the computer</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-APPLICATION-INHIBIT-SWITCH:CAPS">GTK_APPLICATION_INHIBIT_SWITCH</para></entry>
<entry role="enum_member_description"><para>Inhibit user switching</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-APPLICATION-INHIBIT-SUSPEND:CAPS">GTK_APPLICATION_INHIBIT_SUSPEND</para></entry>
<entry role="enum_member_description"><para>Inhibit suspending the
session or computer</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-APPLICATION-INHIBIT-IDLE:CAPS">GTK_APPLICATION_INHIBIT_IDLE</para></entry>
<entry role="enum_member_description"><para>Inhibit the session being
marked as idle (and possibly locked)</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkApplication.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkApplication--active-window" role="property"><title>The <literal>“active-window”</literal> property</title>
<indexterm zone="GtkApplication--active-window"><primary>GtkApplication:active-window</primary></indexterm>
<programlisting>  “active-window”            <link linkend="GtkWindow"><type>GtkWindow</type></link>&#160;*</programlisting>
<para>The window which most recently had focus.</para><para>Owner: GtkApplication</para>
<para>Flags: Read</para>
</refsect2>
<refsect2 id="GtkApplication--app-menu" role="property"><title>The <literal>“app-menu”</literal> property</title>
<indexterm zone="GtkApplication--app-menu"><primary>GtkApplication:app-menu</primary></indexterm>
<programlisting>  “app-menu”                 <link linkend="GMenuModel"><type>GMenuModel</type></link>&#160;*</programlisting>
<para>The GMenuModel for the application menu.</para><para>Owner: GtkApplication</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkApplication--menubar" role="property"><title>The <literal>“menubar”</literal> property</title>
<indexterm zone="GtkApplication--menubar"><primary>GtkApplication:menubar</primary></indexterm>
<programlisting>  “menubar”                  <link linkend="GMenuModel"><type>GMenuModel</type></link>&#160;*</programlisting>
<para>The GMenuModel for the menubar.</para><para>Owner: GtkApplication</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkApplication--register-session" role="property"><title>The <literal>“register-session”</literal> property</title>
<indexterm zone="GtkApplication--register-session"><primary>GtkApplication:register-session</primary></indexterm>
<programlisting>  “register-session”         <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>Set this property to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to register with the session manager.
This will make GTK+ track the session state (such as the
<link linkend="GtkApplication--screensaver-active"><type>“screensaver-active”</type></link> property).</para>
<para>Owner: GtkApplication</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkApplication--screensaver-active" role="property"><title>The <literal>“screensaver-active”</literal> property</title>
<indexterm zone="GtkApplication--screensaver-active"><primary>GtkApplication:screensaver-active</primary></indexterm>
<programlisting>  “screensaver-active”       <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>This property is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if GTK+ believes that the screensaver is
currently active. GTK+ only tracks session state (including this)
when <link linkend="GtkApplication--register-session"><type>“register-session”</type></link> is set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.</para>
<para>Tracking the screensaver state is supported on Linux.</para>
<para>Owner: GtkApplication</para>
<para>Flags: Read</para>
<para>Default value: FALSE</para>
</refsect2>

</refsect1>
<refsect1 id="GtkApplication.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GtkApplication-query-end" role="signal"><title>The <literal>“query-end”</literal> signal</title>
<indexterm zone="GtkApplication-query-end"><primary>GtkApplication::query-end</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GtkApplication"><type>GtkApplication</type></link> *application,
               <link linkend="gpointer"><type>gpointer</type></link>        user_data)</programlisting>
<para>Emitted when the session manager is about to end the session, only
if <link linkend="GtkApplication--register-session"><type>“register-session”</type></link> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. Applications can
connect to this signal and call <link linkend="gtk-application-inhibit"><function>gtk_application_inhibit()</function></link> with
<link linkend="GTK-APPLICATION-INHIBIT-LOGOUT:CAPS"><literal>GTK_APPLICATION_INHIBIT_LOGOUT</literal></link> to delay the end of the session
until state has been saved.</para>
<refsect3 id="GtkApplication-query-end.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkApplication"><type>GtkApplication</type></link> which emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></para>
</refsect2><refsect2 id="GtkApplication-window-added" role="signal"><title>The <literal>“window-added”</literal> signal</title>
<indexterm zone="GtkApplication-window-added"><primary>GtkApplication::window-added</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GtkApplication"><type>GtkApplication</type></link> *application,
               <link linkend="GtkWindow"><type>GtkWindow</type></link>      *window,
               <link linkend="gpointer"><type>gpointer</type></link>        user_data)</programlisting>
<para>Emitted when a <link linkend="GtkWindow"><type>GtkWindow</type></link> is added to <parameter>application</parameter>
 through
<link linkend="gtk-application-add-window"><function>gtk_application_add_window()</function></link>.</para>
<refsect3 id="GtkApplication-window-added.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkApplication"><type>GtkApplication</type></link> which emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>window</para></entry>
<entry role="parameter_description"><para>the newly-added <link linkend="GtkWindow"><type>GtkWindow</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></para>
</refsect2><refsect2 id="GtkApplication-window-removed" role="signal"><title>The <literal>“window-removed”</literal> signal</title>
<indexterm zone="GtkApplication-window-removed"><primary>GtkApplication::window-removed</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GtkApplication"><type>GtkApplication</type></link> *application,
               <link linkend="GtkWindow"><type>GtkWindow</type></link>      *window,
               <link linkend="gpointer"><type>gpointer</type></link>        user_data)</programlisting>
<para>Emitted when a <link linkend="GtkWindow"><type>GtkWindow</type></link> is removed from <parameter>application</parameter>
,
either as a side-effect of being destroyed or explicitly
through <link linkend="gtk-application-remove-window"><function>gtk_application_remove_window()</function></link>.</para>
<refsect3 id="GtkApplication-window-removed.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkApplication"><type>GtkApplication</type></link> which emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>window</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkWindow"><type>GtkWindow</type></link> that is being removed</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-FIRST:CAPS">Run First</link></para>
</refsect2>
</refsect1>

</refentry>
