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_add_accel_group ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @window:
 137 @accel_group:
 138
 139
 140 <!-- ##### FUNCTION gtk_window_remove_accel_group ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @window:
 146 @accel_group:
 147
 148
 149 <!-- ##### MACRO gtk_window_position ##### -->
 150 <para>
 151
 152 </para>
 153
 154
 155
 156 <!-- ##### FUNCTION gtk_window_activate_focus ##### -->
 157 <para>
 158
 159 </para>
 160
 161 @window:
 162 @Returns:
 163
 164
 165 <!-- ##### FUNCTION gtk_window_activate_default ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @window:
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION gtk_window_set_modal ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @window:
 180 @modal:
 181
 182
 183 <!-- ##### FUNCTION gtk_window_set_default_size ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @window:
 189 @width:
 190 @height:
 191
 192
 193 <!-- ##### FUNCTION gtk_window_set_geometry_hints ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @window:
 199 @geometry_widget:
 200 @geometry:
 201 @geom_mask:
 202
 203
 204 <!-- ##### FUNCTION gtk_window_set_position ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @window:
 210 @position:
 211
 212
 213 <!-- ##### FUNCTION gtk_window_set_transient_for ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @window:
 219 @parent:
 220
 221
 222 <!-- ##### FUNCTION gtk_window_set_destroy_with_parent ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @window:
 228 @setting:
 229
 230
 231 <!-- ##### FUNCTION gtk_window_list_toplevels ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @Returns:
 237
 238
 239 <!-- ##### SIGNAL GtkWindow::set-focus ##### -->
 240 <para>
 241
 242 </para>
 243
 244 @window: the object which received the signal.
 245 @widget:
 246
 247 <!-- ##### ARG GtkWindow:type ##### -->
 248 <para>
 249 The type of the window.
 250 </para>
 251
 252 <!-- ##### ARG GtkWindow:title ##### -->
 253 <para>
 254 The title of the window.
 255 </para>
 256
 257 <!-- ##### ARG GtkWindow:auto_shrink ##### -->
 258 <para>
 259 If the window shrinks automatically when widgets within it shrink.
 260 </para>
 261
 262 <!-- ##### ARG GtkWindow:allow_shrink ##### -->
 263 <para>
 264 If the window can be resized to a smaller size by the user.
 265 </para>
 266
 267 <!-- ##### ARG GtkWindow:allow_grow ##### -->
 268 <para>
 269 If the window can be resized to a larger size by the user.
 270 </para>
 271
 272 <!-- ##### ARG GtkWindow:modal ##### -->
 273 <para>
 274 If the window is modal, i.e. it grabs all GTK+ events.
 275 </para>
 276
 277 <!-- ##### ARG GtkWindow:window_position ##### -->
 278 <para>
 279 The position of the window.
 280 </para>
 281
 282 <!-- ##### ARG GtkWindow:default_width ##### -->
 283 <para>
 284
 285 </para>
 286
 287 <!-- ##### ARG GtkWindow:default_height ##### -->
 288 <para>
 289
 290 </para>
 291
 292 <!-- ##### ARG GtkWindow:destroy_with_parent ##### -->
 293 <para>
 294
 295 </para>
 296