path: root/docs/reference/pygtk-gtkhandlebox.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-gtkhandlebox">
  <refnamediv>
    <refname>gtk.HandleBox</refname>
    <refpurpose>a widget for detachable window portions.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.HandleBox</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkbin">gtk.Bin</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkhandlebox">gtk.HandleBox</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--set-shadow-type">set_shadow_type</link></methodname>
	<methodparam><parameter
		       role="keyword">type</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--get-shadow-type">get_shadow_type</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--set-handle-position">set_handle_position</link></methodname>
	<methodparam><parameter
		       role="keyword">position</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--get-handle-position">get_handle_position</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--set-snap-edge">set_snap_edge</link></methodname>
	<methodparam><parameter
		       role="keyword">edge</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkhandlebox--get-snap-edge">get_snap_edge</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkhandlebox--get-child-detached">get_child_detached</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-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkhandlebox">gtk.HandleBox</link>
</synopsis>

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


  <refsect1 id="properties-gtkhandlebox">
    <title>gtk.HandleBox 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-gtkcontainer">gtk.Container 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>"child-detached"</entry>
	      <entry>Read</entry>
	      <entry><literal>True</literal> if the handlebox's child is detached, <literal>False</literal> otherwise.</entry>
	    </row>

	    <row valign="top">
	      <entry>"handle-position"</entry>
	      <entry>Read-Write</entry>
	      <entry>The position of the handle relative to the child
	      widget; one of the <xref linkend="gtk-position-type-constants"
	      endterm="gtk-position-type-constants-title"></xref>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"shadow-type"</entry>
	      <entry>Read-Write</entry>
	      <entry>The type of shadow; one of the <xref
	      linkend="gtk-shadow-type-constants"
	      endterm="gtk-shadow-type-constants-title"></xref>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"snap-edge"</entry>
	      <entry>Read-Write</entry>
	      <entry>The side of the handlebox that's lined up with the
	      docking point to dock the handlebox; one of the <xref
	      linkend="gtk-position-type-constants"
	      endterm="gtk-position-type-constants-title"></xref>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"snap-edge-set"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, use the value from
	      "snap-edge"; otherwise, use a value derived from
	      "handle-position".  Available in GTK+ 2.2 and above.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkhandlebox">
    <title>gtk.HandleBox Style Properties</title>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkhandlebox">
    <title>gtk.HandleBox 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-gtkcontainer">gtk.Container Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkhandlebox--child-attached">child-attached</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>handlebox</parameter>
            </methodparam>
            <methodparam><parameter>widget</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkhandlebox--child-detached">child-detached</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>handlebox</parameter>
            </methodparam>
            <methodparam><parameter>widget</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkhandlebox"><classname>gtk.HandleBox</classname></link>
widget allows a portion of a window to be "torn off". It is a bin widget
which displays its child and a handle that the user can drag to tear off
into a separate floating window containing the child widget. A thin ghost is
drawn in the original location of the handlebox. The separate window can be
dragged back to its original location to be reattached. When reattaching,
the ghost and float window, must be aligned along one of the edges called
the snap edge that can be specified by the application, or specified
automatically using a reasonable default based on the handle position. The
snap edge is automatically set as <literal>gtk.POS_TOP</literal> if the
handle position is <literal>gtk.POS_RIGHT</literal> or
<literal>gtk.POS_LEFT</literal>; otherwise, the snap edge will be set as
<literal>gtk.POS_LEFT</literal>.</para>

    <para>To make detaching and reattaching the handlebox as minimally
confusing as possible to the user, it is important to set the snap edge so
that the snap edge does not move when the handlebox is detached. For
example, if the handlebox is packed at the bottom of a <link
linkend="class-gtkvbox"><classname>gtk.VBox</classname></link>, then when
the handlebox is detached, the bottom edge of the handlebox's allocation
will remain fixed as the height of the handlebox shrinks, so the snap edge
should be set to <literal>gtk.POS_BOTTOM</literal>.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.HandleBox</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new handlebox widget</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkhandlebox"><classname>gtk.HandleBox</classname></link>
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkhandlebox--set-shadow-type">
      <title>gtk.HandleBox.set_shadow_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_shadow_type</methodname>
	  <methodparam><parameter
			 role="keyword">type</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>the shadow type:
<literal>gtk.SHADOW_NONE</literal>, <literal>gtk.SHADOW_IN</literal>,
<literal>gtk.SHADOW_OUT</literal>, <literal>gtk.SHADOW_ETCHED_IN</literal>,
<literal>gtk.SHADOW_ETCHED_OUT</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_shadow_type</methodname>() method sets the
type of shadow to be drawn around the border of the handle box as specified
by <parameter>type</parameter>. The value of <parameter>type</parameter>
must be one of: <literal>gtk.SHADOW_NONE</literal>,
<literal>gtk.SHADOW_IN</literal>, <literal>gtk.SHADOW_OUT</literal>,
<literal>gtk.SHADOW_ETCHED_IN</literal>,
<literal>gtk.SHADOW_ETCHED_OUT</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--get-shadow-type">
      <title>gtk.HandleBox.get_shadow_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_shadow_type</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the type of shadow currently drawn around the
handle box.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_shadow_type</methodname>() method gets the
type of shadow drawn around the handle box. The shadow type is one of:
<literal>gtk.SHADOW_NONE</literal>, <literal>gtk.SHADOW_IN</literal>,
<literal>gtk.SHADOW_OUT</literal>, <literal>gtk.SHADOW_ETCHED_IN</literal>,
<literal>gtk.SHADOW_ETCHED_OUT</literal>. See <link
linkend="method-gtkhandlebox--set-shadow-type"><methodname>set_shadow_type</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--set-handle-position">
      <title>gtk.HandleBox.set_handle_position</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_handle_position</methodname>
	  <methodparam><parameter
			 role="keyword">position</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">position</parameter>&nbsp;:</term>
	  <listitem><simpara>the side of the handlebox where the handle
should be drawn.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_handle_position</methodname>() method sets
the side of the handlebox where the handle is drawn using the value of
<parameter>position</parameter>. The value of
<parameter>position</parameter> must be one of:
<literal>gtk.POS_LEFT</literal>, <literal>gtk.POS_RIGHT</literal>,
<literal>gtk.POS_TOP</literal>, <literal>gtk.POS_BOTTOM</literal></para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--get-handle-position">
      <title>gtk.HandleBox.get_handle_position</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_handle_position</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current handle
position.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_handle_position</methodname>() method gets
the handle position of the handle box; one of:
<literal>gtk.POS_LEFT</literal>, <literal>gtk.POS_RIGHT</literal>,
<literal>gtk.POS_TOP</literal>, <literal>gtk.POS_BOTTOM</literal>. See <link
linkend="method-gtkhandlebox--set-handle-position"><methodname>set_handle_position</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--set-snap-edge">
      <title>gtk.HandleBox.set_snap_edge</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_snap_edge</methodname>
	  <methodparam><parameter
			 role="keyword">edge</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">edge</parameter>&nbsp;:</term>
	  <listitem><simpara>the edge to use as the snap edge or -1 to have
PyGTK automatically pick the snap edge</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_snap_edge</methodname>() method sets the
snap edge of the handlebox to the value specified by
<parameter>edge</parameter>. The value of <parameter>edge</parameter> can be
one of: <literal>gtk.POS_LEFT</literal>, <literal>gtk.POS_RIGHT</literal>,
<literal>gtk.POS_TOP</literal>, <literal>gtk.POS_BOTTOM</literal> or -1 to
have the snap edge automatically specified.</para>

      <para>The snap edge is the edge of the detached child that must be
aligned with the corresponding edge of the "ghost" left behind when the
child was detached to reattach the torn-off window. Usually, the snap edge
should be chosen so that it stays in the same place on the screen when the
handlebox is torn off. If the snap edge is not set, then an appropriate
value will be guessed from the handle position. If the handle position is
<literal>gtk.POS_RIGHT</literal> or <literal>gtk.POS_LEFT</literal>, then
the snap edge will be <literal>gtk.POS_TOP</literal>, otherwise it will be
<literal>gtk.POS_LEFT</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--get-snap-edge">
      <title>gtk.HandleBox.get_snap_edge</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_snap_edge</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the edge used for determining reattachment, or
-1 if the snap edge is determined (as per default) from the handle
position.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_snap_edge</methodname>() method gets the
edge used for determining reattachment of the handle box. The return value
will be one of: <literal>gtk.POS_LEFT</literal>,
<literal>gtk.POS_RIGHT</literal>, <literal>gtk.POS_TOP</literal>,
<literal>gtk.POS_BOTTOM</literal> or -1 to indicate the snap edge is
automatically selected. See <link
linkend="method-gtkhandlebox--set-snap-edge"><methodname>set_snap_edge</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkhandlebox--get-child-detached">
      <title>gtk.HandleBox.get_child_detached</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_child_detached</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the child is currently detached,
	  otherwise <literal>False</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_child_detached</methodname>() method gets
	whether the handlebox's child is currently detached.
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkhandlebox--child-attached">
      <title>The "child-attached" gtk.HandleBox Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>handlebox</parameter></methodparam>
	  <methodparam><parameter>widget</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>handlebox</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the child widget</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 "child-attached" signal is emitted when the contents of the
handlebox are reattached to the main window.</para>

    </refsect2>

    <refsect2 id="signal-gtkhandlebox--child-detached">
      <title>The "child-detached" gtk.HandleBox Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>handlebox</parameter></methodparam>
	  <methodparam><parameter>widget</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>handlebox</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the child widget</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 "child-detached" signal is emitted when the contents of the
handlebox are detached from the main window.</para>

    </refsect2>

  </refsect1>

</refentry>