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_activate_key ##### -->
 494 <para>
 495
 496 </para>
 497
 498 @window:
 499 @event:
 500 @Returns:
 501
 502
 503 <!-- ##### FUNCTION gtk_window_get_focus ##### -->
 504 <para>
 505
 506 </para>
 507
 508 @window:
 509 @Returns:
 510
 511
 512 <!-- ##### FUNCTION gtk_window_set_focus ##### -->
 513 <para>
 514
 515 </para>
 516
 517 @window:
 518 @focus:
 519
 520
 521 <!-- ##### FUNCTION gtk_window_set_default ##### -->
 522 <para>
 523
 524 </para>
 525
 526 @window:
 527 @default_widget:
 528
 529
 530 <!-- ##### FUNCTION gtk_window_present ##### -->
 531 <para>
 532
 533 </para>
 534
 535 @window:
 536
 537
 538 <!-- ##### FUNCTION gtk_window_iconify ##### -->
 539 <para>
 540
 541 </para>
 542
 543 @window:
 544
 545
 546 <!-- ##### FUNCTION gtk_window_deiconify ##### -->
 547 <para>
 548
 549 </para>
 550
 551 @window:
 552
 553
 554 <!-- ##### FUNCTION gtk_window_stick ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @window:
 560
 561
 562 <!-- ##### FUNCTION gtk_window_unstick ##### -->
 563 <para>
 564
 565 </para>
 566
 567 @window:
 568
 569
 570 <!-- ##### FUNCTION gtk_window_maximize ##### -->
 571 <para>
 572
 573 </para>
 574
 575 @window:
 576
 577
 578 <!-- ##### FUNCTION gtk_window_unmaximize ##### -->
 579 <para>
 580
 581 </para>
 582
 583 @window:
 584
 585
 586 <!-- ##### FUNCTION gtk_window_fullscreen ##### -->
 587 <para>
 588
 589 </para>
 590
 591 @window:
 592
 593
 594 <!-- ##### FUNCTION gtk_window_unfullscreen ##### -->
 595 <para>
 596
 597 </para>
 598
 599 @window:
 600
 601
 602 <!-- ##### FUNCTION gtk_window_set_keep_above ##### -->
 603 <para>
 604
 605 </para>
 606
 607 @window:
 608 @setting:
 609
 610
 611 <!-- ##### FUNCTION gtk_window_set_keep_below ##### -->
 612 <para>
 613
 614 </para>
 615
 616 @window:
 617 @setting:
 618
 619
 620 <!-- ##### FUNCTION gtk_window_begin_resize_drag ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @window:
 626 @edge:
 627 @button:
 628 @root_x:
 629 @root_y:
 630 @timestamp:
 631
 632
 633 <!-- ##### FUNCTION gtk_window_begin_move_drag ##### -->
 634 <para>
 635
 636 </para>
 637
 638 @window:
 639 @button:
 640 @root_x:
 641 @root_y:
 642 @timestamp:
 643
 644
 645 <!-- ##### FUNCTION gtk_window_set_decorated ##### -->
 646 <para>
 647
 648 </para>
 649
 650 @window:
 651 @setting:
 652
 653
 654 <!-- ##### FUNCTION gtk_window_set_frame_dimensions ##### -->
 655 <para>
 656
 657 </para>
 658
 659 @window:
 660 @left:
 661 @top:
 662 @right:
 663 @bottom:
 664
 665
 666 <!-- ##### FUNCTION gtk_window_set_has_frame ##### -->
 667 <para>
 668
 669 </para>
 670
 671 @window:
 672 @setting:
 673
 674
 675 <!-- ##### FUNCTION gtk_window_set_mnemonic_modifier ##### -->
 676 <para>
 677
 678 </para>
 679
 680 @window:
 681 @modifier:
 682
 683
 684 <!-- ##### FUNCTION gtk_window_set_role ##### -->
 685 <para>
 686
 687 </para>
 688
 689 @window:
 690 @role:
 691
 692
 693 <!-- ##### FUNCTION gtk_window_set_type_hint ##### -->
 694 <para>
 695
 696 </para>
 697
 698 @window:
 699 @hint:
 700
 701
 702 <!-- ##### FUNCTION gtk_window_set_skip_taskbar_hint ##### -->
 703 <para>
 704
 705 </para>
 706
 707 @window:
 708 @setting:
 709
 710
 711 <!-- ##### FUNCTION gtk_window_set_skip_pager_hint ##### -->
 712 <para>
 713
 714 </para>
 715
 716 @window:
 717 @setting:
 718
 719
 720 <!-- ##### FUNCTION gtk_window_set_accept_focus ##### -->
 721 <para>
 722
 723 </para>
 724
 725 @window:
 726 @setting:
 727
 728
 729 <!-- ##### FUNCTION gtk_window_get_decorated ##### -->
 730 <para>
 731
 732 </para>
 733
 734 @window:
 735 @Returns:
 736
 737
 738 <!-- ##### FUNCTION gtk_window_get_default_icon_list ##### -->
 739 <para>
 740
 741 </para>
 742
 743 @Returns:
 744
 745
 746 <!-- ##### FUNCTION gtk_window_get_default_size ##### -->
 747 <para>
 748
 749 </para>
 750
 751 @window:
 752 @width:
 753 @height:
 754
 755
 756 <!-- ##### FUNCTION gtk_window_get_destroy_with_parent ##### -->
 757 <para>
 758
 759 </para>
 760
 761 @window:
 762 @Returns:
 763
 764
 765 <!-- ##### FUNCTION gtk_window_get_frame_dimensions ##### -->
 766 <para>
 767
 768 </para>
 769
 770 @window:
 771 @left:
 772 @top:
 773 @right:
 774 @bottom:
 775
 776
 777 <!-- ##### FUNCTION gtk_window_get_has_frame ##### -->
 778 <para>
 779
 780 </para>
 781
 782 @window:
 783 @Returns:
 784
 785
 786 <!-- ##### FUNCTION gtk_window_get_icon ##### -->
 787 <para>
 788
 789 </para>
 790
 791 @window:
 792 @Returns:
 793
 794
 795 <!-- ##### FUNCTION gtk_window_get_icon_list ##### -->
 796 <para>
 797
 798 </para>
 799
 800 @window:
 801 @Returns:
 802
 803
 804 <!-- ##### FUNCTION gtk_window_get_mnemonic_modifier ##### -->
 805 <para>
 806
 807 </para>
 808
 809 @window:
 810 @Returns:
 811
 812
 813 <!-- ##### FUNCTION gtk_window_get_modal ##### -->
 814 <para>
 815
 816 </para>
 817
 818 @window:
 819 @Returns:
 820
 821
 822 <!-- ##### FUNCTION gtk_window_get_position ##### -->
 823 <para>
 824
 825 </para>
 826
 827 @window:
 828 @root_x:
 829 @root_y:
 830 <!-- # Unused Parameters # -->
 831 @x:
 832 @y:
 833
 834
 835 <!-- ##### FUNCTION gtk_window_get_role ##### -->
 836 <para>
 837
 838 </para>
 839
 840 @window:
 841 @Returns:
 842
 843
 844 <!-- ##### FUNCTION gtk_window_get_size ##### -->
 845 <para>
 846
 847 </para>
 848
 849 @window:
 850 @width:
 851 @height:
 852
 853
 854 <!-- ##### FUNCTION gtk_window_get_title ##### -->
 855 <para>
 856
 857 </para>
 858
 859 @window:
 860 @Returns:
 861
 862
 863 <!-- ##### FUNCTION gtk_window_get_transient_for ##### -->
 864 <para>
 865
 866 </para>
 867
 868 @window:
 869 @Returns:
 870
 871
 872 <!-- ##### FUNCTION gtk_window_get_type_hint ##### -->
 873 <para>
 874
 875 </para>
 876
 877 @window:
 878 @Returns:
 879
 880
 881 <!-- ##### FUNCTION gtk_window_get_skip_taskbar_hint ##### -->
 882 <para>
 883
 884 </para>
 885
 886 @window:
 887 @Returns:
 888
 889
 890 <!-- ##### FUNCTION gtk_window_get_skip_pager_hint ##### -->
 891 <para>
 892
 893 </para>
 894
 895 @window:
 896 @Returns:
 897
 898
 899 <!-- ##### FUNCTION gtk_window_get_accept_focus ##### -->
 900 <para>
 901
 902 </para>
 903
 904 @window:
 905 @Returns:
 906
 907
 908 <!-- ##### FUNCTION gtk_window_move ##### -->
 909 <para>
 910
 911 </para>
 912
 913 @window:
 914 @x:
 915 @y:
 916
 917
 918 <!-- ##### FUNCTION gtk_window_parse_geometry ##### -->
 919 <para>
 920
 921 </para>
 922
 923 @window:
 924 @geometry:
 925 @Returns:
 926
 927
 928 <!-- ##### FUNCTION gtk_window_reshow_with_initial_size ##### -->
 929 <para>
 930
 931 </para>
 932
 933 @window:
 934
 935
 936 <!-- ##### FUNCTION gtk_window_resize ##### -->
 937 <para>
 938
 939 </para>
 940
 941 @window:
 942 @width:
 943 @height:
 944
 945
 946 <!-- ##### FUNCTION gtk_window_set_default_icon_list ##### -->
 947 <para>
 948
 949 </para>
 950
 951 @list:
 952
 953
 954 <!-- ##### FUNCTION gtk_window_set_default_icon ##### -->
 955 <para>
 956
 957 </para>
 958
 959 @icon:
 960 <!-- # Unused Parameters # -->
 961 @pixbuf:
 962
 963
 964 <!-- ##### FUNCTION gtk_window_set_default_icon_from_file ##### -->
 965 <para>
 966
 967 </para>
 968
 969 @filename:
 970 @err:
 971 @Returns:
 972
 973
 974 <!-- ##### FUNCTION gtk_window_set_icon ##### -->
 975 <para>
 976
 977 </para>
 978
 979 @window:
 980 @icon:
 981
 982
 983 <!-- ##### FUNCTION gtk_window_set_icon_list ##### -->
 984 <para>
 985
 986 </para>
 987
 988 @window:
 989 @list:
 990
 991
 992 <!-- ##### FUNCTION gtk_window_set_icon_from_file ##### -->
 993 <para>
 994
 995 </para>
 996
 997 @window:
 998 @filename:
 999 @err:
1000 @Returns:
1001
1002
1003 <!-- ##### FUNCTION gtk_window_set_auto_startup_notification ##### -->
1004 <para>
1005
1006 </para>
1007
1008 @setting:
1009
1010
1011 <!-- ##### FUNCTION gtk_decorated_window_init ##### -->
1012 <para>
1013
1014 </para>
1015
1016 @window:
1017
1018
1019 <!-- ##### FUNCTION gtk_decorated_window_calculate_frame_size ##### -->
1020 <para>
1021
1022 </para>
1023
1024 @window:
1025
1026
1027 <!-- ##### FUNCTION gtk_decorated_window_set_title ##### -->
1028 <para>
1029
1030 </para>
1031
1032 @window:
1033 @title:
1034
1035
1036 <!-- ##### FUNCTION gtk_decorated_window_move_resize_window ##### -->
1037 <para>
1038
1039 </para>
1040
1041 @window:
1042 @x:
1043 @y:
1044 @width:
1045 @height:
1046
1047