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

<refsect1 id="gtk4-Keyboard-Accelerators.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="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-accelerator-valid">gtk_accelerator_valid</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-accelerator-parse">gtk_accelerator_parse</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-accelerator-name">gtk_accelerator_name</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-accelerator-get-label">gtk_accelerator_get_label</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-accelerator-parse-with-keycode">gtk_accelerator_parse_with_keycode</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-accelerator-name-with-keycode">gtk_accelerator_name_with_keycode</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-accelerator-get-label-with-keycode">gtk_accelerator_get_label_with_keycode</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GdkModifierType"><returnvalue>GdkModifierType</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-accelerator-get-default-mod-mask">gtk_accelerator_get_default_mod_mask</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

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

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

<refsect1 id="gtk4-Keyboard-Accelerators.description" role="desc">
<title role="desc.title">Description</title>
<para>We have various utility functions to parse and generate
textual representations of keyboard accelerators.</para>
<para>If you want to set up keyboard accelerators for widgets,
<link linkend="GtkShortcutTrigger"><type>GtkShortcutTrigger</type></link> is probably more convenient than the
functions in this section.</para>

</refsect1>
<refsect1 id="gtk4-Keyboard-Accelerators.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-accelerator-valid" role="function">
<title>gtk_accelerator_valid&#160;()</title>
<indexterm zone="gtk-accelerator-valid"><primary>gtk_accelerator_valid</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_accelerator_valid (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>,
                       <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> modifiers</parameter>);</programlisting>
<para>Determines whether a given keyval and modifier mask constitute
a valid keyboard accelerator. For example, the <link linkend="GDK-KEY-a"><type>GDK_KEY_a</type></link> keyval
plus <link linkend="GDK-CONTROL-MASK:CAPS"><type>GDK_CONTROL_MASK</type></link> is valid - this is a “Ctrl+a” accelerator.
But, you can't, for instance, use the <link linkend="GDK-KEY-Control-L"><type>GDK_KEY_Control_L</type></link> keyval
as an accelerator.</para>
<refsect3 id="gtk-accelerator-valid.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>keyval</para></entry>
<entry role="parameter_description"><para>a GDK keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>modifiers</para></entry>
<entry role="parameter_description"><para>modifier mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-valid.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the accelerator is valid</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-parse" role="function">
<title>gtk_accelerator_parse&#160;()</title>
<indexterm zone="gtk-accelerator-parse"><primary>gtk_accelerator_parse</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_accelerator_parse (<parameter>const <link linkend="gchar"><type>gchar</type></link> *accelerator</parameter>,
                       <parameter><link linkend="guint"><type>guint</type></link> *accelerator_key</parameter>,
                       <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> *accelerator_mods</parameter>);</programlisting>
<para>Parses a string representing an accelerator. The format looks like
“&lt;Control>a” or “&lt;Shift>&lt;Alt>F1”.</para>
<para>The parser is fairly liberal and allows lower or upper case, and also
abbreviations such as “&lt;Ctl>” and “&lt;Ctrl>”. Key names are parsed using
<link linkend="gdk-keyval-from-name"><function>gdk_keyval_from_name()</function></link>. For character keys the name is not the symbol,
but the lowercase name, e.g. one would use “&lt;Ctrl>minus” instead of
“&lt;Ctrl>-”.</para>
<para>If the parse fails, <parameter>accelerator_key</parameter>
 and <parameter>accelerator_mods</parameter>
 will
be set to 0 (zero).</para>
<refsect3 id="gtk-accelerator-parse.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>accelerator</para></entry>
<entry role="parameter_description"><para>string representing an accelerator</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accelerator_key</para></entry>
<entry role="parameter_description"><para>return location for accelerator
keyval, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>return location for accelerator
modifier mask, <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-name" role="function">
<title>gtk_accelerator_name&#160;()</title>
<indexterm zone="gtk-accelerator-name"><primary>gtk_accelerator_name</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gtk_accelerator_name (<parameter><link linkend="guint"><type>guint</type></link> accelerator_key</parameter>,
                      <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> accelerator_mods</parameter>);</programlisting>
<para>Converts an accelerator keyval and modifier mask into a string
parseable by <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link>. For example, if you pass in
<link linkend="GDK-KEY-q"><type>GDK_KEY_q</type></link> and <link linkend="GDK-CONTROL-MASK:CAPS"><type>GDK_CONTROL_MASK</type></link>, this function returns “&lt;Control>q”.</para>
<para>If you need to display accelerators in the user interface,
see <link linkend="gtk-accelerator-get-label"><function>gtk_accelerator_get_label()</function></link>.</para>
<refsect3 id="gtk-accelerator-name.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>accelerator_key</para></entry>
<entry role="parameter_description"><para>accelerator keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>accelerator modifier mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-name.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated accelerator name</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-get-label" role="function">
<title>gtk_accelerator_get_label&#160;()</title>
<indexterm zone="gtk-accelerator-get-label"><primary>gtk_accelerator_get_label</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gtk_accelerator_get_label (<parameter><link linkend="guint"><type>guint</type></link> accelerator_key</parameter>,
                           <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> accelerator_mods</parameter>);</programlisting>
<para>Converts an accelerator keyval and modifier mask into a string
which can be used to represent the accelerator to the user.</para>
<refsect3 id="gtk-accelerator-get-label.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>accelerator_key</para></entry>
<entry role="parameter_description"><para>accelerator keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>accelerator modifier mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-get-label.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string representing the accelerator.</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-parse-with-keycode" role="function">
<title>gtk_accelerator_parse_with_keycode&#160;()</title>
<indexterm zone="gtk-accelerator-parse-with-keycode"><primary>gtk_accelerator_parse_with_keycode</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_accelerator_parse_with_keycode (<parameter>const <link linkend="gchar"><type>gchar</type></link> *accelerator</parameter>,
                                    <parameter><link linkend="GdkDisplay"><type>GdkDisplay</type></link> *display</parameter>,
                                    <parameter><link linkend="guint"><type>guint</type></link> *accelerator_key</parameter>,
                                    <parameter><link linkend="guint"><type>guint</type></link> **accelerator_codes</parameter>,
                                    <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> *accelerator_mods</parameter>);</programlisting>
<para>Parses a string representing an accelerator, similarly to
<link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link> but handles keycodes as well. This is only
useful for system-level components, applications should use
<link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link> instead.</para>
<para>If <parameter>accelerator_codes</parameter>
 is given and the result stored in it is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>,
the result must be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
<para>If a keycode is present in the accelerator and no <parameter>accelerator_codes</parameter>

is given, the parse will fail.</para>
<para>If the parse fails, <parameter>accelerator_key</parameter>
, <parameter>accelerator_mods</parameter>
 and
<parameter>accelerator_codes</parameter>
 will be set to 0 (zero).</para>
<refsect3 id="gtk-accelerator-parse-with-keycode.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>accelerator</para></entry>
<entry role="parameter_description"><para>string representing an accelerator</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>display</para></entry>
<entry role="parameter_description"><para>the <link linkend="GdkDisplay"><type>GdkDisplay</type></link> to look up <parameter>accelerator_codes</parameter>
in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_key</para></entry>
<entry role="parameter_description"><para>return location for accelerator
keyval, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_codes</para></entry>
<entry role="parameter_description"><para>return location for accelerator keycodes, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>array</acronym> zero-terminated=1][<acronym>transfer full</acronym>][<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>return location for accelerator
modifier mask, <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-parse-with-keycode.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if parsing succeeded</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-name-with-keycode" role="function">
<title>gtk_accelerator_name_with_keycode&#160;()</title>
<indexterm zone="gtk-accelerator-name-with-keycode"><primary>gtk_accelerator_name_with_keycode</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gtk_accelerator_name_with_keycode (<parameter><link linkend="GdkDisplay"><type>GdkDisplay</type></link> *display</parameter>,
                                   <parameter><link linkend="guint"><type>guint</type></link> accelerator_key</parameter>,
                                   <parameter><link linkend="guint"><type>guint</type></link> keycode</parameter>,
                                   <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> accelerator_mods</parameter>);</programlisting>
<para>Converts an accelerator keyval and modifier mask
into a string parseable by <link linkend="gtk-accelerator-parse-with-keycode"><function>gtk_accelerator_parse_with_keycode()</function></link>,
similarly to <link linkend="gtk-accelerator-name"><function>gtk_accelerator_name()</function></link> but handling keycodes.
This is only useful for system-level components, applications
should use <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link> instead.</para>
<refsect3 id="gtk-accelerator-name-with-keycode.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>display</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDisplay"><type>GdkDisplay</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to use the default display. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_key</para></entry>
<entry role="parameter_description"><para>accelerator keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>keycode</para></entry>
<entry role="parameter_description"><para>accelerator keycode</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>accelerator modifier mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-name-with-keycode.returns" role="returns">
<title>Returns</title>
<para> a newly allocated accelerator name.</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-get-label-with-keycode" role="function">
<title>gtk_accelerator_get_label_with_keycode&#160;()</title>
<indexterm zone="gtk-accelerator-get-label-with-keycode"><primary>gtk_accelerator_get_label_with_keycode</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gtk_accelerator_get_label_with_keycode
                               (<parameter><link linkend="GdkDisplay"><type>GdkDisplay</type></link> *display</parameter>,
                                <parameter><link linkend="guint"><type>guint</type></link> accelerator_key</parameter>,
                                <parameter><link linkend="guint"><type>guint</type></link> keycode</parameter>,
                                <parameter><link linkend="GdkModifierType"><type>GdkModifierType</type></link> accelerator_mods</parameter>);</programlisting>
<para>Converts an accelerator keyval and modifier mask
into a (possibly translated) string that can be displayed to
a user, similarly to <link linkend="gtk-accelerator-get-label"><function>gtk_accelerator_get_label()</function></link>, but handling
keycodes.</para>
<para>This is only useful for system-level components, applications
should use <link linkend="gtk-accelerator-parse"><function>gtk_accelerator_parse()</function></link> instead.</para>
<refsect3 id="gtk-accelerator-get-label-with-keycode.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>display</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDisplay"><type>GdkDisplay</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to use the default display. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>accelerator_key</para></entry>
<entry role="parameter_description"><para>accelerator keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>keycode</para></entry>
<entry role="parameter_description"><para>accelerator keycode</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accelerator_mods</para></entry>
<entry role="parameter_description"><para>accelerator modifier mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-accelerator-get-label-with-keycode.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string representing the accelerator.</para>
</refsect3></refsect2>
<refsect2 id="gtk-accelerator-get-default-mod-mask" role="function">
<title>gtk_accelerator_get_default_mod_mask&#160;()</title>
<indexterm zone="gtk-accelerator-get-default-mod-mask"><primary>gtk_accelerator_get_default_mod_mask</primary></indexterm>
<programlisting language="C"><link linkend="GdkModifierType"><returnvalue>GdkModifierType</returnvalue></link>
gtk_accelerator_get_default_mod_mask (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the modifier mask.</para>
<para>The modifier mask determines which modifiers are considered significant
for keyboard accelerators. This includes all keyboard modifiers except
for <link linkend="GDK-LOCK-MASK:CAPS"><literal>GDK_LOCK_MASK</literal></link>.</para>
<refsect3 id="gtk-accelerator-get-default-mod-mask.returns" role="returns">
<title>Returns</title>
<para> the modifier mask for accelerators</para>
</refsect3></refsect2>

</refsect1>

</refentry>
