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