<?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="GtkPopoverMenu">
<refmeta>
<refentrytitle role="top_of_page" id="GtkPopoverMenu.top_of_page">GtkPopoverMenu</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkPopoverMenu</refname>
<refpurpose>Popovers to use as menus</refpurpose>
</refnamediv>

<refsect1 id="GtkPopoverMenu.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="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-popover-menu-new-from-model">gtk_popover_menu_new_from_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-popover-menu-new-from-model-full">gtk_popover_menu_new_from_model_full</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-popover-menu-set-menu-model">gtk_popover_menu_set_menu_model</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-popover-menu-get-menu-model">gtk_popover_menu_get_menu_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkPopoverMenu.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="GMenuModel"><type>GMenuModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkPopoverMenu--menu-model">menu-model</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkPopoverMenu--visible-submenu">visible-submenu</link></entry><entry role="property_flags">Read / Write</entry></row>

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

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkPopoverMenu.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="GInitiallyUnowned">GInitiallyUnowned</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkWidget">GtkWidget</link>
            <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkPopover">GtkPopover</link>
                <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkPopoverMenu
</screen>
</refsect1>
<refsect1 id="GtkPopoverMenu.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkPopoverMenu implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link>,  <link linkend="GtkConstraintTarget">GtkConstraintTarget</link>,  <link linkend="GtkShortcutManager">GtkShortcutManager</link> and  <link linkend="GtkNative">GtkNative</link>.</para>

</refsect1>

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

<refsect1 id="GtkPopoverMenu.description" role="desc">
<title role="desc.title">Description</title>
<para>GtkPopoverMenu is a subclass of <link linkend="GtkPopover"><type>GtkPopover</type></link> that treats its
children like menus and allows switching between them. It
can open submenus as traditional, nested submenus, or in a
more touch-friendly sliding fashion.</para>
<para>GtkPopoverMenu is meant to be used primarily with menu models,
using <link linkend="gtk-popover-menu-new-from-model"><function>gtk_popover_menu_new_from_model()</function></link>. If you need to put other
widgets such as <link linkend="GtkSpinButton"><type>GtkSpinButton</type></link> or <link linkend="GtkSwitch"><type>GtkSwitch</type></link> into a popover,
use a plain <link linkend="GtkPopover"><type>GtkPopover</type></link>.</para>
<refsect3><title>Menu models</title><para>The XML format understood by <link linkend="GtkBuilder"><type>GtkBuilder</type></link> for <link linkend="GMenuModel"><type>GMenuModel</type></link> consists
of a toplevel <literal>&lt;menu&gt;</literal> element, which contains one or more <literal>&lt;item&gt;</literal>
elements. Each <literal>&lt;item&gt;</literal> element contains <literal>&lt;attribute&gt;</literal> and <literal>&lt;link&gt;</literal>
elements with a mandatory name attribute. <literal>&lt;link&gt;</literal> elements have the
same content model as <literal>&lt;menu&gt;</literal>. Instead of <literal>&lt;link name="submenu&gt;</literal> or
<literal>&lt;link name="section"&gt;</literal>, you can use <literal>&lt;submenu&gt;</literal> or <literal>&lt;section&gt;</literal>
elements.</para>
<informalexample><programlisting role="example"><![CDATA[
<menu id='app-menu'>
  <section>
    <item>
      <attribute name='label' translatable='yes'>_New Window</attribute>
      <attribute name='action'>app.new</attribute>
    </item>
    <item>
      <attribute name='label' translatable='yes'>_About Sunny</attribute>
      <attribute name='action'>app.about</attribute>
    </item>
    <item>
      <attribute name='label' translatable='yes'>_Quit</attribute>
      <attribute name='action'>app.quit</attribute>
    </item>
  </section>
</menu>
]]></programlisting></informalexample>
<para></para>
<para>Attribute values can be translated using gettext, like other <link linkend="GtkBuilder"><type>GtkBuilder</type></link>
content. <literal>&lt;attribute&gt;</literal> elements can be marked for translation with a
<literal>translatable="yes"</literal> attribute. It is also possible to specify message
context and translator comments, using the context and comments attributes.
To make use of this, the <link linkend="GtkBuilder"><type>GtkBuilder</type></link> must have been given the gettext
domain to use.</para>
<para>The following attributes are used when constructing menu items:</para>
<itemizedlist>
<listitem><para>"label": a user-visible string to display</para></listitem>
<listitem><para>"action": the prefixed name of the action to trigger</para></listitem>
<listitem><para>"target": the parameter to use when activating the action</para></listitem>
<listitem><para>"icon" and "verb-icon": names of icons that may be displayed</para></listitem>
<listitem><para>"submenu-action": name of an action that may be used to determine
 if a submenu can be opened</para></listitem>
<listitem>
<para>"hidden-when": a string used to determine when the item will be hidden.
 Possible values include "action-disabled", "action-missing", "macos-menubar".
 This is mainly useful for exported menus, see <link linkend="gtk-application-set-menubar"><function>gtk_application_set_menubar()</function></link>.</para>
</listitem>
</itemizedlist>
<para>The following attributes are used when constructing sections:</para>
<itemizedlist>
<listitem><para>"label": a user-visible string to use as section heading</para></listitem>
<listitem><para>"display-hint": a string used to determine special formatting for the section.
Possible values include "horizontal-buttons", "circular-buttons" and "inline-buttons". They all indicate that section should be
displayed as a horizontal row of buttons.</para></listitem>
<listitem>
<para>"text-direction": a string used to determine the <link linkend="GtkTextDirection"><type>GtkTextDirection</type></link> to use
when "display-hint" is set to "horizontal-buttons". Possible values
include "rtl", "ltr", and "none".</para>
</listitem>
</itemizedlist>
<para>The following attributes are used when constructing submenus:</para>
<itemizedlist>
<listitem><para>"label": a user-visible string to display</para></listitem>
<listitem>
<para>"icon": icon name to display</para>
</listitem>
</itemizedlist>
<para>Menu items will also show accelerators, which are usually associated
with actions via <link linkend="gtk-application-set-accels-for-action"><function>gtk_application_set_accels_for_action()</function></link>,
<link linkend="gtk-widget-class-add-binding-action"><function>gtk_widget_class_add_binding_action()</function></link> or <link linkend="gtk-shortcut-controller-add-shortcut"><function>gtk_shortcut_controller_add_shortcut()</function></link>.</para>
</refsect3>
<refsect2><title>CSS Nodes</title><para><link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link> is just a subclass of <link linkend="GtkPopover"><type>GtkPopover</type></link> that adds
custom content to it, therefore it has the same CSS nodes.
It is one of the cases that add a .menu style class to
the popover's main node.</para>
</refsect2>

</refsect1>
<refsect1 id="GtkPopoverMenu.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-popover-menu-new-from-model" role="function">
<title>gtk_popover_menu_new_from_model&#160;()</title>
<indexterm zone="gtk-popover-menu-new-from-model"><primary>gtk_popover_menu_new_from_model</primary></indexterm>
<programlisting language="C"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
gtk_popover_menu_new_from_model (<parameter><link linkend="GMenuModel"><type>GMenuModel</type></link> *model</parameter>);</programlisting>
<para>Creates a <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link> and populates it according to
<parameter>model</parameter>
.</para>
<para>The created buttons are connected to actions found in the
<link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> to which the popover belongs - typically
by means of being attached to a widget that is contained within
the <link linkend="GtkApplicationWindows"><type>GtkApplicationWindows</type></link> widget hierarchy.</para>
<para>Actions can also be added using <link linkend="gtk-widget-insert-action-group"><function>gtk_widget_insert_action_group()</function></link>
on the menus attach widget or on any of its parent widgets.</para>
<para>This function creates menus with sliding submenus.
See <link linkend="gtk-popover-menu-new-from-model-full"><function>gtk_popover_menu_new_from_model_full()</function></link> for a way
to control this.</para>
<refsect3 id="gtk-popover-menu-new-from-model.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>model</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><refsect3 id="gtk-popover-menu-new-from-model.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-popover-menu-new-from-model-full" role="function">
<title>gtk_popover_menu_new_from_model_full&#160;()</title>
<indexterm zone="gtk-popover-menu-new-from-model-full"><primary>gtk_popover_menu_new_from_model_full</primary></indexterm>
<programlisting language="C"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
gtk_popover_menu_new_from_model_full (<parameter><link linkend="GMenuModel"><type>GMenuModel</type></link> *model</parameter>,
                                      <parameter><link linkend="GtkPopoverMenuFlags"><type>GtkPopoverMenuFlags</type></link> flags</parameter>);</programlisting>
<para>Creates a <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link> and populates it according to
<parameter>model</parameter>
.</para>
<para>The created buttons are connected to actions found in the
action groups that are accessible from the parent widget.
This includes the <link linkend="GtkApplicationWindow"><type>GtkApplicationWindow</type></link> to which the popover
belongs. Actions can also be added using <link linkend="gtk-widget-insert-action-group"><function>gtk_widget_insert_action_group()</function></link>
on the parent widget or on any of its parent widgets.</para>
<para>The only flag that is supported currently is
<link linkend="GTK-POPOVER-MENU-NESTED:CAPS"><type>GTK_POPOVER_MENU_NESTED</type></link>, which makes GTK create traditional,
nested submenus instead of the default sliding submenus.</para>
<refsect3 id="gtk-popover-menu-new-from-model-full.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>model</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMenuModel"><type>GMenuModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>flags that affect how the menu is created</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-popover-menu-new-from-model-full.returns" role="returns">
<title>Returns</title>
<para>the new <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-popover-menu-set-menu-model" role="function">
<title>gtk_popover_menu_set_menu_model&#160;()</title>
<indexterm zone="gtk-popover-menu-set-menu-model"><primary>gtk_popover_menu_set_menu_model</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_popover_menu_set_menu_model (<parameter><link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link> *popover</parameter>,
                                 <parameter><link linkend="GMenuModel"><type>GMenuModel</type></link> *model</parameter>);</programlisting>
<para>Sets a new menu model on <parameter>popover</parameter>
.</para>
<para>The existing contents of <parameter>popover</parameter>
 are removed, and
the <parameter>popover</parameter>
 is populated with new contents according
to <parameter>model</parameter>
.</para>
<refsect3 id="gtk-popover-menu-set-menu-model.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>popover</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>model</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>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-popover-menu-get-menu-model" role="function">
<title>gtk_popover_menu_get_menu_model&#160;()</title>
<indexterm zone="gtk-popover-menu-get-menu-model"><primary>gtk_popover_menu_get_menu_model</primary></indexterm>
<programlisting language="C"><link linkend="GMenuModel"><returnvalue>GMenuModel</returnvalue></link>&#160;*
gtk_popover_menu_get_menu_model (<parameter><link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link> *popover</parameter>);</programlisting>
<para>Returns the menu model used to populate the popover.</para>
<refsect3 id="gtk-popover-menu-get-menu-model.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>popover</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkPopoverMenu"><type>GtkPopoverMenu</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-popover-menu-get-menu-model.returns" role="returns">
<title>Returns</title>
<para>the menu model of <parameter>popover</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkPopoverMenu.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkPopoverMenu-struct" role="struct">
<title>GtkPopoverMenu</title>
<indexterm zone="GtkPopoverMenu-struct"><primary>GtkPopoverMenu</primary></indexterm>
<programlisting language="C">typedef struct _GtkPopoverMenu GtkPopoverMenu;</programlisting>
</refsect2>
<refsect2 id="GtkPopoverMenuFlags" role="enum">
<title>enum GtkPopoverMenuFlags</title>
<indexterm zone="GtkPopoverMenuFlags"><primary>GtkPopoverMenuFlags</primary></indexterm>
<para>Flags that affect how popover menus are created from
a menu model.</para>
<refsect3 id="GtkPopoverMenuFlags.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-POPOVER-MENU-NESTED:CAPS">GTK_POPOVER_MENU_NESTED</para></entry>
<entry role="enum_member_description"><para>Create submenus as nested
popovers. Without this flag, submenus are created as
sliding pages that replace the main menu.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkPopoverMenu.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkPopoverMenu--menu-model" role="property"><title>The <literal>“menu-model”</literal> property</title>
<indexterm zone="GtkPopoverMenu--menu-model"><primary>GtkPopoverMenu:menu-model</primary></indexterm>
<programlisting>  “menu-model”               <link linkend="GMenuModel"><type>GMenuModel</type></link>&#160;*</programlisting>
<para>The model from which the menu is made.</para><para>Owner: GtkPopoverMenu</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkPopoverMenu--visible-submenu" role="property"><title>The <literal>“visible-submenu”</literal> property</title>
<indexterm zone="GtkPopoverMenu--visible-submenu"><primary>GtkPopoverMenu:visible-submenu</primary></indexterm>
<programlisting>  “visible-submenu”          <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The name of the visible submenu.</para><para>Owner: GtkPopoverMenu</para>
<para>Flags: Read / Write</para>
<para>Default value: NULL</para>
</refsect2>

</refsect1>

</refentry>
