<refentry id="gtk-Accelerator-Maps">
<refmeta>
<refentrytitle>Accelerator Maps</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Accelerator Maps</refname><refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gtk/gtk.h&gt;


void        (<link linkend="GtkAccelMapForeach">*GtkAccelMapForeach</link>)           (<link linkend="gpointer">gpointer</link> data,
                                             const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods,
                                             <link linkend="gboolean">gboolean</link> changed);
void        <link linkend="gtk-accel-map-add-entry">gtk_accel_map_add_entry</link>         (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-accel-map-lookup-entry">gtk_accel_map_lookup_entry</link>      (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="GtkAccelKey">GtkAccelKey</link> *key);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-accel-map-change-entry">gtk_accel_map_change_entry</link>      (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods,
                                             <link linkend="gboolean">gboolean</link> replace);
void        <link linkend="gtk-accel-map-load">gtk_accel_map_load</link>              (const <link linkend="gchar">gchar</link> *file_name);
void        <link linkend="gtk-accel-map-save">gtk_accel_map_save</link>              (const <link linkend="gchar">gchar</link> *file_name);
void        <link linkend="gtk-accel-map-foreach">gtk_accel_map_foreach</link>           (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link> foreach_func);
void        <link linkend="gtk-accel-map-load-fd">gtk_accel_map_load_fd</link>           (<link linkend="gint">gint</link> fd);
void        <link linkend="gtk-accel-map-save-fd">gtk_accel_map_save_fd</link>           (<link linkend="gint">gint</link> fd);
void        <link linkend="gtk-accel-map-load-scanner">gtk_accel_map_load_scanner</link>      (<link linkend="GScanner">GScanner</link> *scanner);
void        <link linkend="gtk-accel-map-add-filter">gtk_accel_map_add_filter</link>        (const <link linkend="gchar">gchar</link> *filter_pattern);
void        <link linkend="gtk-accel-map-foreach-unfiltered">gtk_accel_map_foreach_unfiltered</link>
                                            (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link> foreach_func);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkAccelMapForeach">GtkAccelMapForeach ()</title>
<programlisting>void        (*GtkAccelMapForeach)           (<link linkend="gpointer">gpointer</link> data,
                                             const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods,
                                             <link linkend="gboolean">gboolean</link> changed);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>accel_path</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>accel_key</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>accel_mods</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>changed</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-add-entry">gtk_accel_map_add_entry ()</title>
<programlisting>void        gtk_accel_map_add_entry         (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods);</programlisting>
<para>
Registers a new accelerator with the global accelerator map.
This function should only be called once per <parameter>accel_path</parameter>
with the canonical <parameter>accel_key</parameter> and <parameter>accel_mods</parameter> for this path.
To change the accelerator during runtime programatically, use
<link linkend="gtk-accel-map-change-entry">gtk_accel_map_change_entry</link>().
The accelerator path must consist of "&lt;WINDOWTYPE&gt;/Category1/Category2/.../Action",
where &lt;WINDOWTYPE&gt; should be a unique application-specific identifier, that
corresponds to the kind of window the accelerator is being used in, e.g. "Gimp-Image",
"Abiword-Document" or "Gnumeric-Settings".
The Category1/.../Action portion is most appropriately chosen by the action the
accelerator triggers, i.e. for accelerators on menu items, choose the item's menu path,
e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All".
So a full valid accelerator path may look like:
"&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...".</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>accel_path</parameter>&nbsp;:</entry>
<entry> valid accelerator path
</entry></row>
<row><entry align="right"><parameter>accel_key</parameter>&nbsp;:</entry>
<entry>  the accelerator key
</entry></row>
<row><entry align="right"><parameter>accel_mods</parameter>&nbsp;:</entry>
<entry> the accelerator modifiers
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-lookup-entry">gtk_accel_map_lookup_entry ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_accel_map_lookup_entry      (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="GtkAccelKey">GtkAccelKey</link> *key);</programlisting>
<para>
Looks up the accelerator entry for <parameter>accel_path</parameter> and fills in <parameter>key</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>accel_path</parameter>&nbsp;:</entry>
<entry>  a valid accelerator path
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>         the accelerator key to be filled in (optional)
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>     <literal>TRUE</literal> if <parameter>accel_path</parameter> is known, <literal>FALSE</literal> otherwise
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-change-entry">gtk_accel_map_change_entry ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_accel_map_change_entry      (const <link linkend="gchar">gchar</link> *accel_path,
                                             <link linkend="guint">guint</link> accel_key,
                                             <link linkend="GdkModifierType">GdkModifierType</link> accel_mods,
                                             <link linkend="gboolean">gboolean</link> replace);</programlisting>
<para>
Changes the <parameter>accel_key</parameter> and <parameter>accel_mods</parameter> currently associated with <parameter>accel_path</parameter>.
Due to conflicts with other accelerators, a change may not always be possible,
<parameter>replace</parameter> indicates whether other accelerators may be deleted to resolve such
conflicts. A change will only occur if all conflicts could be resolved (which
might not be the case if conflicting accelerators are locked). Successful
changes are indicated by a <literal>TRUE</literal> return value.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>accel_path</parameter>&nbsp;:</entry>
<entry>  a valid accelerator path
</entry></row>
<row><entry align="right"><parameter>accel_key</parameter>&nbsp;:</entry>
<entry>   the new accelerator key
</entry></row>
<row><entry align="right"><parameter>accel_mods</parameter>&nbsp;:</entry>
<entry>  the new accelerator modifiers
</entry></row>
<row><entry align="right"><parameter>replace</parameter>&nbsp;:</entry>
<entry>     <literal>TRUE</literal> if other accelerators may be deleted upon conflicts
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>     <literal>TRUE</literal> if the accelerator could be changed, <literal>FALSE</literal> otherwise
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-load">gtk_accel_map_load ()</title>
<programlisting>void        gtk_accel_map_load              (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
Parses a file previously saved with <link linkend="gtk-accel-map-save">gtk_accel_map_save</link>() for
accelerator specifications, and propagates them accordingly.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>file_name</parameter>&nbsp;:</entry>
<entry> a file containing accelerator specifications
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-save">gtk_accel_map_save ()</title>
<programlisting>void        gtk_accel_map_save              (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
Saves current accelerator specifications (accelerator path, key
and modifiers) to <parameter>file_name</parameter>.
The file is written in a format suitable to be read back in by
<link linkend="gtk-accel-map-load">gtk_accel_map_load</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>file_name</parameter>&nbsp;:</entry>
<entry> the file to contain accelerator specifications
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-foreach">gtk_accel_map_foreach ()</title>
<programlisting>void        gtk_accel_map_foreach           (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link> foreach_func);</programlisting>
<para>
Loops over the entries in the accelerator map whose accel path 
doesn't match any of the filters added with <link linkend="gtk-accel-map-add-filter">gtk_accel_map_add_filter</link>(), 
and execute <parameter>foreach_func</parameter> on each. The signature of <parameter>foreach_func</parameter> is 
that of <link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link>, the <parameter>changed</parameter> parameter indicates whether
this accelerator was changed during runtime (thus, would need
saving during an accelerator map dump).</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>         data to be passed into <parameter>foreach_func</parameter>
</entry></row>
<row><entry align="right"><parameter>foreach_func</parameter>&nbsp;:</entry>
<entry> function to be executed for each accel map entry which
               is not filtered out
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-load-fd">gtk_accel_map_load_fd ()</title>
<programlisting>void        gtk_accel_map_load_fd           (<link linkend="gint">gint</link> fd);</programlisting>
<para>
Filedescriptor variant of <link linkend="gtk-accel-map-load">gtk_accel_map_load</link>().
</para>
<para>
Note that the file descriptor will not be closed by this function.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>fd</parameter>&nbsp;:</entry>
<entry> a valid readable file descriptor
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-save-fd">gtk_accel_map_save_fd ()</title>
<programlisting>void        gtk_accel_map_save_fd           (<link linkend="gint">gint</link> fd);</programlisting>
<para>
Filedescriptor variant of <link linkend="gtk-accel-map-save">gtk_accel_map_save</link>().
</para>
<para>
Note that the file descriptor will not be closed by this function.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>fd</parameter>&nbsp;:</entry>
<entry> a valid writable file descriptor
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-load-scanner">gtk_accel_map_load_scanner ()</title>
<programlisting>void        gtk_accel_map_load_scanner      (<link linkend="GScanner">GScanner</link> *scanner);</programlisting>
<para>
<link linkend="GScanner">GScanner</link> variant of <link linkend="gtk-accel-map-load">gtk_accel_map_load</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>scanner</parameter>&nbsp;:</entry>
<entry> a <link linkend="GScanner">GScanner</link> which has already been provided with an input file
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-add-filter">gtk_accel_map_add_filter ()</title>
<programlisting>void        gtk_accel_map_add_filter        (const <link linkend="gchar">gchar</link> *filter_pattern);</programlisting>
<para>
Adds a filter to the global list of accel path filters.
</para>
<para>
Accel map entries whose accel path matches one of the filters
are skipped by <link linkend="gtk-accel-map-foreach">gtk_accel_map_foreach</link>().
</para>
<para>
This function is intended for GTK+ modules that create their own
menus, but don't want them to be saved into the applications accelerator
map dump.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filter_pattern</parameter>&nbsp;:</entry>
<entry> a pattern (see <link linkend="GPatternSpec">GPatternSpec</link>)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-accel-map-foreach-unfiltered">gtk_accel_map_foreach_unfiltered ()</title>
<programlisting>void        gtk_accel_map_foreach_unfiltered
                                            (<link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link> foreach_func);</programlisting>
<para>
Loops over all entries in the accelerator map, and execute
<parameter>foreach_func</parameter> on each. The signature of <parameter>foreach_func</parameter> is that of
<link linkend="GtkAccelMapForeach">GtkAccelMapForeach</link>, the <parameter>changed</parameter> parameter indicates whether
this accelerator was changed during runtime (thus, would need
saving during an accelerator map dump).</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>         data to be passed into <parameter>foreach_func</parameter>
</entry></row>
<row><entry align="right"><parameter>foreach_func</parameter>&nbsp;:</entry>
<entry> function to be executed for each accel map entry
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
