gtkhandlebox.sgml 5.38 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
GtkHandleBox

<!-- ##### SECTION Short_Description ##### -->
5
a widget for detachable window portions
Owen Taylor's avatar
Owen Taylor committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkHandleBox 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 a separate window (the <firstterm>float
window</firstterm>) containing the child widget. A thin
<firstterm>ghost</firstterm> is drawn in the original location of the
handlebox. By dragging the separate window back to its original
location, it can be reattached.
</para>
<para>
When reattaching, the ghost and float window, must be aligned
along one of the edges, the <firstterm>snap edge</firstterm>.
This either can be specified by the application programmer
explicitely, or GTK+ will pick a reasonable default based
on the handle position.
</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 deattached. For
instance, if the handlebox is packed at the bottom of a VBox, 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 %GTK_POS_BOTTOM.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

Matthias Clasen's avatar
2.7.0  
Matthias Clasen committed
39 40 41
<!-- ##### SECTION Stability_Level ##### -->


42 43 44
<!-- ##### SECTION Image ##### -->


Owen Taylor's avatar
Owen Taylor committed
45 46 47 48 49 50
<!-- ##### STRUCT GtkHandleBox ##### -->
<para>
The #GtkHandleBox-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)

Matthias Clasen's avatar
Matthias Clasen committed
51 52
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
Owen Taylor's avatar
Owen Taylor committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
<tbody>

<row>
<entry>GtkShadowType shadow_type;</entry>
<entry>The shadow type for the entry. (See gtk_handle_box_set_shadow_type()).</entry>
</row>

<row>
<entry>GtkPositionType handle_position;</entry>
<entry>The position of the handlebox's handle with respect
to the child. (See gtk_handle_box_set_handle_position())</entry>
</row>

<row>
<entry>gint snap_edge;</entry>
<entry>A value of type #GtkPosition type indicating snap edge for the widget.
(See gtk_handle_box_set_snap_edge). The value of -1 indicates
Owen Taylor's avatar
Owen Taylor committed
70 71
that this value has not been set.</entry>
</row>
Owen Taylor's avatar
Owen Taylor committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85

<row>
<entry>#gboolean child_detached;</entry>
<entry>A boolean value indicating whether the handlebox's
child is attached or detached.</entry>
</row>

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

</para>


Soeren Sandmann's avatar
Soeren Sandmann committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
<!-- ##### SIGNAL GtkHandleBox::child-attached ##### -->
<para>
This signal is emitted when the contents of the
handlebox are reattached to the main window.
</para>

@handlebox: the object which received the signal.
@widget: the child widget of the handlebox.
         (this argument provides no extra information
          and is here only for backwards-compatibility)

<!-- ##### SIGNAL GtkHandleBox::child-detached ##### -->
<para>
This signal is emitted when the contents of the
handlebox are detached from the main window.
</para>

@handlebox: the object which received the signal.
@widget: the child widget of the handlebox. 
         (this argument provides no extra information
          and is here only for backwards-compatibility)

Matthias Clasen's avatar
2.13.4  
Matthias Clasen committed
108 109 110 111 112
<!-- ##### ARG GtkHandleBox:child-detached ##### -->
<para>

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
<!-- ##### ARG GtkHandleBox:handle-position ##### -->
<para>

</para>

<!-- ##### ARG GtkHandleBox:shadow-type ##### -->
<para>

</para>

<!-- ##### ARG GtkHandleBox:snap-edge ##### -->
<para>

</para>

<!-- ##### ARG GtkHandleBox:snap-edge-set ##### -->
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
133 134 135 136 137
<!-- ##### FUNCTION gtk_handle_box_new ##### -->
<para>
Create a new handle box.
</para>

138
@void: 
Owen Taylor's avatar
Owen Taylor committed
139 140 141 142 143
@Returns: a new #GtkHandleBox.


<!-- ##### FUNCTION gtk_handle_box_set_shadow_type ##### -->
<para>
144 145
Sets the type of shadow to be drawn around the border 
of the handle box.
Owen Taylor's avatar
Owen Taylor committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
</para>

@handle_box: a #GtkHandleBox
@type: the shadow type.


<!-- ##### FUNCTION gtk_handle_box_set_handle_position ##### -->
<para>
Sets the side of the handlebox where the handle is drawn.
</para>

@handle_box: a #GtkHandleBox
@position: the side of the handlebox where the handle should be drawn.


<!-- ##### FUNCTION gtk_handle_box_set_snap_edge ##### -->
<para>
Sets the snap edge of a handlebox. 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.
</para>
<para>
If the snap edge is not set, then an appropriate value
will be guessed from the handle position. If the
handle position is %GTK_POS_RIGHT or %GTK_POS_LEFT,
then the snap edge will be %GTK_POS_TOP, otherwise
it will be %GTK_POS_LEFT.
</para>

@handle_box: a #GtkHandleBox
@edge: the snap edge, or -1 to unset the value; in which
case GTK+ will try to guess an appropriate value
in the future.


185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
<!-- ##### FUNCTION gtk_handle_box_get_handle_position ##### -->
<para>

</para>

@handle_box: 
@Returns: 


<!-- ##### FUNCTION gtk_handle_box_get_shadow_type ##### -->
<para>

</para>

@handle_box: 
@Returns: 


<!-- ##### FUNCTION gtk_handle_box_get_snap_edge ##### -->
<para>

</para>

@handle_box: 
@Returns: 


Matthias Clasen's avatar
2.13.5  
Matthias Clasen committed
212 213 214 215 216 217 218 219 220
<!-- ##### FUNCTION gtk_handle_box_get_child_detached ##### -->
<para>

</para>

@handle_box: 
@Returns: