New upstream version 3.23.0

This commit is contained in:
Iain Lane
2018-07-18 14:06:19 +01:00
731 changed files with 556100 additions and 542972 deletions

View File

@ -3,12 +3,12 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GtkContainer: GTK+ 3 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
<link rel="up" href="AbstractObjects.html" title="Abstract Base Classes">
<link rel="prev" href="GtkWidget.html" title="GtkWidget">
<link rel="next" href="GtkBin.html" title="GtkBin">
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
<meta name="generator" content="GTK-Doc V1.25 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@ -537,119 +537,59 @@ every widget request at least enough space to display all of its content at all
<p>When <a class="link" href="GtkWidget.html#gtk-widget-get-preferred-height" title="gtk_widget_get_preferred_height ()"><code class="function">gtk_widget_get_preferred_height()</code></a> is called on a container that is height-for-width,
the container must return the height for its minimum width. This is easily achieved by
simply calling the reverse apis implemented for itself as follows:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
<span class="function">foo_container_get_preferred_height</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">widget</span><span class="symbol">,</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">min_height</span><span class="symbol">,</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">nat_height</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">i_am_in_height_for_width_mode</span><span class="symbol">)</span>
<span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> min_width</span><span class="symbol">;</span>
<span class="normal"> </span><span class="function">GTK_WIDGET_GET_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">)-&gt;</span><span class="function">get_preferred_width</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">,</span>
<span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">min_width</span><span class="symbol">,</span>
<span class="normal"> NULL</span><span class="symbol">);</span>
<span class="normal"> </span><span class="function">GTK_WIDGET_GET_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">)-&gt;</span><span class="normal">get_preferred_height_for_width</span>
<span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">,</span>
<span class="normal"> min_width</span><span class="symbol">,</span>
<span class="normal"> min_height</span><span class="symbol">,</span>
<span class="normal"> nat_height</span><span class="symbol">);</span>
<span class="normal"> </span><span class="cbracket">}</span>
<span class="normal"> </span><span class="keyword">else</span>
<span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="symbol">...</span><span class="normal"> many containers support both </span><span class="usertype">request</span><span class="normal"> modes</span><span class="symbol">,</span><span class="normal"> execute the</span>
<span class="normal"> </span><span class="usertype">real</span><span class="normal"> width</span><span class="symbol">-</span><span class="keyword">for</span><span class="symbol">-</span><span class="normal">height request here by returning the</span>
<span class="normal"> collective heights of all widgets that are stacked</span>
<span class="normal"> </span><span class="function">vertically</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">or whatever is appropriate </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">this</span><span class="normal"> container</span><span class="symbol">)</span>
<span class="normal"> </span><span class="symbol">...</span>
<span class="normal"> </span><span class="cbracket">}</span>
<span class="cbracket">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<div class="informalexample"><pre class="programlisting">
static void
foo_container_get_preferred_height (GtkWidget *widget,
gint *min_height,
gint *nat_height)
{
if (i_am_in_height_for_width_mode)
{
gint min_width;
GTK_WIDGET_GET_CLASS (widget)-&gt;get_preferred_width (widget,
&amp;min_width,
NULL);
GTK_WIDGET_GET_CLASS (widget)-&gt;get_preferred_height_for_width
(widget,
min_width,
min_height,
nat_height);
}
else
{
... many containers support both request modes, execute the
real width-for-height request here by returning the
collective heights of all widgets that are stacked
vertically (or whatever is appropriate for this container)
...
}
}
</pre></div>
<p></p>
<p>Similarly, when <a class="link" href="GtkWidget.html#gtk-widget-get-preferred-width-for-height" title="gtk_widget_get_preferred_width_for_height ()"><code class="function">gtk_widget_get_preferred_width_for_height()</code></a> is called for a container or widget
that is height-for-width, it then only needs to return the base minimum width like so:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
<span class="function">foo_container_get_preferred_width_for_height</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">widget</span><span class="symbol">,</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> for_height</span><span class="symbol">,</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">min_width</span><span class="symbol">,</span>
<span class="normal"> </span><span class="usertype">gint</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">nat_width</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">i_am_in_height_for_width_mode</span><span class="symbol">)</span>
<span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="function">GTK_WIDGET_GET_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">)-&gt;</span><span class="function">get_preferred_width</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">widget</span><span class="symbol">,</span>
<span class="normal"> min_width</span><span class="symbol">,</span>
<span class="normal"> nat_width</span><span class="symbol">);</span>
<span class="normal"> </span><span class="cbracket">}</span>
<span class="normal"> </span><span class="keyword">else</span>
<span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="symbol">...</span><span class="normal"> execute the </span><span class="usertype">real</span><span class="normal"> width</span><span class="symbol">-</span><span class="keyword">for</span><span class="symbol">-</span><span class="normal">height request here based on</span>
<span class="normal"> the required width of the children collectively </span><span class="keyword">if</span><span class="normal"> the</span>
<span class="normal"> container were to be allocated the </span><span class="usertype">said</span><span class="normal"> height </span><span class="symbol">...</span>
<span class="normal"> </span><span class="cbracket">}</span>
<span class="cbracket">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<div class="informalexample"><pre class="programlisting">
static void
foo_container_get_preferred_width_for_height (GtkWidget *widget,
gint for_height,
gint *min_width,
gint *nat_width)
{
if (i_am_in_height_for_width_mode)
{
GTK_WIDGET_GET_CLASS (widget)-&gt;get_preferred_width (widget,
min_width,
nat_width);
}
else
{
... execute the real width-for-height request here based on
the required width of the children collectively if the
container were to be allocated the said height ...
}
}
</pre></div>
<p></p>
<p>Height for width requests are generally implemented in terms of a virtual allocation
of widgets in the input orientation. Assuming an height-for-width request mode, a container
@ -711,45 +651,23 @@ for regular properties.</p>
&lt;widget&gt; elements, one for each child that should be added to the focus
chain. The ”name” attribute gives the id of the widget.</p>
<p>An example of these properties in UI definitions:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="symbol">&lt;</span><span class="usertype">object</span><span class="normal"> class</span><span class="symbol">=</span><span class="string">"GtkBox"</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="normal">child</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="usertype">object</span><span class="normal"> class</span><span class="symbol">=</span><span class="string">"GtkEntry"</span><span class="normal"> id</span><span class="symbol">=</span><span class="string">"entry1"</span><span class="symbol">/&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="normal">packing</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="usertype">property</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"pack-type"</span><span class="symbol">&gt;</span><span class="normal">start</span><span class="symbol">&lt;/</span><span class="normal">property</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;/</span><span class="normal">packing</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;/</span><span class="normal">child</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="normal">child</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="usertype">object</span><span class="normal"> class</span><span class="symbol">=</span><span class="string">"GtkEntry"</span><span class="normal"> id</span><span class="symbol">=</span><span class="string">"entry2"</span><span class="symbol">/&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;/</span><span class="normal">child</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="normal">focus</span><span class="symbol">-</span><span class="normal">chain</span><span class="symbol">&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="usertype">widget</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"entry1"</span><span class="symbol">/&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;</span><span class="usertype">widget</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"entry2"</span><span class="symbol">/&gt;</span>
<span class="normal"> </span><span class="symbol">&lt;/</span><span class="normal">focus</span><span class="symbol">-</span><span class="normal">chain</span><span class="symbol">&gt;</span>
<span class="symbol">&lt;/</span><span class="normal">object</span><span class="symbol">&gt;</span></pre></td>
</tr>
</tbody>
</table>
</div>
<div class="informalexample"><pre class="programlisting">
&lt;object class="GtkBox"&gt;
&lt;child&gt;
&lt;object class="GtkEntry" id="entry1"/&gt;
&lt;packing&gt;
&lt;property name="pack-type"&gt;start&lt;/property&gt;
&lt;/packing&gt;
&lt;/child&gt;
&lt;child&gt;
&lt;object class="GtkEntry" id="entry2"/&gt;
&lt;/child&gt;
&lt;focus-chain&gt;
&lt;widget name="entry1"/&gt;
&lt;widget name="entry2"/&gt;
&lt;/focus-chain&gt;
&lt;/object&gt;
</pre></div>
<p></p>
</div>
</div>
@ -1043,7 +961,7 @@ rather than <a class="link" href="GtkContainer.html#gtk-container-forall" title=
</tr>
<tr>
<td class="parameter_name"><p>callback</p></td>
<td class="parameter_description"><p>a callback. </p></td>
<td class="parameter_description"><p> a callback. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span></td>
</tr>
<tr>
@ -1079,7 +997,7 @@ gtk_container_get_children (<em class="parameter"><code><a class="link" href="Gt
</div>
<div class="refsect3">
<a name="gtk-container-get-children.returns"></a><h4>Returns</h4>
<p>a newly-allocated list of the containers non-internal children. </p>
<p> a newly-allocated list of the containers non-internal children. </p>
<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> GtkWidget][<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>]</span></p>
</div>
</div>
@ -1184,7 +1102,7 @@ currently focused widget. That can be obtained by calling
</div>
<div class="refsect3">
<a name="gtk-container-get-focus-child.returns"></a><h4>Returns</h4>
<p>The child widget which will receive the
<p> The child widget which will receive the
focus inside <em class="parameter"><code>container</code></em>
when the <em class="parameter"><code>container</code></em>
is focused,
@ -1224,7 +1142,7 @@ default behaviour by overriding the class closure of this signal.</p>
</tr>
<tr>
<td class="parameter_name"><p>child</p></td>
<td class="parameter_description"><p>a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a>, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_description"><p> a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a>, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
</tbody>
@ -1255,7 +1173,7 @@ gtk_container_get_focus_vadjustment (<em class="parameter"><code><a class="link"
</div>
<div class="refsect3">
<a name="gtk-container-get-focus-vadjustment.returns"></a><h4>Returns</h4>
<p>the vertical focus adjustment, or
<p> the vertical focus adjustment, or
<code class="literal">NULL</code> if none has been set. </p>
<p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
</div>
@ -1323,7 +1241,7 @@ gtk_container_get_focus_hadjustment (<em class="parameter"><code><a class="link"
</div>
<div class="refsect3">
<a name="gtk-container-get-focus-hadjustment.returns"></a><h4>Returns</h4>
<p>the horizontal focus adjustment, or <code class="literal">NULL</code> if
<p> the horizontal focus adjustment, or <code class="literal">NULL</code> if
none has been set. </p>
<p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
</div>
@ -1814,7 +1732,7 @@ than <a class="link" href="GtkContainer.html#gtk-container-forall" title="gtk_co
</tr>
<tr>
<td class="parameter_name"><p>callback</p></td>
<td class="parameter_description"><p>a callback. </p></td>
<td class="parameter_description"><p> a callback. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>][<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym> callback_data]</span></td>
</tr>
<tr>
@ -1972,7 +1890,7 @@ of the children. In that case, GTK+ stores <code class="literal">NULL</code> in
</tr>
<tr>
<td class="parameter_name"><p>focusable_widgets</p></td>
<td class="parameter_description"><p>location
<td class="parameter_description"><p> location
to store the focus chain of the
container, or <code class="literal">NULL</code>. You should free this list
using <code class="function">g_list_free()</code> when you are done with it, however
@ -2017,7 +1935,7 @@ when the focus chain is actually traversed.</p>
</tr>
<tr>
<td class="parameter_name"><p>focusable_widgets</p></td>
<td class="parameter_description"><p>the new focus chain. </p></td>
<td class="parameter_description"><p> the new focus chain. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> GtkWidget]</span></td>
</tr>
</tbody>
@ -2065,7 +1983,7 @@ gtk_container_class_find_child_property
<tbody>
<tr>
<td class="parameter_name"><p>cclass</p></td>
<td class="parameter_description"><p>a <a class="link" href="GtkContainer.html#GtkContainerClass" title="struct GtkContainerClass"><span class="type">GtkContainerClass</span></a>. </p></td>
<td class="parameter_description"><p> a <a class="link" href="GtkContainer.html#GtkContainerClass" title="struct GtkContainerClass"><span class="type">GtkContainerClass</span></a>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GtkContainerClass]</span></td>
</tr>
<tr>
@ -2078,7 +1996,7 @@ gtk_container_class_find_child_property
</div>
<div class="refsect3">
<a name="gtk-container-class-find-child-property.returns"></a><h4>Returns</h4>
<p>the <span class="type">GParamSpec</span> of the child
<p> the <span class="type">GParamSpec</span> of the child
property or <code class="literal">NULL</code> if <em class="parameter"><code>class</code></em>
has no child property with that
name. </p>
@ -2152,7 +2070,7 @@ gtk_container_class_install_child_properties
</tr>
<tr>
<td class="parameter_name"><p>pspecs</p></td>
<td class="parameter_description"><p>the <span class="type">GParamSpec</span> array defining the new
<td class="parameter_description"><p> the <span class="type">GParamSpec</span> array defining the new
child properties. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_pspecs]</span></td>
</tr>
@ -2180,7 +2098,7 @@ gtk_container_class_list_child_properties
<tbody>
<tr>
<td class="parameter_name"><p>cclass</p></td>
<td class="parameter_description"><p>a <a class="link" href="GtkContainer.html#GtkContainerClass" title="struct GtkContainerClass"><span class="type">GtkContainerClass</span></a>. </p></td>
<td class="parameter_description"><p> a <a class="link" href="GtkContainer.html#GtkContainerClass" title="struct GtkContainerClass"><span class="type">GtkContainerClass</span></a>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GtkContainerClass]</span></td>
</tr>
<tr>
@ -2193,7 +2111,7 @@ gtk_container_class_list_child_properties
</div>
<div class="refsect3">
<a name="gtk-container-class-list-child-properties.returns"></a><h4>Returns</h4>
<p>a newly allocated <code class="literal">NULL</code>-terminated array of <span class="type">GParamSpec</span>*.
<p> a newly allocated <code class="literal">NULL</code>-terminated array of <span class="type">GParamSpec</span>*.
The array must be freed with <code class="function">g_free()</code>. </p>
<p><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_properties][<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>]</span></p>
</div>
@ -2440,6 +2358,6 @@ user_function (<a class="link" href="GtkContainer.html" title="GtkContainer"><sp
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.27</div>
<hr>Generated by GTK-Doc V1.25</div>
</body>
</html>