path: root/docs/reference/pygtk-gtklayout.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-gtklayout">
  <refnamediv>
    <refname>gtk.Layout</refname>
    <refpurpose>infinite scrollable area containing child widgets and custom
drawing</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Layout</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkcontainer">gtk.Container</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtklayout">gtk.Layout</link></methodname>
	<methodparam><parameter
		       role="keyword">hadjustment</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">vadjustment</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--put">put</link></methodname>
	<methodparam><parameter
		       role="keyword">child_widget</parameter></methodparam>
	<methodparam><parameter role="keyword">x</parameter></methodparam>
	<methodparam><parameter role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--move">move</link></methodname>
	<methodparam><parameter
		       role="keyword">child_widget</parameter></methodparam>
	<methodparam><parameter role="keyword">x</parameter></methodparam>
	<methodparam><parameter role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--set-size">set_size</link></methodname>
	<methodparam><parameter
		       role="keyword">width</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">height</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--get-size">get_size</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--get-hadjustment">get_hadjustment</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--get-vadjustment">get_vadjustment</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--set-hadjustment">set_hadjustment</link></methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklayout--set-vadjustment">set_vadjustment</link></methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter></methodparam>
      </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtklayout--get-bin-window">get_bin_window</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-gtklayout">gtk.Layout</link>
</synopsis>

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


  <refsect1 id="properties-gtklayout">
    <title>gtk.Layout 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>"hadjustment"</entry>
	      <entry>Read-Write</entry>
	      <entry>The <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for the horizontal position.</entry>
	    </row>

	    <row valign="top">
	      <entry>"height"</entry>
	      <entry>Read-Write</entry>
	      <entry>the layout height</entry>
	    </row>

	    <row valign="top">
	      <entry>"vadjustment"</entry>
	      <entry>Read-Write</entry>
	      <entry>The <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for the vertical position.</entry>
	    </row>

	    <row valign="top">
	      <entry>"width"</entry>
	      <entry>Read-Write</entry>
	      <entry>the layout width</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtklayout">
    <title>gtk.Layout Style Properties</title>

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

  </refsect1>

  <refsect1 id="child-properties-gtklayout">
    <title>gtk.Layout Child Properties</title>

    <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>"x"</entry>
	      <entry>Read-Write</entry>
	      <entry>the X position of the child</entry>
	    </row>

	    <row valign="top">
	      <entry>"y"</entry>
	      <entry>Read-Write</entry>
	      <entry>the Y position of the child</entry>
	    </row>

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

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <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>"bin_window"</entry>
	      <entry>Read</entry>
	      <entry>the window of a layout to draw into</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtklayout">
    <title>gtk.Layout 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-gtklayout--set-scroll-adjustments">set-scroll-adjustments</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>layout</parameter>
            </methodparam>
            <methodparam><parameter>hadjustment</parameter>
            </methodparam>
            <methodparam><parameter>vadjustment</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-gtklayout"><classname>gtk.Layout</classname></link> is a
simple container widget similar to the <link
linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link> container
widget. Like the <link
linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link> the <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link> places a
child widget at a specific position within the container. The <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link> offers
two features beyond the <link
linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link>
widget:</para>

    <itemizedlist>
      <listitem>
	<simpara>a very large width and height for the container - limited
by the size of an unsigned integer.</simpara>
      </listitem>
      <listitem>
	<simpara>horizontal and vertical adjustments can be specified for
use with scrollbars, etc.</simpara>
      </listitem>
    </itemizedlist>

    <para>The <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link> can also
be drawn on similar to drawing on a <link
linkend="class-gtkdrawingarea"><classname>gtk.DrawingArea</classname></link>. 
When handling expose events on a <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link>, you must
draw to the window specified by the <literal>bin_window</literal> attribute
rather than the widget <literal>window</literal> attribute.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Layout</methodname>
	<methodparam><parameter
		       role="keyword">hadjustment</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">vadjustment</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter
role="keyword">hadjustment</parameter>&nbsp;:</term>
	<listitem><simpara>horizontal adjustment, or
<literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter
role="keyword">vadjustment</parameter>&nbsp;:</term>
	<listitem><simpara>vertical adjustment, or
<literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtklayout"><classname>gtk.Layout</classname></link>. Usually
the <parameter>hadjustment</parameter> and
<parameter>vadjustment</parameter> arguments are not specified or are
specified as <literal>None</literal>, so that new adjustments are
created.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtklayout--put">
      <title>gtk.Layout.put</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>put</methodname>
	  <methodparam><parameter
			 role="keyword">child_widget</parameter></methodparam>
	  <methodparam><parameter role="keyword">x</parameter></methodparam>
	  <methodparam><parameter role="keyword">y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">child_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the child widget</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X position of child
widget</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y position of child
widget</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>put</methodname>() method adds
<parameter>child_widget</parameter> to the layout and places its upper, left
corner at the position specified by <parameter>x</parameter> and
<parameter>y</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--move">
      <title>gtk.Layout.move</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>move</methodname>
	  <methodparam><parameter
			 role="keyword">child_widget</parameter></methodparam>
	  <methodparam><parameter role="keyword">x</parameter></methodparam>
	  <methodparam><parameter role="keyword">y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">child_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>a current child of the
layout</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X position to move
<parameter>child_widget</parameter> to</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y position to move
<parameter>child_widget</parameter> to</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>move</methodname>() method moves a current child
of the layout (specified by <parameter>child_widget</parameter>) to the new
position specified by <parameter>x</parameter> and <parameter>y</parameter>.
The upper, left corner of <parameter>child_widget</parameter> will be placed
at (<parameter>x</parameter>, <parameter>y</parameter>).</para>

    </refsect2>

    <refsect2 id="method-gtklayout--set-size">
      <title>gtk.Layout.set_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_size</methodname>
	  <methodparam><parameter
			 role="keyword">width</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">height</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">width</parameter>&nbsp;:</term>
	  <listitem><simpara>width of the layout area</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">height</parameter>&nbsp;:</term>
	  <listitem><simpara>height of the layout area</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_size</methodname>() method sets the size of
the virtual area of the layout to the values specified by
<parameter>width</parameter> and <parameter>height</parameter>. The "width"
and "height" properties are also set by this method.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--get-size">
      <title>gtk.Layout.get_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the width and height set on
<parameter>layout</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_size</methodname>() method returns a tuple
that contains the width and height of the virtual size that has been set on
the layout. See <link
linkend="method-gtklayout--set-size"><methodname>set_size</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--get-hadjustment">
      <title>gtk.Layout.get_hadjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_hadjustment</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a horizontal adjustment</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_hadjustment</methodname>() method returns
the value of the "hadjustment" property that contains the horizontal
adjustment object associated with the layout. This function should only be
called after the layout has been placed in a <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link> 
or has otherwise been configured for scrolling. See <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>, 
<link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for details.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--get-vadjustment">
      <title>gtk.Layout.get_vadjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_vadjustment</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a vertical adjustment</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_vadjustment</methodname>() method returns
the "vadjustment" property that contains the vertical adjustment object
associated with the layout. This function should only be called after the
layout has been placed in a <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link> 
or has otherwise been configured for scrolling. See <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>, 
<link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for details.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--set-hadjustment">
      <title>gtk.Layout.set_hadjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_hadjustment</methodname>
	  <methodparam><parameter
			 role="keyword">adjustment</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">adjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>a horizontal adjustment</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_hadjustment</methodname>() method sets the
horizontal adjustment for the layout (and the "hadjustment" property) to the
value of <parameter>adjustment</parameter>. See <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>, 
<link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for details.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--set-vadjustment">
      <title>gtk.Layout.set_vadjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_vadjustment</methodname>
	  <methodparam><parameter
			 role="keyword">adjustment</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">adjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>a vertical adjustment</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_vadjustment</methodname>() method sets the
vertical adjustment for the layout (and the "vadjustment" property) to the
value of <parameter>adjustment</parameter>. See <link
linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>, 
<link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
for details.</para>

    </refsect2>

    <refsect2 id="method-gtklayout--get-bin-window">
      <title>gtk.Layout.get_bin_window</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_bin_window</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a
	  <link linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link>.
	  </simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_bin_window</methodname>() method retrieve the bin window
	of the layout used for drawing operations.
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtklayout--set-scroll-adjustments">
      <title>The "set-scroll-adjustments" gtk.Layout Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>layout</parameter></methodparam>
	  <methodparam><parameter>hadjustment</parameter></methodparam>
	  <methodparam><parameter>vadjustment</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>layout</parameter>&nbsp;:</term>
	  <listitem><simpara>the layout that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>hadjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>the horizontal adjustment associated with the
layout.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>vadjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>the horizontal adjustment associated with the
layout.</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 "set-scroll-adjustments" signal is emitted when one of the
adjustments associated with a layout is changed.</para>

    </refsect2>

  </refsect1>

</refentry>