path: root/docs/reference/pygtk-gtkaccelmap.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkaccelmap">

  <refnamediv>
    <refname>gtk.AccelMap</refname>
      <refpurpose>Loadable keyboard accelerator specifications (new in PyGTK
      2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.AccelMap</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
</classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>
<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-add-entry">gtk.accel_map_add_entry</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
	<methodparam><parameter role="keyword">accel_key</parameter></methodparam>
	<methodparam><parameter role="keyword">accel_mods</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-lookup-entry">gtk.accel_map_lookup_entry</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-change-entry">gtk.accel_map_change_entry</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
	<methodparam><parameter role="keyword">accel_key</parameter></methodparam>
	<methodparam><parameter role="keyword">accel_mods</parameter></methodparam>
	<methodparam><parameter role="keyword">replace</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
      <methodname><link linkend="function-gtk--accel-map-foreach">gtk.accel_map_foreach</link></methodname>
      <methodparam><parameter role="keyword">foreach_func</parameter></methodparam>
      <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis><methodsynopsis language="python">
      <methodname><link linkend="function-gtk--accel-map-foreach-unfiltered">gtk.accel_map_foreach_unfiltered</link></methodname>
      <methodparam><parameter role="keyword">foreach_func</parameter></methodparam>
      <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis><methodsynopsis language="python">
      <methodname><link linkend="function-gtk--accel-map-get">gtk.accel_map_get</link></methodname>
      <methodparam></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-load">gtk.accel_map_load</link></methodname>
	<methodparam><parameter role="keyword">file_name</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-save">gtk.accel_map_save</link></methodname>
	<methodparam><parameter role="keyword">file_name</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-load-fd">gtk.accel_map_load_fd</link></methodname>
	<methodparam><parameter role="keyword">fd</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-save-fd">gtk.accel_map_save_fd</link></methodname>
	<methodparam><parameter role="keyword">fd</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-lock-path">gtk.accel_map_lock_path</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-unlock-path">gtk.accel_map_unlock_path</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-map-add-filter">gtk.accel_map_add_filter</link></methodname>
	<methodparam><parameter role="keyword">filter_pattern</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accel-groups-from-object">gtk.accel_groups_from_object</link></methodname>
	<methodparam><parameter>object</parameter></methodparam>
      </methodsynopsis>
</programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkaccelmap">gtk.AccelMap</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkaccelmap">
    <title>gtk.AccelMap Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>

      <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkaccelmap--changed">changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>object</parameter></methodparam>
            <methodparam><parameter>accel_path</parameter></methodparam>
            <methodparam><parameter>accel_key</parameter></methodparam>
            <methodparam><parameter>accel_mods</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

<para></para>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--accel-map-add-entry">
      <title>gtk.accel_map_add_entry</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_add_entry</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">accel_key</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">accel_mods</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accel_key</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelerator key</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelerator modifiers</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.accel_map_add_entry</function>() function
registers a new accelerator specified by <parameter>accel_key</parameter>
and <parameter>accel_mods</parameter> with the global accelerator map. The
accelerator will be associated with the accelerator path specified by
<parameter>accel_path</parameter>. 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 the
<link
linkend="function-gtk--accel-map-change-entry"><function>gtk.accel_map_change_entry</function>()</link>
function. 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>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-lookup-entry">
      <title>gtk.accel_map_lookup_entry</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_lookup_entry</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the keyval and modifier
mask corresponding to <parameter>accel_path</parameter> or
<literal>None</literal> if not valid</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_lookup_entry</function>() function
returns a 2-tuple containing the keyval and modifier mask corresponding to
the accelerator path specified by <parameter>accel_path</parameter> or
<literal>None</literal> if <parameter>accel_path</parameter> is not a valid
accelerator path.</para>

      <para>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>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-change-entry">
      <title>gtk.accel_map_change_entry</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_change_entry</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">accel_key</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">accel_mods</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">replace</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accel_key</parameter>&nbsp;:</term>
	  <listitem><simpara> the new accelerator key</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara> the new accelerator
modifiers</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">replace</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> other accelerators
may be deleted if conflicting</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the accelerator
could be changed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_change_entry</function>() function
changes the keyval and modifier mask currently associated with the
accelerator path specified by <parameter>accel_path</parameter> to the
values specified by <parameter>accel_key</parameter> and
<parameter>accel_mods</parameter> respectively. Due to conflicts with other
accelerators, a change may not always be possible. If
<parameter>replace</parameter> is <literal>True</literal> the 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>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-foreach">
      <title>gtk.accel_map_foreach</title>

      <programlisting><methodsynopsis language="python">
      <methodname>gtk.accel_map_foreach</methodname>
      <methodparam><parameter role="keyword">foreach_func</parameter></methodparam>
      <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">foreach_func</parameter>&nbsp;:</term>
          <listitem><simpara>function to be executed for each accel map
          entry which is not filtered out</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">data</parameter>&nbsp;:</term>
          <listitem><simpara>data to be passed into
          <parameter>foreach_func</parameter></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Loops over the entries in the accelerator map whose accel path
      doesn't match any of the filters added with the <link
      linkend="function-gtk--accel-map-add-filter"><function>gtk.accel_map_add_filter</function>()</link>
      function, and executes <parameter>foreach_func</parameter> on
      each. The signature of <parameter>foreach_func</parameter> is:</para>

      <programlisting>
  def foreach_func(accel_path, accel_key, accel_mode, changed, user_data):
      </programlisting>

      <para>where <parameter>accel_path</parameter>,
      <parameter>accel_key</parameter> and <parameter>accel_mode</parameter>
      describe the accel map accelerator entry and the
      <parameter>changed</parameter> parameter indicates whether this
      accelerator was changed during runtime ( and thus, would need saving
      during an accelerator map dump). <parameter>user_data</parameter> is
      <parameter>data</parameter> if <parameter>data</parameter> was
      specified. See the <link
      linkend="function-gtk--accel-map-add-entry"><function>gtk.accel_map_add_entry</function>()</link>
      function for more information.</para>
    </refsect2>

    <refsect2 id="function-gtk--accel-map-foreach-unfiltered">
      <title>gtk.accel_map_foreach_unfiltered</title>

      <programlisting><methodsynopsis language="python">
      <methodname>gtk.accel_map_foreach_unfiltered</methodname>
      <methodparam><parameter role="keyword">foreach_func</parameter></methodparam>
      <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">foreach_func</parameter>&nbsp;:</term>
          <listitem><simpara>function to be executed for each accel map
          entry</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">data</parameter>&nbsp;:</term>
          <listitem><simpara>data to be passed into
          <parameter>foreach_func</parameter></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Loops over all entries in the accelerator map, and executes
      <parameter>foreach_func</parameter> on each. The signature of
      <parameter>foreach_func</parameter> is:</para>

      <programlisting>
  def foreach_func(accel_path, accel_key, accel_mode, changed, user_data):
      </programlisting>

      <para>where <parameter>accel_path</parameter>,
      <parameter>accel_key</parameter> and <parameter>accel_mode</parameter>
      describe the accel map accelerator entry and the
      <parameter>changed</parameter> parameter indicates whether this
      accelerator was changed during runtime (thus, would need saving during
      an accelerator map dump).  <parameter>user_data</parameter> is
      <parameter>data</parameter> if <parameter>data</parameter> was
      specified. See the <link
      linkend="function-gtk--accel-map-add-entry"><function>gtk.accel_map_add_entry</function>()</link>
      function for more information.</para>
    </refsect2>

    <refsect2 id="function-gtk--accel-map-get">
      <title>gtk.accel_map_get</title>

      <programlisting><methodsynopsis language="python">
      <methodname>gtk.accel_map_get</methodname>
      <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the global <link
          linkend="class-gtkaccelmap"><classname>gtk.AccelMap</classname></link>
          object</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Gets the singleton global <link
      linkend="class-gtkaccelmap"><classname>gtk.AccelMap</classname></link>
      object. This object is useful only for notification of changes to the
      accelerator map via the "changed" signal. it has no methods or
      properties.</para>
    </refsect2>

    <refsect2 id="function-gtk--accel-map-load">
      <title>gtk.accel_map_load</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_load</methodname>
	  <methodparam><parameter
			 role="keyword">file_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">file_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the file containing accelerator
specifications</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_load</function>() function parses
the file (specified by <parameter>file_name</parameter>) previously saved
with the <link
linkend="function-gtk--accel-map-save"><function>gtk.accel_map_save</function>()</link> 
function for accelerator specifications, and propagates them
accordingly.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-save">
      <title>gtk.accel_map_save</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_save</methodname>
	  <methodparam><parameter
			 role="keyword">file_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">file_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the file to save the accelerator specifications
in</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_save</function>() function saves
current accelerator specifications (accelerator path, key and modifiers) to
the file specified by <parameter>file_name</parameter>. The file is written
in a format suitable to be read back in by the <link
linkend="function-gtk--accel-map-load"><function>gtk.accel_map_load</function>()</link> 
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-load-fd">
      <title>gtk.accel_map_load_fd</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_load_fd</methodname>
	  <methodparam><parameter
			 role="keyword">fd</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">fd</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python file object or an integer file
descriptor</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_load_fd</function>() function loads
the accelerator map from the open Python file object specified by
<parameter>fd</parameter>. <parameter>fd</parameter> may also be an integer
file descriptor. See the <link
linkend="function-gtk--accel-map-load"><function>gtk.accel_map_load</function>()</link> 
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-save-fd">
      <title>gtk.accel_map_save_fd</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_save_fd</methodname>
	  <methodparam><parameter
			 role="keyword">fd</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">fd</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python file object or an integer file
descriptor</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_save_fd</function>() function saves
the accelerator map into the open Python file object specified by fd.
<parameter>fd</parameter> may also be an integer file descriptor. See the
<link
linkend="function-gtk--accel-map-save"><function>gtk.accel_map_save</function>()</link> 
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-lock-path">
      <title>gtk.accel_map_lock_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_lock_path</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.accel_map_lock_path</function>() function
      locks the accelerator path specified by
      <parameter>accel_path</parameter>. If the accelerator map doesn't yet
      contain an entry for <parameter>accel_path</parameter>, a new one is
      created.</para>

      <para>Locking an accelerator path prevents its accelerator from being
      changed during runtime. A locked accelerator path can be unlocked by
      the <link
      linkend="function-gtk--accel-map-unlock-path"><function>gtk.accel_map_unlock_path</function>()</link>
      function. Refer to the <link
      linkend="function-gtk--accel-map-change-entry"><function>gtk.accel_map_change_entry</function>()</link>
      function for information about runtime accelerator changes.</para>

      <para>If called more than once, <parameter>accel_path</parameter>
      remains locked until the <link
      linkend="function-gtk--accel-map-unlock-path"><function>gtk.accel_map_unlock_path</function>()</link>
      function has been called an equivalent number of times.</para>

      <para>Note that locking of individual accelerator paths is independent
      from locking the <link
      linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
      containing them. For runtime accelerator changes to be possible both
      the accelerator path and its <link
      linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
      have to be unlocked.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-unlock-path">
      <title>gtk.accel_map_unlock_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_unlock_path</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.accel_map_unlock_path</function>() function
      undoes the last call to the <link
      linkend="function-gtk--accel-map-lock-path"><function>gtk.accel_map_lock_path</function>()</link>
      function on the accelerator path specified by
      <parameter>accel_path</parameter>. Refer to the <link
      linkend="function-gtk--accel-map-lock-path"><function>gtk.accel_map_lock_path</function>()</link>
      function for information about accelerator path locking.</para>

    </refsect2>

    <refsect2 id="function-gtk--accel-map-add-filter">
      <title>gtk.accel_map_add_filter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_map_add_filter</methodname>
	  <methodparam><parameter
			 role="keyword">filter_pattern</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">filter_pattern</parameter>&nbsp;:</term>
	  <listitem><simpara>a glob-style pattern</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accel_map_add_filter</function>() function
      adds the filter pattern specified by
      <parameter>filter_pattern</parameter> to the global list of accel path
      filters. The pattern specified by
      <parameter>filter_pattern</parameter> contain '*' and '?' wildcards
      with similar semantics as the Python <filename>glob.py</filename> and
      <filename>fnmatch.py</filename> modules: '*' matches an arbitrary,
      possibly empty, string, '?' matches an arbitrary character. Note that
      in contrast to <filename>glob.py</filename>, the '/' character can be
      matched by the wildcards, there are no '[...]' character ranges and
      '*' and '?' can not be escaped to include them literally in a
      pattern. Accelerator map entries whose accelerator path matches one of
      the filters are skipped by the <link
      linkend="function-gtk--accel-map-foreach"><function>gtk.accel_map_foreach</function>()</link>
      function.  This function is intended for <literal>PyGTK</literal>
      modules that create their own menus, but don't want them to be saved
      into the applications accelerator map dump.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkaccelmap--changed">
      <title>The "changed" gtk.AccelMap Signal</title>

      <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>object</parameter></methodparam>
            <methodparam><parameter>accel_path</parameter></methodparam>
            <methodparam><parameter>accel_key</parameter></methodparam>
            <methodparam><parameter>accel_mods</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>object</parameter>&nbsp;:</term>
          <listitem><simpara>the global accel map object</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>accel_path</parameter>&nbsp;:</term>
          <listitem><simpara>the path of the accelerator that
          changed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>accel_key</parameter>&nbsp;:</term>
          <listitem><simpara>the key value for the new
          accelerator</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>accel_mods</parameter>&nbsp;:</term>
          <listitem><simpara>the modifier mask for the new
          accelerator</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if
          any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This signal is available in GTK+ 2.4 and above.</para>
      </note>

      <para>Notifies of a change in the global accelerator map.  The path is
      also used as the detail for the signal, so it is possible to connect
      to changed::<replaceable>accel_path</replaceable>.</para>

    </refsect2>

</refsect1>

</refentry>