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