gtkwindow.sgml 8.75 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
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 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
<!-- ##### SECTION Title ##### -->
GtkWindow

<!-- ##### SECTION Short_Description ##### -->


<!-- ##### SECTION Long_Description ##### -->
<para>

</para>

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

</para>

<!-- ##### STRUCT GtkWindow ##### -->
<para>

</para>


<!-- ##### FUNCTION gtk_window_new ##### -->
<para>

</para>

@type: 
@Returns: 


<!-- ##### FUNCTION gtk_window_set_title ##### -->
<para>

</para>

@window: 
@title: 


<!-- ##### FUNCTION gtk_window_set_wmclass ##### -->
<para>

</para>

@window: 
@wmclass_name: 
@wmclass_class: 


<!-- ##### FUNCTION gtk_window_set_policy ##### -->
<para>
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
Changes how a toplevel window deals with its size request and user resize
attempts. There are really only two reasonable ways to call this function:
<orderedlist>
<listitem>
<para>
<literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, TRUE, FALSE)</literal> 
means that the window is user-resizable.
</para>
</listitem>
<listitem>
<para>
<literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, FALSE, TRUE)</literal> 
means that the window's size is program-controlled, and should simply match 
the current size request of the window's children.
</para>
</listitem>
</orderedlist>
The first policy is the default, that is, by default windows are designed to 
be resized by users.
</para>
Owen Taylor's avatar
Owen Taylor committed
73

74 75 76 77 78 79 80 81
<para>
The basic ugly truth of this function is that it should be simply:
<programlisting>
 void gtk_window_set_user_resizeable(GtkWidget* window, gboolean setting);
</programlisting>
So, pretend it is like that, and only use the two policies mentioned above.
GTK+ 1.4 may replace gtk_window_set_policy() with a nicer function like
gtk_window_set_user_resizeable().
Owen Taylor's avatar
Owen Taylor committed
82 83
</para>

84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
<para>
If set to TRUE, the @allow_grow parameter allows the user to expand the window
beyond the size request of its child widgets. If @allow_grow is TRUE, be sure to
check that your child widgets work properly as the window is resized.
</para>

<para>
A toplevel window will always change size to ensure its child widgets receive
their requested size. This means that if you add child widgets, the toplevel
window will expand to contain them. However, normally the toplevel will not
shrink to fit the size request of its children if it's too large; the
@auto_shrink parameter causes the window to shrink when child widgets have too
much space. @auto_shrink is normally used with the second of the two window
policies mentioned above.  That is, set @auto_shrink to TRUE if you want the
window to have a fixed, always-optimal size determined by your program.
</para>

<para>
Note that @auto_shrink doesn't do anything if @allow_shrink and @allow_grow are
both set to FALSE.
</para>

<para>
Neither of the two suggested window policies set the @allow_shrink paramter to
TRUE.  If @allow_shrink is TRUE, the user can shrink the window so that its
children do not receive their full size request; this is basically a bad thing,
because most widgets will look wrong if this happens. Furthermore GTK+ has a
tendency to re-expand the window if size is recalculated for any reason. The
upshot is that @allow_shrink should always be set to FALSE.
</para>

<para>
Sometimes when you think you want to use @allow_shrink, the real problem is that
some specific child widget is requesting too much space, so the user can't
shrink the window sufficiently. Perhaps you are calling gtk_widget_set_usize()
on a child widget, and forcing its size request to be too large. Instead of
setting the child's usize, consider using gtk_window_set_default_size() so that
the child gets a larger allocation than it requests.
</para>

@window: the window
@allow_shrink: whether the user can shrink the window below its size request
@allow_grow: whether the user can grow the window larger than its size request
@auto_shrink: whether the window automatically snaps back to its size request if
it's larger
Owen Taylor's avatar
Owen Taylor committed
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 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 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203


<!-- ##### FUNCTION gtk_window_add_accel_group ##### -->
<para>

</para>

@window: 
@accel_group: 


<!-- ##### FUNCTION gtk_window_remove_accel_group ##### -->
<para>

</para>

@window: 
@accel_group: 


<!-- ##### MACRO gtk_window_position ##### -->
<para>

</para>



<!-- ##### FUNCTION gtk_window_activate_focus ##### -->
<para>

</para>

@window: 
@Returns: 


<!-- ##### FUNCTION gtk_window_activate_default ##### -->
<para>

</para>

@window: 
@Returns: 


<!-- ##### FUNCTION gtk_window_set_modal ##### -->
<para>

</para>

@window: 
@modal: 


<!-- ##### FUNCTION gtk_window_set_default_size ##### -->
<para>

</para>

@window: 
@width: 
@height: 


<!-- ##### FUNCTION gtk_window_set_geometry_hints ##### -->
<para>

</para>

@window: 
@geometry_widget: 
@geometry: 
@geom_mask: 


204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
<!-- ##### FUNCTION gtk_window_set_gravity ##### -->
<para>

</para>

@window: 
@gravity: 


<!-- ##### FUNCTION gtk_window_get_gravity ##### -->
<para>

</para>

@window: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
<!-- ##### FUNCTION gtk_window_set_position ##### -->
<para>

</para>

@window: 
@position: 


<!-- ##### FUNCTION gtk_window_set_transient_for ##### -->
<para>

</para>

@window: 
@parent: 


240 241 242 243 244 245 246 247 248
<!-- ##### FUNCTION gtk_window_set_destroy_with_parent ##### -->
<para>

</para>

@window: 
@setting: 


249 250 251 252 253 254 255 256
<!-- ##### FUNCTION gtk_window_list_toplevels ##### -->
<para>

</para>

@Returns: 


Havoc Pennington's avatar
Havoc Pennington committed
257 258 259 260 261 262 263 264 265 266
<!-- ##### FUNCTION gtk_window_add_mnemonic ##### -->
<para>

</para>

@window: 
@keyval: 
@target: 


267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
<!-- ##### FUNCTION gtk_window_remove_mnemonic ##### -->
<para>

</para>

@window: 
@keyval: 
@target: 


<!-- ##### FUNCTION gtk_window_mnemonic_activate ##### -->
<para>

</para>

@window: 
@keyval: 
@modifier: 
@Returns: 


<!-- ##### FUNCTION gtk_window_present ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
<para>

</para>

@window: 


<!-- ##### FUNCTION gtk_window_iconify ##### -->
<para>

</para>

@window: 


304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
<!-- ##### FUNCTION gtk_window_deiconify ##### -->
<para>

</para>

@window: 


<!-- ##### FUNCTION gtk_window_stick ##### -->
<para>

</para>

@window: 


<!-- ##### FUNCTION gtk_window_unstick ##### -->
<para>

</para>

@window: 


Havoc Pennington's avatar
Havoc Pennington committed
328 329 330 331 332 333 334 335
<!-- ##### FUNCTION gtk_window_maximize ##### -->
<para>

</para>

@window: 


336
<!-- ##### FUNCTION gtk_window_unmaximize ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
337 338 339 340 341 342 343
<para>

</para>

@window: 


344
<!-- ##### FUNCTION gtk_window_begin_resize_drag ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
345 346 347 348 349
<para>

</para>

@window: 
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
@edge: 
@button: 
@root_x: 
@root_y: 
@timestamp: 


<!-- ##### FUNCTION gtk_window_begin_move_drag ##### -->
<para>

</para>

@window: 
@button: 
@root_x: 
@root_y: 
@timestamp: 
Havoc Pennington's avatar
Havoc Pennington committed
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395


<!-- ##### FUNCTION gtk_window_set_decorated ##### -->
<para>

</para>

@window: 
@setting: 


<!-- ##### FUNCTION gtk_window_set_frame_dimensions ##### -->
<para>

</para>

@window: 
@left: 
@top: 
@right: 
@bottom: 


<!-- ##### FUNCTION gtk_window_set_has_frame ##### -->
<para>

</para>

@window: 
Owen Taylor's avatar
Owen Taylor committed
396
@setting: 
Havoc Pennington's avatar
Havoc Pennington committed
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425


<!-- ##### FUNCTION gtk_window_set_mnemonic_modifier ##### -->
<para>

</para>

@window: 
@modifier: 


<!-- ##### FUNCTION gtk_window_set_role ##### -->
<para>

</para>

@window: 
@role: 


<!-- ##### FUNCTION gtk_window_set_type_hint ##### -->
<para>

</para>

@window: 
@hint: 


426
<!-- ##### FUNCTION gtk_decorated_window_init ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
427 428 429 430 431 432 433
<para>

</para>

@window: 


434
<!-- ##### FUNCTION gtk_decorated_window_calculate_frame_size ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
435 436 437 438 439 440 441
<para>

</para>

@window: 


442 443 444 445 446 447 448 449 450 451
<!-- ##### FUNCTION gtk_decorated_window_set_title ##### -->
<para>

</para>

@window: 
@title: 


<!-- ##### FUNCTION gtk_decorated_window_move_resize_window ##### -->
Havoc Pennington's avatar
Havoc Pennington committed
452 453 454 455 456
<para>

</para>

@window: 
457 458 459 460
@x: 
@y: 
@width: 
@height: 
Havoc Pennington's avatar
Havoc Pennington committed
461 462


463 464 465 466 467 468 469 470 471 472 473 474 475 476
<!-- ##### SIGNAL GtkWindow::activate-default ##### -->
<para>

</para>

@window: the object which received the signal.

<!-- ##### SIGNAL GtkWindow::activate-focus ##### -->
<para>

</para>

@window: the object which received the signal.

477 478 479 480 481 482 483 484 485
<!-- ##### SIGNAL GtkWindow::frame-event ##### -->
<para>

</para>

@window: the object which received the signal.
@event: 
@Returns: 

486 487 488 489 490 491 492 493
<!-- ##### SIGNAL GtkWindow::move-focus ##### -->
<para>

</para>

@window: the object which received the signal.
@arg1: 

Owen Taylor's avatar
Owen Taylor committed
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511
<!-- ##### SIGNAL GtkWindow::set-focus ##### -->
<para>

</para>

@window: the object which received the signal.
@widget: 

<!-- ##### ARG GtkWindow:type ##### -->
<para>
The type of the window.
</para>

<!-- ##### ARG GtkWindow:title ##### -->
<para>
The title of the window.
</para>

Owen Taylor's avatar
Owen Taylor committed
512
<!-- ##### ARG GtkWindow:auto-shrink ##### -->
Owen Taylor's avatar
Owen Taylor committed
513 514 515 516
<para>
If the window shrinks automatically when widgets within it shrink.
</para>

Owen Taylor's avatar
Owen Taylor committed
517
<!-- ##### ARG GtkWindow:allow-shrink ##### -->
Owen Taylor's avatar
Owen Taylor committed
518 519 520 521
<para>
If the window can be resized to a smaller size by the user.
</para>

Owen Taylor's avatar
Owen Taylor committed
522
<!-- ##### ARG GtkWindow:allow-grow ##### -->
Owen Taylor's avatar
Owen Taylor committed
523 524 525 526 527 528 529 530 531
<para>
If the window can be resized to a larger size by the user.
</para>

<!-- ##### ARG GtkWindow:modal ##### -->
<para>
If the window is modal, i.e. it grabs all GTK+ events.
</para>

Owen Taylor's avatar
Owen Taylor committed
532
<!-- ##### ARG GtkWindow:window-position ##### -->
Owen Taylor's avatar
Owen Taylor committed
533 534 535 536
<para>
The position of the window.
</para>

Owen Taylor's avatar
Owen Taylor committed
537
<!-- ##### ARG GtkWindow:default-width ##### -->
538 539 540 541
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
542
<!-- ##### ARG GtkWindow:default-height ##### -->
543 544 545 546
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
547
<!-- ##### ARG GtkWindow:destroy-with-parent ##### -->
548 549 550 551
<para>

</para>