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

  <refnamediv>
    <refname>gtk.AccelLabel</refname>
      <refpurpose>a label which displays accelerator info to the right of the text</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
      <ooclass><classname>gtk.AccelLabel</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtklabel">gtk.Label</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkaccellabel">gtk.AccelLabel</link></methodname>
	<methodparam><parameter
		       role="keyword">string</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccellabel--accelerator-width">accelerator_width</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccellabel--get-accel-widget">get_accel_widget</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccellabel--get-accel-width">get_accel_width</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccellabel--set-accel-widget">set_accel_widget</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_widget</parameter></methodparam>
      </methodsynopsis>
<!-- NOT IMPLEMENTED
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkaccellabel- -set-accel-closure">set_accel_closure</link></methodname>
    <methodparam><parameter>accel_closure</parameter></methodparam>
  </methodsynopsis>
END NOT IMPLEMENTED -->
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkaccellabel--refetch">refetch</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>
  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkmisc">gtk.Misc</link>
        +-- <link linkend="class-gtklabel">gtk.Label</link>
          +-- <link linkend="class-gtkaccellabel">gtk.AccelLabel</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkaccellabel">
    <title>gtk.AccelLabel Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkmisc">gtk.Misc Properties</link></para>
    <para><link linkend="properties-gtklabel">gtk.Label Properties</link></para>
    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"accel-closure"</entry>
	      <entry>Read-Write</entry>
	      <entry>The closure to be monitored for accelerator
changes</entry>
	    </row>
	    <row valign="top">
	      <entry>"accel-widget"</entry>
	      <entry>Read-Write</entry>
	      <entry>The widget associated with the accelerator
label</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkaccellabel">
    <title>gtk.AccelLabel Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>


  </refsect1>

  <refsect1 id="signal-prototypes-gtkaccellabel">
    <title>gtk.AccelLabel Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtklabel">gtk.Label Signal Prototypes</link></para>
</refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
widget is a subclass of <link
linkend="class-gtklabel"><classname>gtk.Label</classname></link> that
displays an accelerator string to the right of the label text, e.g.
<keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>S</keycap>
      </keycombo>. It is commonly used in menus to show the keyboard
shortcuts for commands. The accelerator string to display is not set
explicitly; instead, the <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
displays the accelerators which have been added to the associated widget. A
widget is associated with the accelerator label by calling <link
linkend="method-gtkaccellabel--set-accel-widget"><methodname>set_accel_widget</methodname>()</link>.</para>

    <para>For example, a <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
widget may have an accelerator added to emit the "activate" signal when the
<keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>S</keycap>
      </keycombo> key combination is pressed. A <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
is created and added to the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>, and
<link
linkend="method-gtkaccellabel--set-accel-widget"><methodname>set_accel_widget</methodname>()</link> is called with the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> as
the first argument. The <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
will now display <keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>S</keycap>
      </keycombo> after its label.</para>

    <para>Creating a <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> with
the <link
linkend="constructor-gtkmenuitem"><function>gtk.MenuItem</function>()</link>
function (or one of the similar functions <link
linkend="constructor-gtkcheckmenuitem"><function>gtk.CheckMenuItem</function>()</link> 
and <link
linkend="constructor-gtkradiomenuitem"><function>gtk.RadioMenuItem</function>()</link>) 
and specifying a label, automatically adds a <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
to the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> and
calls <link
linkend="method-gtkaccellabel--set-accel-widget"><methodname>set_accel_widget</methodname>()</link> 
to set it up for you.</para>

    <para>A <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
will only display accelerators which have
<literal>gtk.ACCEL_VISIBLE</literal> set. A <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
can display multiple accelerators and even signal names, though it is almost
always used to display just one accelerator.</para>

    <para>The following code fragment creates a simple menu item with an
accelerator and enables the display of the accelerator key string in the
menu item label:</para>

<example>
<title>Creating a simple menu item with an accelerator key.</title>
<programlisting>
    # Create an accelgroup and add it to the window
    accel_group = gtk.AccelGroup()
    window.add_accel_group(accel_group)

    # Create the menu item
    save_item = gtk.MenuItem("Save")
    save_item.show()
    menu.add(save_item)

    # Now add the accelerator to the menu item. Note that since we created
    # the menu item with a label the AccelLabel is automatically setup to 
    # display the accelerators.
    save_item.add_accelerator("activate", accel_group, ord("S"),
                              gtk.gdk.CONTROL_MASK, gtk.ACCEL_VISIBLE)
</programlisting>
</example>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.AccelLabel</methodname>
	<methodparam><parameter
		       role="keyword">string</parameter></methodparam>
      </constructorsynopsis></programlisting>

    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">string</parameter>&nbsp;:</term>
	<listitem><simpara>the label string</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <classname>gtk.AccelLabel</classname>
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para><function>gtk.AccelLabel</function>() creates a new <link
linkend="class-gtkaccellabel"><classname>gtk.AccelLabel</classname></link>
object. The <parameter>string</parameter> parameter specifies the text to be
displayed by the label. The accelerator text is automatically added by the
associated widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkaccellabel--accelerator-width">
      <title>gtk.AccelLabel.accelerator_width</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>accelerator_width</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the width in pixels needed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>accelerator_width</methodname>() method returns
the width in pixels needed to display the accelerator(s). It is used by
menus to align all of the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
widgets, and isn't usually needed by applications.</para>
      <note><para><methodname>accelerator_width</methodname>() is deprecated
- use the <link
linkend="method-gtkaccellabel--get-accel-width"><methodname>get_accel_width</methodname>()</link> 
method instead.</para>
      </note>

    </refsect2>

    <refsect2 id="method-gtkaccellabel--get-accel-widget">
      <title>gtk.AccelLabel.get_accel_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_accel_widget</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the widget associated with the accelerator
label, or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_accel_widget</methodname>() method retrieves
the widget associated with this accelerator label. See <link
linkend="method-gtkaccellabel--set-accel-widget"><function>gtk.AccelLabel.set_accel_widget()</function></link>.
</para>

    </refsect2>

    <refsect2 id="method-gtkaccellabel--get-accel-width">
      <title>gtk.AccelLabel.get_accel_width</title>

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

      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the width in pixels needed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_accel_width</methodname>() method returns
the width in pixels needed to display the accelerator(s). It is used by
menus to align all of the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
widgets, and isn't usually needed by applications.</para>

    </refsect2>

    <refsect2 id="method-gtkaccellabel--set-accel-widget">
      <title>gtk.AccelLabel.set_accel_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_accel_widget</methodname>
	  <methodparam><parameter
			 role="keyword">accel_widget</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget to be
associated.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_accel_widget</methodname>() method
associates the accelerator label with the widget specified by
<parameter>accel_widget</parameter>.</para>

    </refsect2>

<!-- NOT IMPLEMENTED

  <refsect2 id="method-gtkaccellabel- -set-accel-closure">
    <title>gtk.AccelLabel.set_accel_closure</title>

<programlisting><methodsynopsis language="python">
    <methodname>set_accel_closure</methodname>
    <methodparam><parameter role="keyword">accel_closure</parameter></methodparam>
  </methodsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><parameter role="keyword">accel_closure</parameter>&nbsp;:</term>
      <listitem><simpara>the closure to monitor for accelerator changes.</simpara></listitem>
    </varlistentry>
  </variablelist>
<para>
Sets the closure to be monitored by this accelerator label. The closure
must be connected to an accelerator group; see <link linkend="method-gtkaccelgroup- -connect"><function>gtk.AccelGroup.connect()</function></link>.
</para>  </refsect2>

END NOT IMPLEMENTED -->

    <refsect2 id="method-gtkaccellabel--refetch">
      <title>gtk.AccelLabel.refetch</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>refetch</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>False</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>refetch</methodname>() method recreates the
accelerator label string holding the accelerator information when the
accelerator is changed. The size of the string is also recalculated.</para>

      <para>This method is not usually needed by applications since the
accelerator label string is automatically updated whenever accelerators are
added or removed from the associated widget.</para>

    </refsect2>

  </refsect1>

</refentry>