Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkwindow.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkWindow
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### STRUCT GtkWindow ##### -->
  18 <para>
  19
  20 </para>
  21
  22
  23 <!-- ##### FUNCTION gtk_window_new ##### -->
  24 <para>
  25
  26 </para>
  27
  28 @type:
  29 @Returns:
  30
  31
  32 <!-- ##### FUNCTION gtk_window_set_title ##### -->
  33 <para>
  34
  35 </para>
  36
  37 @window:
  38 @title:
  39
  40
  41 <!-- ##### FUNCTION gtk_window_set_wmclass ##### -->
  42 <para>
  43
  44 </para>
  45
  46 @window:
  47 @wmclass_name:
  48 @wmclass_class:
  49
  50
  51 <!-- ##### FUNCTION gtk_window_set_policy ##### -->
  52 <para>
  53 Changes how a toplevel window deals with its size request and user resize
  54 attempts. There are really only two reasonable ways to call this function:
  55 <orderedlist>
  56 <listitem>
  57 <para>
  58 <literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, TRUE, FALSE)</literal>
  59 means that the window is user-resizable.
  60 </para>
  61 </listitem>
  62 <listitem>
  63 <para>
  64 <literal>gtk_window_set_policy(GTK_WINDOW(window), FALSE, FALSE, TRUE)</literal>
  65 means that the window's size is program-controlled, and should simply match
  66 the current size request of the window's children.
  67 </para>
  68 </listitem>
  69 </orderedlist>
  70 The first policy is the default, that is, by default windows are designed to
  71 be resized by users.
  72 </para>
  73
  74 <para>
  75 The basic ugly truth of this function is that it should be simply:
  76 <programlisting>
  77  void gtk_window_set_user_resizeable(GtkWidget* window, gboolean setting);
  78 </programlisting>
  79 So, pretend it is like that, and only use the two policies mentioned above.
  80 GTK+ 1.4 may replace gtk_window_set_policy() with a nicer function like
  81 gtk_window_set_user_resizeable().
  82 </para>
  83
  84 <para>
  85 If set to TRUE, the @allow_grow parameter allows the user to expand the window
  86 beyond the size request of its child widgets. If @allow_grow is TRUE, be sure to
  87 check that your child widgets work properly as the window is resized.
  88 </para>
  89
  90 <para>
  91 A toplevel window will always change size to ensure its child widgets receive
  92 their requested size. This means that if you add child widgets, the toplevel
  93 window will expand to contain them. However, normally the toplevel will not
  94 shrink to fit the size request of its children if it's too large; the
  95 @auto_shrink parameter causes the window to shrink when child widgets have too
  96 much space. @auto_shrink is normally used with the second of the two window
  97 policies mentioned above.  That is, set @auto_shrink to TRUE if you want the
  98 window to have a fixed, always-optimal size determined by your program.
  99 </para>
 100
 101 <para>
 102 Note that @auto_shrink doesn't do anything if @allow_shrink and @allow_grow are
 103 both set to FALSE.
 104 </para>
 105
 106 <para>
 107 Neither of the two suggested window policies set the @allow_shrink paramter to
 108 TRUE.  If @allow_shrink is TRUE, the user can shrink the window so that its
 109 children do not receive their full size request; this is basically a bad thing,
 110 because most widgets will look wrong if this happens. Furthermore GTK+ has a
 111 tendency to re-expand the window if size is recalculated for any reason. The
 112 upshot is that @allow_shrink should always be set to FALSE.
 113 </para>
 114
 115 <para>
 116 Sometimes when you think you want to use @allow_shrink, the real problem is that
 117 some specific child widget is requesting too much space, so the user can't
 118 shrink the window sufficiently. Perhaps you are calling gtk_widget_set_usize()
 119 on a child widget, and forcing its size request to be too large. Instead of
 120 setting the child's usize, consider using gtk_window_set_default_size() so that
 121 the child gets a larger allocation than it requests.
 122 </para>
 123
 124 @window: the window
 125 @allow_shrink: whether the user can shrink the window below its size request
 126 @allow_grow: whether the user can grow the window larger than its size request
 127 @auto_shrink: whether the window automatically snaps back to its size request if
 128 it's larger
 129
 130
 131 <!-- ##### FUNCTION gtk_window_set_resizeable ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @window:
 137 @setting:
 138 <!-- # Unused Parameters # -->
 139 @resizeable:
 140
 141
 142 <!-- ##### FUNCTION gtk_window_get_resizeable ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @window:
 148 @Returns:
 149
 150
 151 <!-- ##### FUNCTION gtk_window_add_accel_group ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @window:
 157 @accel_group:
 158
 159
 160 <!-- ##### FUNCTION gtk_window_remove_accel_group ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @window:
 166 @accel_group:
 167
 168
 169 <!-- ##### MACRO gtk_window_position ##### -->
 170 <para>
 171
 172 </para>
 173
 174
 175
 176 <!-- ##### FUNCTION gtk_window_activate_focus ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @window:
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION gtk_window_activate_default ##### -->
 186 <para>
 187
 188 </para>
 189
 190 @window:
 191 @Returns:
 192
 193
 194 <!-- ##### FUNCTION gtk_window_set_modal ##### -->
 195 <para>
 196
 197 </para>
 198
 199 @window:
 200 @modal:
 201
 202
 203 <!-- ##### FUNCTION gtk_window_set_default_size ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @window:
 209 @width:
 210 @height:
 211
 212
 213 <!-- ##### FUNCTION gtk_window_set_geometry_hints ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @window:
 219 @geometry_widget:
 220 @geometry:
 221 @geom_mask:
 222
 223
 224 <!-- ##### FUNCTION gtk_window_set_gravity ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @window:
 230 @gravity:
 231
 232
 233 <!-- ##### FUNCTION gtk_window_get_gravity ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @window:
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION gtk_window_set_position ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @window:
 248 @position:
 249
 250
 251 <!-- ##### FUNCTION gtk_window_set_transient_for ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @window:
 257 @parent:
 258
 259
 260 <!-- ##### FUNCTION gtk_window_set_destroy_with_parent ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @window:
 266 @setting:
 267
 268
 269 <!-- ##### FUNCTION gtk_window_list_toplevels ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @Returns:
 275
 276
 277 <!-- ##### FUNCTION gtk_window_add_mnemonic ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @window:
 283 @keyval:
 284 @target:
 285
 286
 287 <!-- ##### FUNCTION gtk_window_remove_mnemonic ##### -->
 288 <para>
 289
 290 </para>
 291
 292 @window:
 293 @keyval:
 294 @target:
 295
 296
 297 <!-- ##### FUNCTION gtk_window_mnemonic_activate ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @window:
 303 @keyval:
 304 @modifier:
 305 @Returns:
 306
 307
 308 <!-- ##### FUNCTION gtk_window_present ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @window:
 314
 315
 316 <!-- ##### FUNCTION gtk_window_iconify ##### -->
 317 <para>
 318
 319 </para>
 320
 321 @window:
 322
 323
 324 <!-- ##### FUNCTION gtk_window_deiconify ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @window:
 330
 331
 332 <!-- ##### FUNCTION gtk_window_stick ##### -->
 333 <para>
 334
 335 </para>
 336
 337 @window:
 338
 339
 340 <!-- ##### FUNCTION gtk_window_unstick ##### -->
 341 <para>
 342
 343 </para>
 344
 345 @window:
 346
 347
 348 <!-- ##### FUNCTION gtk_window_maximize ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @window:
 354
 355
 356 <!-- ##### FUNCTION gtk_window_unmaximize ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @window:
 362
 363
 364 <!-- ##### FUNCTION gtk_window_begin_resize_drag ##### -->
 365 <para>
 366
 367 </para>
 368
 369 @window:
 370 @edge:
 371 @button:
 372 @root_x:
 373 @root_y:
 374 @timestamp:
 375
 376
 377 <!-- ##### FUNCTION gtk_window_begin_move_drag ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @window:
 383 @button:
 384 @root_x:
 385 @root_y:
 386 @timestamp:
 387
 388
 389 <!-- ##### FUNCTION gtk_window_set_decorated ##### -->
 390 <para>
 391
 392 </para>
 393
 394 @window:
 395 @setting:
 396
 397
 398 <!-- ##### FUNCTION gtk_window_set_frame_dimensions ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @window:
 404 @left:
 405 @top:
 406 @right:
 407 @bottom:
 408
 409
 410 <!-- ##### FUNCTION gtk_window_set_has_frame ##### -->
 411 <para>
 412
 413 </para>
 414
 415 @window:
 416 @setting:
 417
 418
 419 <!-- ##### FUNCTION gtk_window_set_mnemonic_modifier ##### -->
 420 <para>
 421
 422 </para>
 423
 424 @window:
 425 @modifier:
 426
 427
 428 <!-- ##### FUNCTION gtk_window_set_role ##### -->
 429 <para>
 430
 431 </para>
 432
 433 @window:
 434 @role:
 435
 436
 437 <!-- ##### FUNCTION gtk_window_set_type_hint ##### -->
 438 <para>
 439
 440 </para>
 441
 442 @window:
 443 @hint:
 444
 445
 446 <!-- ##### FUNCTION gtk_decorated_window_init ##### -->
 447 <para>
 448
 449 </para>
 450
 451 @window:
 452
 453
 454 <!-- ##### FUNCTION gtk_decorated_window_calculate_frame_size ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @window:
 460
 461
 462 <!-- ##### FUNCTION gtk_decorated_window_set_title ##### -->
 463 <para>
 464
 465 </para>
 466
 467 @window:
 468 @title:
 469
 470
 471 <!-- ##### FUNCTION gtk_decorated_window_move_resize_window ##### -->
 472 <para>
 473
 474 </para>
 475
 476 @window:
 477 @x:
 478 @y:
 479 @width:
 480 @height:
 481
 482
 483 <!-- ##### SIGNAL GtkWindow::activate-default ##### -->
 484 <para>
 485
 486 </para>
 487
 488 @window: the object which received the signal.
 489
 490 <!-- ##### SIGNAL GtkWindow::activate-focus ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @window: the object which received the signal.
 496
 497 <!-- ##### SIGNAL GtkWindow::frame-event ##### -->
 498 <para>
 499
 500 </para>
 501
 502 @window: the object which received the signal.
 503 @event:
 504 @Returns:
 505
 506 <!-- ##### SIGNAL GtkWindow::move-focus ##### -->
 507 <para>
 508
 509 </para>
 510
 511 @window: the object which received the signal.
 512 @arg1:
 513
 514 <!-- ##### SIGNAL GtkWindow::set-focus ##### -->
 515 <para>
 516
 517 </para>
 518
 519 @window: the object which received the signal.
 520 @widget:
 521
 522 <!-- ##### ARG GtkWindow:type ##### -->
 523 <para>
 524 The type of the window.
 525 </para>
 526
 527 <!-- ##### ARG GtkWindow:title ##### -->
 528 <para>
 529 The title of the window.
 530 </para>
 531
 532 <!-- ##### ARG GtkWindow:allow-shrink ##### -->
 533 <para>
 534 If the window can be resized to a smaller size by the user.
 535 </para>
 536
 537 <!-- ##### ARG GtkWindow:allow-grow ##### -->
 538 <para>
 539 If the window can be resized to a larger size by the user.
 540 </para>
 541
 542 <!-- ##### ARG GtkWindow:resizable ##### -->
 543 <para>
 544
 545 </para>
 546
 547 <!-- ##### ARG GtkWindow:modal ##### -->
 548 <para>
 549 If the window is modal, i.e. it grabs all GTK+ events.
 550 </para>
 551
 552 <!-- ##### ARG GtkWindow:window-position ##### -->
 553 <para>
 554 The position of the window.
 555 </para>
 556
 557 <!-- ##### ARG GtkWindow:default-width ##### -->
 558 <para>
 559
 560 </para>
 561
 562 <!-- ##### ARG GtkWindow:default-height ##### -->
 563 <para>
 564
 565 </para>
 566
 567 <!-- ##### ARG GtkWindow:destroy-with-parent ##### -->
 568 <para>
 569
 570 </para>
 571
 572 <!-- ##### ARG GtkWindow:icon ##### -->
 573 <para>
 574
 575 </para>
 576