source: pkg/pygtk/branches/upstream/current/docs/reference/pygtk-gtklayout.xml @ 4

Revision 4, 20.8 KB checked in by alanbach-guest, 6 years ago (diff)

[svn-inject] Installing original source of pygtk
Line 
1<?xml version="1.0" standalone="no"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
5<refentry id="class-gtklayout">
6  <refnamediv>
7    <refname>gtk.Layout</refname>
8    <refpurpose>infinite scrollable area containing child widgets and custom
9drawing</refpurpose>
10  </refnamediv>
11
12  <refsect1>
13    <title>Synopsis</title>
14
15    <classsynopsis language="python">
16      <ooclass><classname>gtk.Layout</classname></ooclass>
17      <ooclass><classname><link
18linkend="class-gtkcontainer">gtk.Container</link></classname></ooclass>
19      <constructorsynopsis language="python">
20        <methodname><link
21linkend="constructor-gtklayout">gtk.Layout</link></methodname>
22        <methodparam><parameter
23                       role="keyword">hadjustment</parameter><initializer>None</initializer></methodparam>
24        <methodparam><parameter
25                       role="keyword">vadjustment</parameter><initializer>None</initializer></methodparam>
26      </constructorsynopsis>
27      <methodsynopsis language="python">
28        <methodname><link
29linkend="method-gtklayout--put">put</link></methodname>
30        <methodparam><parameter
31                       role="keyword">child_widget</parameter></methodparam>
32        <methodparam><parameter role="keyword">x</parameter></methodparam>
33        <methodparam><parameter role="keyword">y</parameter></methodparam>
34      </methodsynopsis>
35      <methodsynopsis language="python">
36        <methodname><link
37linkend="method-gtklayout--move">move</link></methodname>
38        <methodparam><parameter
39                       role="keyword">child_widget</parameter></methodparam>
40        <methodparam><parameter role="keyword">x</parameter></methodparam>
41        <methodparam><parameter role="keyword">y</parameter></methodparam>
42      </methodsynopsis>
43      <methodsynopsis language="python">
44        <methodname><link
45linkend="method-gtklayout--set-size">set_size</link></methodname>
46        <methodparam><parameter
47                       role="keyword">width</parameter></methodparam>
48        <methodparam><parameter
49                       role="keyword">height</parameter></methodparam>
50      </methodsynopsis>
51      <methodsynopsis language="python">
52        <methodname><link
53linkend="method-gtklayout--get-size">get_size</link></methodname>
54        <methodparam></methodparam>
55      </methodsynopsis>
56      <methodsynopsis language="python">
57        <methodname><link
58linkend="method-gtklayout--get-hadjustment">get_hadjustment</link></methodname>
59        <methodparam></methodparam>  </methodsynopsis>
60      <methodsynopsis language="python">
61        <methodname><link
62linkend="method-gtklayout--get-vadjustment">get_vadjustment</link></methodname>
63        <methodparam></methodparam>  </methodsynopsis>
64      <methodsynopsis language="python">
65        <methodname><link
66linkend="method-gtklayout--set-hadjustment">set_hadjustment</link></methodname>
67        <methodparam><parameter
68                       role="keyword">adjustment</parameter></methodparam>
69      </methodsynopsis>
70      <methodsynopsis language="python">
71        <methodname><link
72linkend="method-gtklayout--set-vadjustment">set_vadjustment</link></methodname>
73        <methodparam><parameter
74                       role="keyword">adjustment</parameter></methodparam>
75      </methodsynopsis>
76    </classsynopsis>
77
78  </refsect1>
79
80  <refsect1>
81    <title>Ancestry</title>
82
83<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
84  +-- <link linkend="class-gtkobject">gtk.Object</link>
85    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
86      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
87        +-- <link linkend="class-gtklayout">gtk.Layout</link>
88</synopsis>
89
90  </refsect1>
91
92  <refsect1 id="properties-gtklayout">
93    <title>gtk.Layout Properties</title>
94
95    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
96    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
97    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
98
99    <blockquote role="properties">
100      <informaltable pgwide="1" frame="none">
101        <tgroup cols="3">
102          <colspec column="1" colwidth="1in"/>
103          <colspec column="2" colwidth="1in"/>
104          <colspec column="3" colwidth="4in"/>
105          <tbody>
106
107            <row valign="top">
108              <entry>"hadjustment"</entry>
109              <entry>Read-Write</entry>
110              <entry>The <link
111linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
112for the horizontal position.</entry>
113            </row>
114
115            <row valign="top">
116              <entry>"height"</entry>
117              <entry>Read-Write</entry>
118              <entry>the layout height</entry>
119            </row>
120
121            <row valign="top">
122              <entry>"vadjustment"</entry>
123              <entry>Read-Write</entry>
124              <entry>The <link
125linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
126for the vertical position.</entry>
127            </row>
128
129            <row valign="top">
130              <entry>"width"</entry>
131              <entry>Read-Write</entry>
132              <entry>the layout width</entry>
133            </row>
134
135          </tbody>
136        </tgroup>
137      </informaltable>
138    </blockquote>
139
140  </refsect1>
141
142  <refsect1 id="style-properties-gtklayout">
143    <title>gtk.Layout Style Properties</title>
144
145    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
146
147  </refsect1>
148
149  <refsect1 id="child-properties-gtklayout">
150    <title>gtk.Layout Child Properties</title>
151
152    <blockquote role="properties">
153      <informaltable pgwide="1" frame="none">
154        <tgroup cols="3">
155          <colspec column="1" colwidth="1in"/>
156          <colspec column="2" colwidth="1in"/>
157          <colspec column="3" colwidth="4in"/>
158          <tbody>
159
160            <row valign="top">
161              <entry>"x"</entry>
162              <entry>Read-Write</entry>
163              <entry>the X position of the child</entry>
164            </row>
165
166            <row valign="top">
167              <entry>"y"</entry>
168              <entry>Read-Write</entry>
169              <entry>the Y position of the child</entry>
170            </row>
171
172          </tbody>
173        </tgroup>
174      </informaltable>
175    </blockquote>
176
177  </refsect1>
178
179  <refsect1>
180    <title>Attributes</title>
181
182    <blockquote role="properties">
183      <informaltable pgwide="1" frame="none">
184        <tgroup cols="3">
185          <colspec column="1" colwidth="1in"/>
186          <colspec column="2" colwidth="1in"/>
187          <colspec column="3" colwidth="4in"/>
188          <tbody>
189
190            <row valign="top">
191              <entry>"bin_window"</entry>
192              <entry>Read</entry>
193              <entry>the window of a layout to draw into</entry>
194            </row>
195
196          </tbody>
197        </tgroup>
198      </informaltable>
199    </blockquote>
200
201  </refsect1>
202
203  <refsect1 id="signal-prototypes-gtklayout">
204    <title>gtk.Layout Signal Prototypes</title>
205
206    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
207    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
208    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
209    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
210
211    <variablelist>
212      <varlistentry>
213        <term>"<link
214linkend="signal-gtklayout--set-scroll-adjustments">set-scroll-adjustments</link>"</term>
215        <listitem>
216          <methodsynopsis
217            language="python"><methodname>callback</methodname>
218            <methodparam><parameter>layout</parameter>
219            </methodparam>
220            <methodparam><parameter>hadjustment</parameter>
221            </methodparam>
222            <methodparam><parameter>vadjustment</parameter>
223            </methodparam>
224            <methodparam><parameter>user_param1</parameter>
225            </methodparam>
226            <methodparam><parameter>...</parameter>
227            </methodparam>
228          </methodsynopsis>
229        </listitem>
230      </varlistentry>
231    </variablelist>
232
233  </refsect1>
234
235  <refsect1>
236    <title>Description</title>
237
238    <para>The <link
239linkend="class-gtklayout"><classname>gtk.Layout</classname></link> is a
240simple container widget similar to the <link
241linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link> container
242widget. Like the <link
243linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link> the <link
244linkend="class-gtklayout"><classname>gtk.Layout</classname></link> places a
245child widget at a specific position within the container. The <link
246linkend="class-gtklayout"><classname>gtk.Layout</classname></link> offers
247two features beyond the <link
248linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link>
249widget:</para>
250
251    <itemizedlist>
252      <listitem>
253        <simpara>a very large width and height for the container - limited
254by the size of an unsigned integer.</simpara>
255      </listitem>
256      <listitem>
257        <simpara>horizontal and vertical adjustments can be specified for
258use with scrollbars, etc.</simpara>
259      </listitem>
260    </itemizedlist>
261
262    <para>The <link
263linkend="class-gtklayout"><classname>gtk.Layout</classname></link> can also
264be drawn on similar to drawing on a <link
265linkend="class-gtkdrawingarea"><classname>gtk.DrawingArea</classname></link>.
266When handling expose events on a <link
267linkend="class-gtklayout"><classname>gtk.Layout</classname></link>, you must
268draw to the window specified by the <literal>bin_window</literal> attribute
269rather than the widget <literal>window</literal> attribute.</para>
270
271  </refsect1>
272
273  <refsect1 id="constructor-gtklayout">
274    <title>Constructor</title>
275
276    <programlisting><constructorsynopsis language="python">
277        <methodname>gtk.Layout</methodname>
278        <methodparam><parameter
279                       role="keyword">hadjustment</parameter><initializer>None</initializer></methodparam>
280        <methodparam><parameter
281                       role="keyword">vadjustment</parameter><initializer>None</initializer></methodparam>
282      </constructorsynopsis></programlisting>
283    <variablelist>
284      <varlistentry>
285        <term><parameter
286role="keyword">hadjustment</parameter>&nbsp;:</term>
287        <listitem><simpara>horizontal adjustment, or
288<literal>None</literal></simpara></listitem>
289      </varlistentry>
290      <varlistentry>
291        <term><parameter
292role="keyword">vadjustment</parameter>&nbsp;:</term>
293        <listitem><simpara>vertical adjustment, or
294<literal>None</literal></simpara></listitem>
295      </varlistentry>
296      <varlistentry>
297        <term><emphasis>Returns</emphasis>&nbsp;:</term>
298        <listitem><simpara>a new <link
299linkend="class-gtklayout"><classname>gtk.Layout</classname></link></simpara></listitem>
300      </varlistentry>
301    </variablelist>
302
303    <para>Creates a new <link
304linkend="class-gtklayout"><classname>gtk.Layout</classname></link>. Usually
305the <parameter>hadjustment</parameter> and
306<parameter>vadjustment</parameter> arguments are not specified or are
307specified as <literal>None</literal>, so that new adjustments are
308created.</para>
309
310  </refsect1>
311
312  <refsect1>
313    <title>Methods</title>
314
315    <refsect2 id="method-gtklayout--put">
316      <title>gtk.Layout.put</title>
317
318      <programlisting><methodsynopsis language="python">
319          <methodname>put</methodname>
320          <methodparam><parameter
321                         role="keyword">child_widget</parameter></methodparam>
322          <methodparam><parameter role="keyword">x</parameter></methodparam>
323          <methodparam><parameter role="keyword">y</parameter></methodparam>
324        </methodsynopsis></programlisting>
325      <variablelist>
326        <varlistentry>
327          <term><parameter
328role="keyword">child_widget</parameter>&nbsp;:</term>
329          <listitem><simpara>the child widget</simpara></listitem>
330        </varlistentry>
331        <varlistentry>
332          <term><parameter role="keyword">x</parameter>&nbsp;:</term>
333          <listitem><simpara>the X position of child
334widget</simpara></listitem>
335        </varlistentry>
336        <varlistentry>
337          <term><parameter role="keyword">y</parameter>&nbsp;:</term>
338          <listitem><simpara>the Y position of child
339widget</simpara></listitem>
340        </varlistentry>
341      </variablelist>
342
343      <para>The <methodname>put</methodname>() method adds
344<parameter>child_widget</parameter> to the layout and places its upper, left
345corner at the position specified by <parameter>x</parameter> and
346<parameter>y</parameter>.</para>
347
348    </refsect2>
349
350    <refsect2 id="method-gtklayout--move">
351      <title>gtk.Layout.move</title>
352
353      <programlisting><methodsynopsis language="python">
354          <methodname>move</methodname>
355          <methodparam><parameter
356                         role="keyword">child_widget</parameter></methodparam>
357          <methodparam><parameter role="keyword">x</parameter></methodparam>
358          <methodparam><parameter role="keyword">y</parameter></methodparam>
359        </methodsynopsis></programlisting>
360      <variablelist>
361        <varlistentry>
362          <term><parameter
363role="keyword">child_widget</parameter>&nbsp;:</term>
364          <listitem><simpara>a current child of the
365layout</simpara></listitem>
366        </varlistentry>
367        <varlistentry>
368          <term><parameter role="keyword">x</parameter>&nbsp;:</term>
369          <listitem><simpara>the X position to move
370<parameter>child_widget</parameter> to</simpara></listitem>
371        </varlistentry>
372        <varlistentry>
373          <term><parameter role="keyword">y</parameter>&nbsp;:</term>
374          <listitem><simpara>the Y position to move
375<parameter>child_widget</parameter> to</simpara></listitem>
376        </varlistentry>
377      </variablelist>
378
379      <para>The <methodname>move</methodname>() method moves a current child
380of the layout (specified by <parameter>child_widget</parameter>) to the new
381position specified by <parameter>x</parameter> and <parameter>y</parameter>.
382The upper, left corner of <parameter>child_widget</parameter> will be placed
383at (<parameter>x</parameter>, <parameter>y</parameter>).</para>
384
385    </refsect2>
386
387    <refsect2 id="method-gtklayout--set-size">
388      <title>gtk.Layout.set_size</title>
389
390      <programlisting><methodsynopsis language="python">
391          <methodname>set_size</methodname>
392          <methodparam><parameter
393                         role="keyword">width</parameter></methodparam>
394          <methodparam><parameter
395                         role="keyword">height</parameter></methodparam>
396        </methodsynopsis></programlisting>
397      <variablelist>
398        <varlistentry>
399          <term><parameter role="keyword">width</parameter>&nbsp;:</term>
400          <listitem><simpara>width of the layout area</simpara></listitem>
401        </varlistentry>
402        <varlistentry>
403          <term><parameter role="keyword">height</parameter>&nbsp;:</term>
404          <listitem><simpara>height of the layout area</simpara></listitem>
405        </varlistentry>
406      </variablelist>
407
408      <para>The <methodname>set_size</methodname>() method sets the size of
409the virtual area of the layout to the values specified by
410<parameter>width</parameter> and <parameter>height</parameter>. The "width"
411and "height" properties are also set by this method.</para>
412
413    </refsect2>
414
415    <refsect2 id="method-gtklayout--get-size">
416      <title>gtk.Layout.get_size</title>
417
418      <programlisting><methodsynopsis language="python">
419          <methodname>get_size</methodname>
420          <methodparam></methodparam>
421        </methodsynopsis></programlisting>
422      <variablelist>
423        <varlistentry>
424          <term><emphasis>Returns</emphasis>&nbsp;:</term>
425          <listitem><simpara>a tuple containing the width and height set on
426<parameter>layout</parameter></simpara></listitem>
427        </varlistentry>
428      </variablelist>
429
430      <para>The <methodname>get_size</methodname>() method returns a tuple
431that contains the width and height of the virtual size that has been set on
432the layout. See <link
433linkend="method-gtklayout--set-size"><methodname>set_size</methodname>()</link>.</para>
434
435    </refsect2>
436
437    <refsect2 id="method-gtklayout--get-hadjustment">
438      <title>gtk.Layout.get_hadjustment</title>
439
440      <programlisting><methodsynopsis language="python">
441          <methodname>get_hadjustment</methodname>
442          <methodparam></methodparam>  </methodsynopsis></programlisting>
443      <variablelist>
444        <varlistentry>
445          <term><emphasis>Returns</emphasis>&nbsp;:</term>
446          <listitem><simpara>a horizontal adjustment</simpara></listitem>
447        </varlistentry>
448      </variablelist>
449
450      <para>The <methodname>get_hadjustment</methodname>() method returns
451the value of the "hadjustment" property that contains the horizontal
452adjustment object associated with the layout. This function should only be
453called after the layout has been placed in a <link
454linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link> 
455or has otherwise been configured for scrolling. See <link
456linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>,
457<link
458linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
459<link
460linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
461for details.</para>
462
463    </refsect2>
464
465    <refsect2 id="method-gtklayout--get-vadjustment">
466      <title>gtk.Layout.get_vadjustment</title>
467
468      <programlisting><methodsynopsis language="python">
469          <methodname>get_vadjustment</methodname>
470          <methodparam></methodparam>  </methodsynopsis></programlisting>
471      <variablelist>
472        <varlistentry>
473          <term><emphasis>Returns</emphasis>&nbsp;:</term>
474          <listitem><simpara>a vertical adjustment</simpara></listitem>
475        </varlistentry>
476      </variablelist>
477
478      <para>The <methodname>get_vadjustment</methodname>() method returns
479the "vadjustment" property that contains the vertical adjustment object
480associated with the layout. This function should only be called after the
481layout has been placed in a <link
482linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link> 
483or has otherwise been configured for scrolling. See <link
484linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>,
485<link
486linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
487<link
488linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
489for details.</para>
490
491    </refsect2>
492
493    <refsect2 id="method-gtklayout--set-hadjustment">
494      <title>gtk.Layout.set_hadjustment</title>
495
496      <programlisting><methodsynopsis language="python">
497          <methodname>set_hadjustment</methodname>
498          <methodparam><parameter
499                         role="keyword">adjustment</parameter></methodparam>
500        </methodsynopsis></programlisting>
501      <variablelist>
502        <varlistentry>
503          <term><parameter
504role="keyword">adjustment</parameter>&nbsp;:</term>
505          <listitem><simpara>a horizontal adjustment</simpara></listitem>
506        </varlistentry>
507      </variablelist>
508
509      <para>The <methodname>set_hadjustment</methodname>() method sets the
510horizontal adjustment for the layout (and the "hadjustment" property) to the
511value of <parameter>adjustment</parameter>. See <link
512linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>,
513<link
514linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
515<link
516linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
517for details.</para>
518
519    </refsect2>
520
521    <refsect2 id="method-gtklayout--set-vadjustment">
522      <title>gtk.Layout.set_vadjustment</title>
523
524      <programlisting><methodsynopsis language="python">
525          <methodname>set_vadjustment</methodname>
526          <methodparam><parameter
527                         role="keyword">adjustment</parameter></methodparam>
528        </methodsynopsis></programlisting>
529      <variablelist>
530        <varlistentry>
531          <term><parameter
532role="keyword">adjustment</parameter>&nbsp;:</term>
533          <listitem><simpara>a vertical adjustment</simpara></listitem>
534        </varlistentry>
535      </variablelist>
536
537      <para>The <methodname>set_vadjustment</methodname>() method sets the
538vertical adjustment for the layout (and the "vadjustment" property) to the
539value of <parameter>adjustment</parameter>. See <link
540linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>,
541<link
542linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
543<link
544linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
545for details.</para>
546
547    </refsect2>
548
549  </refsect1>
550
551  <refsect1>
552    <title>Signals</title>
553
554    <refsect2 id="signal-gtklayout--set-scroll-adjustments">
555      <title>The "set-scroll-adjustments" gtk.Layout Signal</title>
556
557      <programlisting><methodsynopsis language="python">
558          <methodname>callback</methodname>
559          <methodparam><parameter>layout</parameter></methodparam>
560          <methodparam><parameter>hadjustment</parameter></methodparam>
561          <methodparam><parameter>vadjustment</parameter></methodparam>
562          <methodparam><parameter>user_param1</parameter></methodparam>
563          <methodparam><parameter>...</parameter></methodparam>
564        </methodsynopsis></programlisting>
565
566      <variablelist>
567        <varlistentry>
568          <term><parameter>layout</parameter>&nbsp;:</term>
569          <listitem><simpara>the layout that received the
570signal</simpara></listitem>
571        </varlistentry>
572        <varlistentry>
573          <term><parameter>hadjustment</parameter>&nbsp;:</term>
574          <listitem><simpara>the horizontal adjustment associated with the
575layout.</simpara></listitem>
576        </varlistentry>
577        <varlistentry>
578          <term><parameter>vadjustment</parameter>&nbsp;:</term>
579          <listitem><simpara>the horizontal adjustment associated with the
580layout.</simpara></listitem>
581        </varlistentry>
582        <varlistentry>
583          <term><parameter>user_param1</parameter>&nbsp;:</term>
584          <listitem><simpara>the first user parameter (if any) specified
585with the <link
586linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
587method</simpara></listitem>
588        </varlistentry>
589        <varlistentry>
590          <term><parameter>...</parameter>&nbsp;:</term>
591          <listitem><simpara>additional user parameters (if
592any)</simpara></listitem>
593        </varlistentry>
594      </variablelist>
595
596      <para>The "set-scroll-adjustments" signal is emitted when one of the
597adjustments associated with a layout is changed.</para>
598
599    </refsect2>
600
601  </refsect1>
602
603</refentry>
Note: See TracBrowser for help on using the repository browser.