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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkWindow
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Toplevel which can contain other widgets
   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 <literal>
  77  void gtk_window_set_resizable (GtkWindow* window, gboolean setting);
  78 </literal>
  79 ...which is why GTK+ 2.0 introduces gtk_window_set_resizable(), which you
  80 should use instead of gtk_window_set_policy().
  81 </para>
  82
  83 <para>
  84 If set to %TRUE, the @allow_grow parameter allows the user to expand the window
  85 beyond the size request of its child widgets. If @allow_grow is %TRUE, be sure to
  86 check that your child widgets work properly as the window is resized.
  87 </para>
  88
  89 <para>
  90 A toplevel window will always change size to ensure its child widgets receive
  91 their requested size. This means that if you add child widgets, the toplevel
  92 window will expand to contain them. However, normally the toplevel will not
  93 shrink to fit the size request of its children if it's too large; the
  94 @auto_shrink parameter causes the window to shrink when child widgets have too
  95 much space. @auto_shrink is normally used with the second of the two window
  96 policies mentioned above.  That is, set @auto_shrink to %TRUE if you want the
  97 window to have a fixed, always-optimal size determined by your program.
  98 </para>
  99
 100 <para>
 101 Note that @auto_shrink doesn't do anything if @allow_shrink and @allow_grow are
 102 both set to %FALSE.
 103 </para>
 104
 105 <para>
 106 Neither of the two suggested window policies set the @allow_shrink parameter to
 107 %TRUE.  If @allow_shrink is %TRUE, the user can shrink the window so that its
 108 children do not receive their full size request; this is basically a bad thing,
 109 because most widgets will look wrong if this happens. Furthermore GTK+ has a
 110 tendency to re-expand the window if size is recalculated for any reason. The
 111 upshot is that @allow_shrink should always be set to %FALSE.
 112 </para>
 113
 114 <para>
 115 Sometimes when you think you want to use @allow_shrink, the real problem is that
 116 some specific child widget is requesting too much space, so the user can't
 117 shrink the window sufficiently. Perhaps you are calling gtk_widget_set_size_request()
 118 on a child widget, and forcing its size request to be too large. Instead of
 119 setting the child's usize, consider using gtk_window_set_default_size() so that
 120 the child gets a larger allocation than it requests.
 121 </para>
 122
 123 @window: the window
 124 @allow_shrink: whether the user can shrink the window below its size request
 125 @allow_grow: whether the user can grow the window larger than its size request
 126 @auto_shrink: whether the window automatically snaps back to its size request
 127               if it's larger
 128 @Deprecated: Use gtk_window_set_resizable() instead.
 129
 130
 131 <!-- ##### FUNCTION gtk_window_set_resizable ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @window:
 137 @resizable:
 138
 139
 140 <!-- ##### FUNCTION gtk_window_get_resizable ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @window:
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION gtk_window_add_accel_group ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @window:
 155 @accel_group:
 156
 157
 158 <!-- ##### FUNCTION gtk_window_remove_accel_group ##### -->
 159 <para>
 160
 161 </para>
 162
 163 @window:
 164 @accel_group:
 165
 166
 167 <!-- ##### MACRO gtk_window_position ##### -->
 168 <para>
 169 Deprecated alias for gtk_window_set_position().
 170 </para>
 171
 172
 173
 174 <!-- ##### FUNCTION gtk_window_activate_focus ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @window:
 180 @Returns:
 181
 182
 183 <!-- ##### FUNCTION gtk_window_activate_default ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @window:
 189 @Returns:
 190
 191
 192 <!-- ##### FUNCTION gtk_window_set_modal ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @window:
 198 @modal:
 199
 200
 201 <!-- ##### FUNCTION gtk_window_set_default_size ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @window:
 207 @width:
 208 @height:
 209
 210
 211 <!-- ##### FUNCTION gtk_window_set_geometry_hints ##### -->
 212 <para>
 213
 214 </para>
 215
 216 @window:
 217 @geometry_widget:
 218 @geometry:
 219 @geom_mask:
 220
 221
 222 <!-- ##### FUNCTION gtk_window_set_gravity ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @window:
 228 @gravity:
 229
 230
 231 <!-- ##### FUNCTION gtk_window_get_gravity ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @window:
 237 @Returns:
 238
 239
 240 <!-- ##### FUNCTION gtk_window_set_position ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @window:
 246 @position:
 247
 248
 249 <!-- ##### FUNCTION gtk_window_set_transient_for ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @window:
 255 @parent:
 256
 257
 258 <!-- ##### FUNCTION gtk_window_set_destroy_with_parent ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @window:
 264 @setting:
 265
 266
 267 <!-- ##### FUNCTION gtk_window_set_screen ##### -->
 268 <para>
 269
 270 </para>
 271
 272 @window:
 273 @screen:
 274
 275
 276 <!-- ##### FUNCTION gtk_window_get_screen ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @window:
 282 @Returns:
 283
 284
 285 <!-- ##### FUNCTION gtk_window_list_toplevels ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION gtk_window_add_mnemonic ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @window:
 299 @keyval:
 300 @target:
 301
 302
 303 <!-- ##### FUNCTION gtk_window_remove_mnemonic ##### -->
 304 <para>
 305
 306 </para>
 307
 308 @window:
 309 @keyval:
 310 @target:
 311
 312
 313 <!-- ##### FUNCTION gtk_window_mnemonic_activate ##### -->
 314 <para>
 315
 316 </para>
 317
 318 @window:
 319 @keyval:
 320 @modifier:
 321 @Returns:
 322
 323
 324 <!-- ##### FUNCTION gtk_window_get_focus ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @window:
 330 @Returns:
 331
 332
 333 <!-- ##### FUNCTION gtk_window_set_focus ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @window:
 339 @focus:
 340
 341
 342 <!-- ##### FUNCTION gtk_window_set_default ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @window:
 348 @default_widget:
 349
 350
 351 <!-- ##### FUNCTION gtk_window_present ##### -->
 352 <para>
 353
 354 </para>
 355
 356 @window:
 357
 358
 359 <!-- ##### FUNCTION gtk_window_iconify ##### -->
 360 <para>
 361
 362 </para>
 363
 364 @window:
 365
 366
 367 <!-- ##### FUNCTION gtk_window_deiconify ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @window:
 373
 374
 375 <!-- ##### FUNCTION gtk_window_stick ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @window:
 381
 382
 383 <!-- ##### FUNCTION gtk_window_unstick ##### -->
 384 <para>
 385
 386 </para>
 387
 388 @window:
 389
 390
 391 <!-- ##### FUNCTION gtk_window_maximize ##### -->
 392 <para>
 393
 394 </para>
 395
 396 @window:
 397
 398
 399 <!-- ##### FUNCTION gtk_window_unmaximize ##### -->
 400 <para>
 401
 402 </para>
 403
 404 @window:
 405
 406
 407 <!-- ##### FUNCTION gtk_window_fullscreen ##### -->
 408 <para>
 409
 410 </para>
 411
 412 @window:
 413
 414
 415 <!-- ##### FUNCTION gtk_window_unfullscreen ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @window:
 421
 422
 423 <!-- ##### FUNCTION gtk_window_set_keep_above ##### -->
 424 <para>
 425
 426 </para>
 427
 428 @window:
 429 @setting:
 430
 431
 432 <!-- ##### FUNCTION gtk_window_set_keep_below ##### -->
 433 <para>
 434
 435 </para>
 436
 437 @window:
 438 @setting:
 439
 440
 441 <!-- ##### FUNCTION gtk_window_begin_resize_drag ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @window:
 447 @edge:
 448 @button:
 449 @root_x:
 450 @root_y:
 451 @timestamp:
 452
 453
 454 <!-- ##### FUNCTION gtk_window_begin_move_drag ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @window:
 460 @button:
 461 @root_x:
 462 @root_y:
 463 @timestamp:
 464
 465
 466 <!-- ##### FUNCTION gtk_window_set_decorated ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @window:
 472 @setting:
 473
 474
 475 <!-- ##### FUNCTION gtk_window_set_frame_dimensions ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @window:
 481 @left:
 482 @top:
 483 @right:
 484 @bottom:
 485
 486
 487 <!-- ##### FUNCTION gtk_window_set_has_frame ##### -->
 488 <para>
 489
 490 </para>
 491
 492 @window:
 493 @setting:
 494
 495
 496 <!-- ##### FUNCTION gtk_window_set_mnemonic_modifier ##### -->
 497 <para>
 498
 499 </para>
 500
 501 @window:
 502 @modifier:
 503
 504
 505 <!-- ##### FUNCTION gtk_window_set_role ##### -->
 506 <para>
 507
 508 </para>
 509
 510 @window:
 511 @role:
 512
 513
 514 <!-- ##### FUNCTION gtk_window_set_type_hint ##### -->
 515 <para>
 516
 517 </para>
 518
 519 @window:
 520 @hint:
 521
 522
 523 <!-- ##### FUNCTION gtk_window_set_skip_taskbar_hint ##### -->
 524 <para>
 525
 526 </para>
 527
 528 @window:
 529 @setting:
 530
 531
 532 <!-- ##### FUNCTION gtk_window_set_skip_pager_hint ##### -->
 533 <para>
 534
 535 </para>
 536
 537 @window:
 538 @setting:
 539
 540
 541 <!-- ##### FUNCTION gtk_window_get_decorated ##### -->
 542 <para>
 543
 544 </para>
 545
 546 @window:
 547 @Returns:
 548
 549
 550 <!-- ##### FUNCTION gtk_window_get_default_icon_list ##### -->
 551 <para>
 552
 553 </para>
 554
 555 @Returns:
 556
 557
 558 <!-- ##### FUNCTION gtk_window_get_default_size ##### -->
 559 <para>
 560
 561 </para>
 562
 563 @window:
 564 @width:
 565 @height:
 566
 567
 568 <!-- ##### FUNCTION gtk_window_get_destroy_with_parent ##### -->
 569 <para>
 570
 571 </para>
 572
 573 @window:
 574 @Returns:
 575
 576
 577 <!-- ##### FUNCTION gtk_window_get_frame_dimensions ##### -->
 578 <para>
 579
 580 </para>
 581
 582 @window:
 583 @left:
 584 @top:
 585 @right:
 586 @bottom:
 587
 588
 589 <!-- ##### FUNCTION gtk_window_get_has_frame ##### -->
 590 <para>
 591
 592 </para>
 593
 594 @window:
 595 @Returns:
 596
 597
 598 <!-- ##### FUNCTION gtk_window_get_icon ##### -->
 599 <para>
 600
 601 </para>
 602
 603 @window:
 604 @Returns:
 605
 606
 607 <!-- ##### FUNCTION gtk_window_get_icon_list ##### -->
 608 <para>
 609
 610 </para>
 611
 612 @window:
 613 @Returns:
 614
 615
 616 <!-- ##### FUNCTION gtk_window_get_mnemonic_modifier ##### -->
 617 <para>
 618
 619 </para>
 620
 621 @window:
 622 @Returns:
 623
 624
 625 <!-- ##### FUNCTION gtk_window_get_modal ##### -->
 626 <para>
 627
 628 </para>
 629
 630 @window:
 631 @Returns:
 632
 633
 634 <!-- ##### FUNCTION gtk_window_get_position ##### -->
 635 <para>
 636
 637 </para>
 638
 639 @window:
 640 @root_x:
 641 @root_y:
 642 <!-- # Unused Parameters # -->
 643 @x:
 644 @y:
 645
 646
 647 <!-- ##### FUNCTION gtk_window_get_role ##### -->
 648 <para>
 649
 650 </para>
 651
 652 @window:
 653 @Returns:
 654
 655
 656 <!-- ##### FUNCTION gtk_window_get_size ##### -->
 657 <para>
 658
 659 </para>
 660
 661 @window:
 662 @width:
 663 @height:
 664
 665
 666 <!-- ##### FUNCTION gtk_window_get_title ##### -->
 667 <para>
 668
 669 </para>
 670
 671 @window:
 672 @Returns:
 673
 674
 675 <!-- ##### FUNCTION gtk_window_get_transient_for ##### -->
 676 <para>
 677
 678 </para>
 679
 680 @window:
 681 @Returns:
 682
 683
 684 <!-- ##### FUNCTION gtk_window_get_type_hint ##### -->
 685 <para>
 686
 687 </para>
 688
 689 @window:
 690 @Returns:
 691
 692
 693 <!-- ##### FUNCTION gtk_window_get_skip_taskbar_hint ##### -->
 694 <para>
 695
 696 </para>
 697
 698 @window:
 699 @Returns:
 700
 701
 702 <!-- ##### FUNCTION gtk_window_get_skip_pager_hint ##### -->
 703 <para>
 704
 705 </para>
 706
 707 @window:
 708 @Returns:
 709
 710
 711 <!-- ##### FUNCTION gtk_window_move ##### -->
 712 <para>
 713
 714 </para>
 715
 716 @window:
 717 @x:
 718 @y:
 719
 720
 721 <!-- ##### FUNCTION gtk_window_parse_geometry ##### -->
 722 <para>
 723
 724 </para>
 725
 726 @window:
 727 @geometry:
 728 @Returns:
 729
 730
 731 <!-- ##### FUNCTION gtk_window_reshow_with_initial_size ##### -->
 732 <para>
 733
 734 </para>
 735
 736 @window:
 737
 738
 739 <!-- ##### FUNCTION gtk_window_resize ##### -->
 740 <para>
 741
 742 </para>
 743
 744 @window:
 745 @width:
 746 @height:
 747
 748
 749 <!-- ##### FUNCTION gtk_window_set_default_icon_list ##### -->
 750 <para>
 751
 752 </para>
 753
 754 @list:
 755
 756
 757 <!-- ##### FUNCTION gtk_window_set_default_icon ##### -->
 758 <para>
 759
 760 </para>
 761
 762 @icon:
 763 <!-- # Unused Parameters # -->
 764 @pixbuf:
 765
 766
 767 <!-- ##### FUNCTION gtk_window_set_default_icon_from_file ##### -->
 768 <para>
 769
 770 </para>
 771
 772 @filename:
 773 @err:
 774 @Returns:
 775
 776
 777 <!-- ##### FUNCTION gtk_window_set_icon ##### -->
 778 <para>
 779
 780 </para>
 781
 782 @window:
 783 @icon:
 784
 785
 786 <!-- ##### FUNCTION gtk_window_set_icon_list ##### -->
 787 <para>
 788
 789 </para>
 790
 791 @window:
 792 @list:
 793
 794
 795 <!-- ##### FUNCTION gtk_window_set_icon_from_file ##### -->
 796 <para>
 797
 798 </para>
 799
 800 @window:
 801 @filename:
 802 @err:
 803 @Returns:
 804
 805
 806 <!-- ##### FUNCTION gtk_window_set_auto_startup_notification ##### -->
 807 <para>
 808
 809 </para>
 810
 811 @setting:
 812
 813
 814 <!-- ##### FUNCTION gtk_decorated_window_init ##### -->
 815 <para>
 816
 817 </para>
 818
 819 @window:
 820
 821
 822 <!-- ##### FUNCTION gtk_decorated_window_calculate_frame_size ##### -->
 823 <para>
 824
 825 </para>
 826
 827 @window:
 828
 829
 830 <!-- ##### FUNCTION gtk_decorated_window_set_title ##### -->
 831 <para>
 832
 833 </para>
 834
 835 @window:
 836 @title:
 837
 838
 839 <!-- ##### FUNCTION gtk_decorated_window_move_resize_window ##### -->
 840 <para>
 841
 842 </para>
 843
 844 @window:
 845 @x:
 846 @y:
 847 @width:
 848 @height:
 849
 850
 851 <!-- ##### SIGNAL GtkWindow::activate-default ##### -->
 852 <para>
 853
 854 </para>
 855
 856 @window: the object which received the signal.
 857
 858 <!-- ##### SIGNAL GtkWindow::activate-focus ##### -->
 859 <para>
 860
 861 </para>
 862
 863 @window: the object which received the signal.
 864
 865 <!-- ##### SIGNAL GtkWindow::frame-event ##### -->
 866 <para>
 867
 868 </para>
 869
 870 @window: the object which received the signal.
 871 @event:
 872 @Returns:
 873
 874 <!-- ##### SIGNAL GtkWindow::keys-changed ##### -->
 875 <para>
 876
 877 </para>
 878
 879 @window: the object which received the signal.
 880
 881 <!-- ##### SIGNAL GtkWindow::move-focus ##### -->
 882 <para>
 883
 884 </para>
 885
 886 @window: the object which received the signal.
 887 @arg1:
 888
 889 <!-- ##### SIGNAL GtkWindow::set-focus ##### -->
 890 <para>
 891
 892 </para>
 893
 894 @window: the object which received the signal.
 895 @widget:
 896
 897 <!-- ##### ARG GtkWindow:allow-grow ##### -->
 898 <para>
 899
 900 </para>
 901
 902 <!-- ##### ARG GtkWindow:allow-shrink ##### -->
 903 <para>
 904
 905 </para>
 906
 907 <!-- ##### ARG GtkWindow:decorated ##### -->
 908 <para>
 909
 910 </para>
 911
 912 <!-- ##### ARG GtkWindow:default-height ##### -->
 913 <para>
 914
 915 </para>
 916
 917 <!-- ##### ARG GtkWindow:default-width ##### -->
 918 <para>
 919
 920 </para>
 921
 922 <!-- ##### ARG GtkWindow:destroy-with-parent ##### -->
 923 <para>
 924
 925 </para>
 926
 927 <!-- ##### ARG GtkWindow:gravity ##### -->
 928 <para>
 929
 930 </para>
 931
 932 <!-- ##### ARG GtkWindow:has-toplevel-focus ##### -->
 933 <para>
 934
 935 </para>
 936
 937 <!-- ##### ARG GtkWindow:icon ##### -->
 938 <para>
 939
 940 </para>
 941
 942 <!-- ##### ARG GtkWindow:is-active ##### -->
 943 <para>
 944
 945 </para>
 946
 947 <!-- ##### ARG GtkWindow:modal ##### -->
 948 <para>
 949
 950 </para>
 951
 952 <!-- ##### ARG GtkWindow:resizable ##### -->
 953 <para>
 954
 955 </para>
 956
 957 <!-- ##### ARG GtkWindow:role ##### -->
 958 <para>
 959
 960 </para>
 961
 962 <!-- ##### ARG GtkWindow:screen ##### -->
 963 <para>
 964
 965 </para>
 966
 967 <!-- ##### ARG GtkWindow:skip-pager-hint ##### -->
 968 <para>
 969
 970 </para>
 971
 972 <!-- ##### ARG GtkWindow:skip-taskbar-hint ##### -->
 973 <para>
 974
 975 </para>
 976
 977 <!-- ##### ARG GtkWindow:title ##### -->
 978 <para>
 979
 980 </para>
 981
 982 <!-- ##### ARG GtkWindow:type ##### -->
 983 <para>
 984
 985 </para>
 986
 987 <!-- ##### ARG GtkWindow:type-hint ##### -->
 988 <para>
 989
 990 </para>
 991
 992 <!-- ##### ARG GtkWindow:window-position ##### -->
 993 <para>
 994
 995 </para>
 996