path: root/docs/reference/pygtk-gtkaccelgroup.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-gtkaccelgroup">

  <refnamediv>
    <refname>gtk.AccelGroup</refname>
      <refpurpose>a group of accelerators for a Window hierarchy</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.AccelGroup</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkaccelgroup">gtk.AccelGroup</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--lock">lock</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--unlock">unlock</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--connect-group">connect</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_key</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">accel_mods</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">accel_flags</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">callback</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--connect-group">connect_group</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_key</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">accel_mods</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">accel_flags</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">callback</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--connect-by-path">connect_by_path</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_path</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">callback</parameter></methodparam>
      </methodsynopsis>
<!-- NOT IMPLEMENTED
<methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup- -disconnect">disconnect</link></methodname>
	<methodparam><parameter>closure</parameter></methodparam>
  </methodsynopsis>
END NOT IMPLEMENTED -->
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup--disconnect-key">disconnect_key</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_key</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">accel_mods</parameter></methodparam>
      </methodsynopsis>
<!-- NOT IMPLEMENTED
<methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccelgroup- -find">find</link></methodname>
	<methodparam><parameter>(*find_func</parameter></methodparam>
      </methodsynopsis>
END NOT IMPLEMENTED -->
    <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaccelgroup--get-is-locked">get_is_locked</link></methodname>
	<methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaccelgroup--get-modifier-mask">get_modifier_mask</link></methodname>
	<methodparam></methodparam>
    </methodsynopsis>

  </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-valid">gtk.accelerator_valid</link></methodname>
	<methodparam><parameter role="keyword">keyval</parameter></methodparam>
	<methodparam><parameter role="keyword">modifiers</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-parse">gtk.accelerator_parse</link></methodname>
	<methodparam><parameter role="keyword">accelerator</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-name">gtk.accelerator_name</link></methodname>
	<methodparam><parameter role="keyword">accelerator_key</parameter></methodparam>
	<methodparam><parameter role="keyword">accelerator_mods</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-set-default-mod-mask">gtk.accelerator_set_default_mod_mask</link></methodname>
	<methodparam><parameter role="keyword">default_mod_mask</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-get-default-mod-mask">gtk.accelerator_get_default_mod_mask</link></methodname>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--accelerator-get-label">gtk.accelerator_get_label</link></methodname>
	<methodparam><parameter role="keyword">accelerator_key</parameter></methodparam>
	<methodparam><parameter role="keyword">accelerator_mods</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-gtkaccelgroup">gtk.AccelGroup</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkaccelgroup">
    <title>gtk.AccelGroup Signal Prototypes</title>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkaccelgroup--accel-activate">accel-activate</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>accelgroup</parameter></methodparam>
	    <methodparam><parameter>acceleratable</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>
      <varlistentry>
        <term>"<link linkend="signal-gtkaccelgroup--accel-changed">accel-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>accelgroup</parameter></methodparam>
            <methodparam><parameter>accel_key</parameter></methodparam>
            <methodparam><parameter>accel_mods</parameter></methodparam>
            <methodparam><parameter>closure</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>
    <para>A <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
object groups all the accelerators for the associated window hierarchy
(either <link
linkend="class-gtkwindow"><classname>gtk.Window</classname></link> (or a
descendant) or <link
linkend="class-gtkmenushell"><classname>gtk.MenuShell</classname></link> (or
a descendant)). Once the <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
is associated with a window or menu (using <link
linkend="method-gtkwindow--add-accel-group"><methodname>gtk.Window.add_accel_group</methodname>()</link> 
or <link
linkend="method-gtkmenu--set-accel-group"><methodname>gtk.Menu.set_accel_group</methodname>()</link>), 
accelerators can be added to the widget or one of its children by using
<link
linkend="method-gtkwidget--add-accelerator"><methodname>gtk.Widget.add_accelerator</methodname>()</link> 
. Accelerators can also be added by using a <link
linkend="class-gtkaccelgroup"><classname>gtk.ItemFactory</classname></link>.</para>
    <para>Note that accelerators are different from mnemonics. Accelerators
are shortcuts for activating a menu item; they appear alongside the menu
item they're a shortcut for. For example
<keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>Q</keycap>
      </keycombo> might appear alongside the
<menuchoice><guimenu>Files</guimenu><guimenuitem>Quit</guimenuitem>
      </menuchoice> menu item. Mnemonics are shortcuts for GUI elements such
as text entries or buttons; they appear as underlined characters. Of course,
menu items can have both accelerators and mnemonics.</para>

    </refsect1>

  <refsect1 id="constructor-gtkaccelgroup">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.AccelGroup</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>an AccelGroup object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkaccelgroup--lock">
      <title>gtk.AccelGroup.lock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>lock</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>lock</methodname>() method locks the accelerator
group. preventing its accelerators from being changed during runtime. Refer
to <link
linkend="function-gtk--accel-map-change-entry"><function>gtk.accel_map_change_entry</function>()</link>
about runtime accelerator changes.</para>

      <para>If called more than once, the accelerator group remains locked
until <link
linkend="method-gtkaccelgroup--unlock"><methodname>gtk.AccelGroup.unlock</methodname>()</link> 
has been called an equivalent number of times.</para>

    </refsect2>

    <refsect2 id="method-gtkaccelgroup--unlock">
      <title>gtk.AccelGroup.unlock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>unlock</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>unlock</methodname>() method undoes the last
call to <link
linkend="method-gtkaccelgroup--lock"><methodname>gtk.AccelGroup.lock</methodname>()</link> 
for this accelerator group.</para>

    </refsect2>

    <refsect2 id="method-gtkaccelgroup--connect-group">
      <title>gtk.AccelGroup.connect_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_group</methodname>
	  <methodparam><parameter
		       role="keyword">accel_key</parameter></methodparam>
	  <methodparam><parameter
		       role="keyword">accel_mods</parameter></methodparam>
	  <methodparam><parameter
		       role="keyword">accel_flags</parameter></methodparam>
	  <methodparam><parameter
		       role="keyword">callback</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
		       role="keyword">accel_key</parameter>&nbsp;:</term>
	  <listitem><simpara>key value of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
		       role="keyword">accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>modifier combination of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
		       role="keyword">accel_flags</parameter>&nbsp;:</term>
	  <listitem><simpara>a flag mask to configure this
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
	  <listitem><simpara>a function or method to be executed upon
accelerator activation</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.2 as
	<parameter>connect</parameter>() and was changed in PyGTK 2.4 and
	above to <parameter>connect_group</parameter>() to avoid conflict
	with the <link
	linkend="method-gobject--connect"><methodname>gobject.GObject.connect</methodname>()</link>
	method.</para>
      </note>

      <para>The <methodname>connect_group</methodname>() method installs an
accelerator in the accelerator group. When the accelerator group is being
activated, the function (or method) specified by
<parameter>callback</parameter> will be invoked if the accelerator key and
modifier key match those specified by <parameter>accel_key</parameter> and
<parameter>accel_mods</parameter>.</para>

      <para>The value of <parameter>modifier</parameter> is a combination of
the <xref linkend="gdk-modifier-constants"
endterm="gdk-modifier-constants-title"></xref>. <parameter>accel_flags</parameter>
is a combination of <literal>gtk.ACCEL_VISIBLE</literal> and
<literal>gtk.ACCEL_LOCKED</literal>.</para>

      <para>The <parameter>callback</parameter> function is defined as:</para>

      <programlisting>
  def callback(accel_group, acceleratable, keyval, modifier)
</programlisting>

      <para>where <parameter>accel_group</parameter> is the accelerator
group, <parameter>acceleratable</parameter> is the object that the
<parameter>accel_group</parameter> is attached to (e.g. a <link
linkend="class-gtkwindow"><classname>gtk.Window</classname></link>),
<parameter>keyval</parameter> is the accelerator key and
<parameter>modifier</parameter> is the key
modifier. <parameter>callback</parameter> returns <literal>True</literal> if
the accelerator was handled by <parameter>callback</parameter>.</para>

      <note><para>Due to implementation details, a single function or method
can only be connected to one accelerator group.</para>
      </note>

  </refsect2>

    <refsect2 id="method-gtkaccelgroup--connect-by-path">
      <title>gtk.AccelGroup.connect_by_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_by_path</methodname>
	  <methodparam><parameter
		       role="keyword">accel_path</parameter></methodparam>
	  <methodparam><parameter
		       role="keyword">callback</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
		       role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>path used for determining key and
modifiers.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
		       role="keyword">callback</parameter>&nbsp;:</term>
	  <listitem><simpara>function or method to be executed upon accelerator
activation</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>connect_by_path</methodname>() method installs
an accelerator in the accelerator group, using an accelerator path to look
up the appropriate key and modifiers (see the function <link
linkend="function-gtk--accel-map-add-entry"><function>gtk.accel_map_add_entry</function>()</link>). When
the accelerator group is being activated, the function (or method) specified
by <parameter>callback</parameter> will be invoked if the
<parameter>accel_key</parameter> and <parameter>accel_mods</parameter> that
cause the activation match the key and modifiers for the accelerator path
specified by <parameter>accel_path</parameter>.</para>

      <para>The <parameter>callback</parameter> function is defined as:</para>

      <programlisting>
  def callback(accel_group, acceleratable, keyval, modifier)
</programlisting>

      <para>where <parameter>accel_group</parameter> is the accelerator
group, <parameter>acceleratable</parameter> is the object that the
<parameter>accel_group</parameter> is attached to (e.g. a <link
linkend="class-gtkwindow"><classname>gtk.Window</classname></link>),
<parameter>keyval</parameter> is the accelerator key and
<parameter>modifier</parameter> is the key
modifier. <parameter>callback</parameter> returns <literal>True</literal> if
the accelerator was handled by <parameter>callback</parameter>.</para>

    </refsect2>


<!-- NOT IMPLEMENTED

    <refsect2 id="method-gtkaccelgroup- -disconnect">
      <title>gtk.AccelGroup.disconnect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disconnect</methodname>
	  <methodparam><parameter>closure</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>closure</parameter>&nbsp;:</term>
	  <listitem><simpara>the closure to remove from this accelerator
group</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a gboolean</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>
Removes an accelerator previously installed through <link
linkend="method-gtkaccelgroup- -connect"><function>gtk.AccelGroup.connect()</function></link>.
</para>  </refsect2>

END NOT IMPLEMENTED -->

    <refsect2 id="method-gtkaccelgroup--disconnect-key">
      <title>gtk.AccelGroup.disconnect_key</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disconnect_key</methodname>
	  <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_key</parameter>&nbsp;:</term>
	  <listitem><simpara>key value of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>modifier combination of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if there was an
	  accelerator which was removed, <literal>False</literal>
	  otherwise</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>disconnect</methodname>() method removes a
previously installed accelerator specified by
<parameter>accel_key</parameter> and <parameter>accel_mods</parameter> from
the accelerator group.</para>

    </refsect2>

<!-- NOT IMPLEMENTED

    <refsect2 id="method-gtkaccelgroup- -find">
      <title>gtk.AccelGroup.find</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>find</methodname>
	  <methodparam><parameter>(*find_func</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>(*find_func</parameter>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a GtkAccelKey*</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>
Finds the first entry in an accelerator group for which
<parameter>find_func</parameter> returns <literal>True</literal> and returns
its <literal>GtkAccelKey</literal>.
</para>  </refsect2>

END NOT IMPLEMENTED -->

  <refsect2 id="method-gtkaccelgroup--get-is-locked">
      <title>gtk.AccelGroup.get_is_locked</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_is_locked</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if there are 1 or more locks
	  on the accel_group, <literal>False</literal> otherwise. </simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
	The <methodname>get_is_locked</methodname>() method returns the locked status.
	Locks are added and removed using
	<link linkend="method-gtkaccelgroup--lock">lock</link>() and
	<link linkend="method-gtkaccelgroup--lock">lock</link>().
      </para>

    </refsect2>
  
    <refsect2 id="method-gtkaccelgroup--get-modifier-mask">
      <title>gtk.AccelGroup.get_modifier_mask</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_modifier_mask</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the modifier mask for this accel group.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
	The <methodname>get_modifier_mask</methodname>() method gets a
	GdkModifierType representing the mask for this accel_group.
	For example, gtk.gdk.CONTROL_MASK, gtk.gdk.SHIFT_MASK, etc.
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--accelerator-valid">
      <title>gtk.accelerator_valid</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_valid</methodname>
	  <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">modifiers</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
	  <listitem><simpara>a key value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">modifiers</parameter>&nbsp;:</term>
	  <listitem><simpara>a modifier mask</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the accelerator is
valid</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accelerator_valid</function>() function
returns <literal>True</literal> if the specified
<parameter>keyval</parameter> and <parameter>modifiers</parameter>
constitute a valid keyboard accelerator. For example, the
<literal>ord('a')</literal> keyval plus
<literal>gtk.gdk.CONTROL_MASK</literal> is valid - this is a <keycombo
action="simul"><keycap>Control</keycap><keycap>a</keycap> </keycombo>
accelerator. The value of <parameter>modifiers</parameter> is a combination
of the <xref linkend="gdk-modifier-constants"
endterm="gdk-modifier-constants-title"></xref>.</para>

    </refsect2>

    <refsect2 id="function-gtk--accelerator-parse">
      <title>gtk.accelerator_parse</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_parse</methodname>
	  <methodparam><parameter
			 role="keyword">accelerator</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accelerator</parameter>&nbsp;:</term>
	  <listitem><simpara>a string representing an
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the keyval and modifier
mask of the accelerator</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accelerator_parse</function>() function parses
the specified <parameter>accelerator</parameter> string and returns a
2-tuple containing the keyval and modifier mask corresponding to
<parameter>accelerator</parameter>. The format looks like "&lt;Control&gt;a" or
"&lt;Shift&gt;&lt;Alt&gt;F1" or "&lt;Release&gt;z" (the last one is for key release). The
parser is fairly liberal and allows lower or upper case, and also
abbreviations such as "&lt;Ctl&gt;" and "&lt;Ctrl&gt;". If the parse fails, the tuple
values will both be 0 (zero). See the <link
linkend="function-gtk--accelerator-valid"><function>gtk.accelerator_valid</function>()</link> 
function for more details.</para>

    </refsect2>

    <refsect2 id="function-gtk--accelerator-name">
      <title>gtk.accelerator_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_name</methodname>
	  <methodparam><parameter
			 role="keyword"></parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accelerator_key</parameter>&nbsp;:</term>
	  <listitem><simpara>a key value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">accelerator_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>a modifier mask</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string representing the accelerator or
<literal>None</literal> if not a valid accelerator</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accelerator_name</function>() function
converts the accelerator keyval and modifier mask (specified by
<parameter>accelerator_key</parameter> and
<parameter>accelerator_mods</parameter>) into a string parseable by the
<link
linkend="function-gtk--accelerator-parse"><function>gtk.accelerator_parse</function>()</link> 
function. For example, if you pass in <literal>ord('q')</literal> and
<literal>gtk.gdk.CONTROL_MASK</literal>, this function returns
"&lt;Control&gt;q".</para>

    </refsect2>

    <refsect2 id="function-gtk--accelerator-set-default-mod-mask">
      <title>gtk.accelerator_set_default_mod_mask</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_set_default_mod_mask</methodname>
	  <methodparam><parameter
			 role="keyword">default_mod_mask</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">default_mod_mask</parameter>&nbsp;:</term>
	  <listitem><simpara>the new default accelerator modifier
mask</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accelerator_set_default_mod_mask</function>()
function sets the modifiers (specified by
<parameter>default_mod_mask</parameter>) that will be considered significant
for keyboard accelerators. The default mod mask is
<literal>gtk.gdk.CONTROL_MASK</literal> |
<literal>gtk.gdk.SHIFT_MASK</literal> |
<literal>gtk.gdk.MOD1_MASK</literal>, that is, <keycap>Control</keycap>,
<keycap>Shift</keycap>, and <keycap>Alt</keycap>. Other modifiers will by
default be ignored by <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>.
You must include at least the three default modifiers in any value you pass
to this function. The default mod mask should be changed on application
startup, before using any accelerator groups. The value of
<parameter>default_mod_mask</parameter> is a combination of the <xref
linkend="gdk-modifier-constants"
endterm="gdk-modifier-constants-title"></xref>.</para>

   </refsect2>

    <refsect2 id="function-gtk--accelerator-get-default-mod-mask">
      <title>gtk.accelerator_get_default_mod_mask</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_get_default_mod_mask</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the default accelerator modifier
mask</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.accelerator_get_default_mod_mask</function>()
function returns the default accelerator modifier mask as set by the <link
linkend="function-gtk--accelerator-set-default-mod-mask"><function>gtk.accelerator_set_default_mod_mask</function>()</link> 
function. See the <link
linkend="function-gtk--accelerator-set-default-mod-mask"><function>gtk.accelerator_set_default_mod_mask</function>()</link> 
function for more detail on modifier masks.</para>

    </refsect2>

    <refsect2 id="function-gtk--accelerator-get-label">
      <title>gtk.accelerator_get_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accelerator_get_label</methodname>
	  <methodparam><parameter
			 role="keyword">accelerator_key</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">accelerator_mods</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">accelerator_key</parameter>&nbsp;:</term>
	  <listitem><simpara>a key value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">accelerator_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>a modifier mask</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string representing the
accelerator</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.accelerator_get_label</function>() function
converts the accelerator keyval and modifier mask specified by
<parameter>accelerator_key</parameter> and
<parameter>accelerator_mods</parameter> respectively into a string which can
be used to represent the accelerator to the user. The value of
<parameter>accelerator_mods</parameter> is a combination of the <xref
linkend="gdk-modifier-constants"
endterm="gdk-modifier-constants-title"></xref>.</para>

    </refsect2>

     <refsect2 id="function-gtk--accel-groups-from-object">
      <title>gtk.accel_groups_from_object</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.accel_groups_from_object</methodname>
	  <methodparam><parameter>object</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>object</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject usually a <link
	  linkend="class-gtkwindow"><classname>gtk.Window</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.accel_groups_from_object</function>() function
returns a list of all the <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
objects attached to the object specified by
<parameter>object</parameter>.</para>

    </refsect2>

 </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkaccelgroup--accel-activate">
      <title>The "accel-activate" gtk.AccelGroup Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>accelgroup</parameter></methodparam>
	  <methodparam><parameter>acceleratable</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>accelgroup</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelgroup that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>acceleratable</parameter>&nbsp;:</term>
	  <listitem><simpara>the object that the accelerator is associated
with</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>accel_key</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelerator key value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelerator modifiers</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>gobject.GObject.connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the accelerator
was handled</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "accel-activate" signal is emitted when an accelerator is
activated.</para>

    </refsect2>

    <refsect2 id="signal-gtkaccelgroup--accel-changed">
      <title>The "accel-changed" gtk.AccelGroup Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>accelgroup</parameter>&nbsp;:</term>
	  <listitem><simpara>the accelgroup that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>accel_key</parameter>&nbsp;:</term>
	  <listitem><simpara>the key value of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>accel_mods</parameter>&nbsp;:</term>
	  <listitem><simpara>the modifiers of the
accelerator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>closure</parameter>&nbsp;:</term>
	  <listitem><simpara>the closure of the
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>

      <para>The "accel-changed" signal is emitted when an accelerator is
added or removed from an accelerator group.</para>

    </refsect2>

  </refsect1>

</refentry>