Pileus Git - ~andy/gtk/blob - docs/reference/gtk/changes-2.0.sgml

   1 <refentry id="gtk-changes-2-0" revision="1 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Changes from 1.2 to 2.0</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Changes from 1.2 to 2.0</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Changes from 1.2 to 2.0</refname>
  10 <refpurpose>
  11 Incompatible changes made between version 1.2 and version 2.0
  12 </refpurpose>
  13 </refnamediv>
  14
  15
  16 <refsect1>
  17 <title>Incompatible changes from 1.2 to 2.0</title>
  18
  19 <para>
  20 The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
  21 porting guide</ulink> on <ulink
  22 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
  23 has some more detailed discussion of porting from 1.2 to 2.0.
  24 See the sections on GLib and GTK+.
  25 </para>
  26
  27 <para>
  28 GTK+ changed fairly substantially from version 1.2 to 2.0, much more
  29 so than from 1.0 to 1.2. Subsequent updates (possibilities are 2.0 to
  30 2.2, 2.2 to 2.4, then to 3.0) will almost certainly be much, much
  31 smaller. Nonetheless, most programs written for 1.2 compile against
  32 2.0 with few changes. The bulk of changes listed below are to obscure
  33 features or very specialized features, and compatibility interfaces
  34 exist whenever possible.
  35 </para>
  36
  37 <itemizedlist>
  38
  39 <listitem>
  40 <para>
  41 <function>gtk_container_get_toplevels()</function> was removed and replaced
  42   with <function>gtk_window_list_toplevels()</function>, which has different
  43   memory management on the return value
  44   (<function>gtk_window_list_toplevels()</function> copies the
  45   <structname>GList</structname> and also references each widget in the list,
  46   so you have to <function>g_list_free()</function> the list after first
  47   unref'ing each list member).
  48 </para>
  49 </listitem>
  50
  51 <listitem>
  52 <para>
  53 The <function>gdk_time*</function> functions have been removed. This
  54   functionality has been unused since the main loop was moved into GLib
  55   prior to 1.2.
  56 </para>
  57 </listitem>
  58
  59 <listitem>
  60 <para>
  61 The signature for <function>GtkPrintFunc</function> (used for
  62   <function>gtk_item_factory_dump_items()</function>)
  63   has been changed to take a <type>const gchar *</type> instead of
  64   <type>gchar *</type>, to match what we do for GLib, and other similar cases.
  65 </para>
  66 </listitem>
  67
  68 <listitem>
  69 <para>
  70 The detail arguments in the <structname>GtkStyleClass</structname> structure
  71 are now <type>const gchar *</type>.
  72 </para>
  73 </listitem>
  74
  75 <listitem>
  76 <para>
  77 <function>gtk_paned_set_gutter_size()</function> has been removed, since the
  78   small handle tab has been changed to include the entire area previously
  79   occupied by the gutter.
  80 </para>
  81 </listitem>
  82
  83 <listitem>
  84 <para>
  85 <function>gtk_paned_set_handle_size()</function> has been removed, in favor of
  86   a style property, since this is an option that only makes sense for themes
  87   to adjust.
  88 </para>
  89 </listitem>
  90
  91 <listitem>
  92 <para>
  93 GDK no longer selects OwnerGrabButtonMask for button presses. This means
  94   that the automatic grab that occurs when the user presses a button
  95   will have <literal>owner_events = FALSE</literal>, so all events are
  96   redirected to the grab window, even events that would normally go to
  97   other windows of the window's owner.
  98 </para>
  99 </listitem>
 100
 101 <listitem>
 102 <para>
 103 <structname>GtkColorSelectionDialog</structname> has now been moved into it's
 104   own set of files, <filename>gtkcolorseldialog.c</filename> and
 105   <filename>gtkcolorseldialog.h</filename>.
 106 </para>
 107 </listitem>
 108
 109 <listitem>
 110 <para>
 111 <function>gtk_widget_shape_combine_mask()</function> now keeps a reference
 112   count on the mask pixmap that is passed in.
 113 </para>
 114 </listitem>
 115
 116 <listitem>
 117 <para>
 118 The <structname>GtkPatternSpec</structname> has been moved to GLib as
 119   <structname>GPatternSpec</structname>, the pattern
 120   arguments to <function>gtk_item_factory_dump_items()</function> and
 121   <function>gtk_item_factory_dump_rc()</function>
 122   have thusly been changed to take a <structname>GPatternSpec</structname>
 123   instead of a <structname>GtkPatternSpec</structname>.
 124 </para>
 125 </listitem>
 126
 127 <listitem>
 128 <para>
 129 Type system changes:
 130 <itemizedlist>
 131 <listitem>
 132 <para>
 133    <literal>GTK_TYPE_OBJECT</literal> is not a fundamental type anymore. Type checks of the
 134     style <literal>(GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)</literal>
 135     will not work anymore. As a replacement, <literal>(GTK_TYPE_IS_OBJECT (some_type))</literal>
 136     can be used now.
 137 </para>
 138 </listitem>
 139 <listitem>
 140 <para>
 141 The following types vanished: <literal>GTK_TYPE_ARGS</literal>, <literal>GTK_TYPE_CALLBACK</literal>,
 142     <literal>GTK_TYPE_C_CALLBACK</literal>, <literal>GTK_TYPE_FOREIGN</literal>. The corresponding <structname>GtkArg</structname>
 143     fields and field access macros are also gone.
 144 </para>
 145 </listitem>
 146 <listitem>
 147 <para>
 148 The following type aliases vanished: <literal>GTK_TYPE_FLAT_FIRST</literal>,
 149     <literal>GTK_TYPE_FLAT_LAST</literal>, <literal>GTK_TYPE_STRUCTURED_FIRST</literal>,
 150     <literal>GTK_TYPE_STRUCTURED_LAST</literal>.
 151 </para>
 152 </listitem>
 153 <listitem>
 154 <para>
 155 The type macros <function>GTK_TYPE_MAKE()</function> and <function>GTK_TYPE_SEQNO()</function> vanished, use of
 156     <function>GTK_FUNDAMENTAL_TYPE()</function> is discouraged. Instead, the corresponding <structname>GType</structname>
 157     API should be used: <function>G_TYPE_FUNDAMENTAL()</function>, <function>G_TYPE_DERIVE_ID()</function>,
 158     <function>G_TYPE_BRANCH_SEQNO()</function>. Note that the GLib type system doesn't build new
 159     type ids based on a global incremental sequential number anymore, but
 160     numbers new type ids sequentially per fundamental type branch.
 161 </para>
 162 </listitem>
 163 <listitem>
 164 <para>
 165 The following type functions vanished/were replaced:
 166 <informaltable>
 167 <tgroup cols="2">
 168 <thead>
 169 <row><entry>Old Function</entry><entry>Replacement</entry></row>
 170 </thead>
 171 <tbody>
 172 <row><entry><function>gtk_type_query()</function></entry><entry>being investigated</entry></row>
 173 <row><entry><function>gtk_type_set_varargs_type()</function></entry><entry>-</entry></row>
 174 <row><entry><function>gtk_type_get_varargs_type()</function></entry><entry>-</entry></row>
 175 <row><entry><function>gtk_type_check_object_cast()</function></entry><entry><function>g_type_check_instance_cast()</function></entry></row>
 176 <row><entry><function>gtk_type_check_class_cast()</function></entry><entry><function>g_type_check_class_cast()</function></entry></row>
 177 <row><entry><function>gtk_type_describe_tree()</function></entry><entry>-</entry></row>
 178 <row><entry><function>gtk_type_describe_heritage()</function></entry><entry>-</entry></row>
 179 <row><entry><function>gtk_type_free()</function></entry><entry>-</entry></row>
 180 <row><entry><function>gtk_type_children_types()</function></entry><entry><function>g_type_children()</function></entry></row>
 181 <row><entry><function>gtk_type_set_chunk_alloc()</function></entry><entry><structfield>GTypeInfo.n_preallocs</structfield></entry></row>
 182 <row><entry><function>gtk_type_register_enum()</function></entry><entry><function>g_enum_register_static()</function></entry></row>
 183 <row><entry><function>gtk_type_register_flags()</function></entry><entry><function>g_flags_register_static()</function></entry></row>
 184 <row><entry><function>gtk_type_parent_class()</function></entry><entry><function>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
 185 </tbody>
 186 </tgroup>
 187 </informaltable>
 188     Use of <function>g_type_class_ref()</function>/<function>g_type_class_unref()</function> and <function>g_type_class_peek()</function>
 189     is recommended over usage of <function>gtk_type_class()</function>.
 190     Use of <function>g_type_register_static()</function>/<function>g_type_register_dynamic()</function> is recommended
 191     over usage of <function>gtk_type_unique()</function>.
 192 </para>
 193 </listitem>
 194 </itemizedlist>
 195 </para>
 196 </listitem>
 197
 198 <listitem>
 199 <para>
 200 Object system changes:
 201   <structname>GtkObject</structname> derives from <structname>GObject</structname>, so is not the basic object type anymore.
 202   This imposes the following source incompatible changes:
 203 <itemizedlist>
 204
 205 <listitem>
 206 <para>
 207 <structname>GtkObject</structname> has no <structfield>klass</structfield> field anymore, an object's class can be retrieved
 208     with the object's coresponding <literal>GTK_&lt;OBJECT&gt;_GET_CLASS (object)</literal>
 209     macro.
 210 </para>
 211 </listitem>
 212 <listitem>
 213 <para>
 214 <structname>GtkObjectClass</structname> has no <structfield>type</structfield> field anymore, a class's type can be retrived
 215     with the <literal>GTK_CLASS_TYPE (class)</literal> macro.
 216 </para>
 217 </listitem>
 218 <listitem>
 219 <para>
 220 <structname>GtkObjectClass</structname> does not introduce the <function>finalize()</function> and <function>shutdown()</function> methods
 221     anymore. While <function>shutdown()</function> is intended for GTK+ internal use only, <function>finalize()</function>
 222     is required by a variety of object implementations. <function>GObjectClass.finalize</function>
 223     should be overriden here, e.g.:
 224 <informalexample><programlisting>
 225     static void gtk_label_finalize (GObject *gobject)
 226     {
 227       GtkLabel *label = GTK_LABEL (gobject);
 228
 229       G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
 230     }
 231     static void gtk_label_class_init (GtkLabelClass *class)
 232     {
 233       GObjectClass *gobject_class = G_OBJECT_CLASS (class);
 234
 235       gobject_class-&gt;finalize = gtk_label_finalize;
 236     }
 237 </programlisting></informalexample>
 238 </para>
 239 </listitem>
 240
 241 </itemizedlist>
 242 </para>
 243 </listitem>
 244
 245 <listitem>
 246 <para>
 247 The GtkObject::destroy signal can now be emitted multiple times on an object.
 248     ::destroy implementations should check that make sure that they take this
 249     into account, by checking to make sure that resources are there before
 250     freeing them. For example:
 251 <informalexample><programlisting>
 252     if (object-&gt;foo_data)
 253       {
 254         g_free (object-&gt;foo_data);
 255         object-&gt;foo_data = NULL;
 256       }
 257 </programlisting></informalexample>
 258
 259     Also, ::destroy implementations have to release object references that
 260     the object holds. Code in finalize implementations such as:
 261 <informalexample><programlisting>
 262     if (object-&gt;adjustment)
 263       {
 264         gtk_object_unref (object-&gt;adjustment);
 265         object-&gt;adjustment = NULL;
 266       }
 267 </programlisting></informalexample>
 268     have to be moved into the ::destroy implementations. The reason for doing
 269     this is that all object reference cycles should be broken at destruction
 270     time.
 271
 272     Because the ::destroy signal can be emitted multiple times, it no longer
 273     makes sense to check if a widget has been destroyed using the
 274     <function>GTK_OBJECT_DESTROYED()</function> macro, and this macro has been
 275     removed. If catching destruction is still needed, it can be done with a
 276     signal connection to ::destroy.
 277 </para>
 278 </listitem>
 279
 280 <listitem>
 281 <para>
 282 Signal system changes:
 283   The GTK+ 2.0 signal system merely proxies the <structname>GSignal</structname>
 284   system now. For future usage, direct use of the
 285   <structname>GSignal</structname> API is recommended,
 286   this avoids significant performance hits where <structname>GtkArg</structname>
 287   structures have to be converted into <structname>GValue</structname>s. For
 288   language bindings, <structname>GSignal</structname>+<structname>GClosure</structname>
 289   provide a much more flexible and convenient mechanism to hook into signal
 290   emissions or install class default handlers, so the old
 291   <structname>GtkSignal</structname> API for language bindings is not
 292   supported anymore.
 293 </para>
 294 <para>
 295   Functions that got removed in the GTK+ signal API:
 296   <function>gtk_signal_n_emissions()</function>,
 297   <function>gtk_signal_n_emissions_by_name()</function>,
 298   <function>gtk_signal_set_funcs()</function>,
 299   <function>gtk_signal_handler_pending_by_id()</function>,
 300   <function>gtk_signal_add_emission_hook()</function>,
 301   <function>gtk_signal_add_emission_hook_full()</function>,
 302   <function>gtk_signal_remove_emission_hook()</function>,
 303   <function>gtk_signal_query()</function>.
 304   Also, the <structname>GtkCallbackMarshal</structname> argument to
 305   <function>gtk_signal_connect_full()</function> is
 306   not supported anymore.
 307   For many of the removed functions, similar variants are available
 308   in the <function>g_signal_*</function> namespace.
 309   The <structname>GSignal</structname> system performs emissions in a
 310   slightly different manner than the old <structname>GtkSignal</structname>
 311   code. Signal handlers that are connected to signal "foo"
 312   on object "bar" while "foo" is being emitted, will not be called anymore
 313   during the emission they were connected within.
 314 </para>
 315 </listitem>
 316
 317 <listitem>
 318 <para>
 319 Inserting and deleting text in <structname>GtkEntry</structname> though
 320   functions such as <function>gtk_entry_insert_text()</function> now leave
 321   the cursor at its original position in the text instead of moving it to
 322   the location of the insertion/deletion.
 323 </para>
 324 </listitem>
 325
 326 <listitem>
 327 <para>
 328 The <structfield>label</structfield> field of <structname>GtkFrame</structname>
 329   widgets has been removed (as part of a change to allow arbitrary widgets
 330   in the title position). The text can now be retrieved with the new function
 331   <function>gtk_frame_get_text()</function>.
 332 </para>
 333 </listitem>
 334
 335 <listitem>
 336 <para>
 337 The 'font' and 'font_set' declarations in RC files are now ignored. There
 338   is a new 'font_name' field that holds the string form of a Pango font.
 339 </para>
 340 </listitem>
 341
 342 <listitem>
 343 <para>
 344 A number of types in GDK have become subclasses of
 345   <structname>GObject</structname>. For the most part, this should not break
 346   anyone's code. However, it's now possible/encouraged to use
 347   <function>g_object_ref()</function>/<function>g_object_unref()</function> and
 348   other <structname>GObject</structname> features with these GDK types. The
 349   converted types are:
 350   <structname>GdkWindow</structname>, <structname>GdkDrawable</structname>,
 351   <structname>GdkPixmap</structname>, <structname>GdkImage</structname>,
 352   <structname>GdkGC</structname>, <structname>GdkDragContext</structname>,
 353   <structname>GdkColormap</structname>.
 354 </para>
 355 </listitem>
 356
 357 <listitem>
 358 <para>
 359 All drawables including pixmaps used to have a type tag, the
 360   <structname>GdkWindowType</structname> enumeration, which included
 361   <literal>GDK_WINDOW_PIXMAP</literal>.
 362   <structname>GdkWindowType</structname> is now a property of
 363   <structname>GdkWindow</structname> <emphasis>only</emphasis>, and there is
 364   no <literal>GDK_WINDOW_PIXMAP</literal>. You can use the
 365   <function>GDK_IS_PIXMAP()</function> macro to see if you have a pixmap, if
 366   you need to know that.
 367 </para>
 368 </listitem>
 369
 370 <listitem>
 371 <para>
 372 <structname>GtkStyle</structname> and <structname>GtkRcStyle</structname> are
 373   now subclasses of <structname>GObject</structname> as well.  This
 374   requires fairly extensive changes to theme engines, but
 375   shouldn't affect most other code.
 376 </para>
 377 </listitem>
 378
 379 <listitem>
 380 <para>
 381 <structfield>xthickness</structfield> and <structfield>ythickness</structfield> have moved from
 382   <structname>GtkStyleClass</structname> to <structname>GtkStyle</structname>
 383   (from class to instance). This gives themes a bit more flexibility
 384   and is generally more of the Right Thing. You can trivially fix
 385   your code with <literal>s/style-&gt;klass-&gt;xthickness/style-&gt;xthickness/g</literal> and
 386   same for <literal>ythickness</literal>.
 387 </para>
 388 </listitem>
 389
 390 <listitem>
 391 <para>
 392 Some <structname>GtkStyle</structname> <function>draw_*</function> methods
 393   have been removed (cross, oval, ramp)
 394   and others have been added (expander, layout). This will require
 395   changes to theme engines.
 396 </para>
 397 </listitem>
 398
 399 <listitem>
 400 <para>
 401 If you were using private GDK types, they have been rearranged
 402   significantly. You shouldn't use private types. ;-)
 403 </para>
 404 </listitem>
 405
 406 <listitem>
 407 <para>
 408 The visual for a widget, and also the default visual is now derived
 409   from the colormap for the widget and the default colormap.
 410   <function>gtk_widget_set_visual()</function>,
 411   <function>gtk_widget_set_default_visual()</function>,
 412   <function>gtk_widget_push_visual()</function> and
 413   <function>gtk_widget_pop_visual()</function> now do
 414   nothing. Since the visual always had to match that of the colormap,
 415   it is safe to simply delete all references to these functions.
 416 </para>
 417 </listitem>
 418
 419
 420 <listitem>
 421 <para>
 422 A number of functions in GDK have been renamed for consistency and
 423   clarity. #defines to provide backwards compatibility have been
 424   included, but can be disabled by defining <literal>GDK_DISABLE_DEPRECATED</literal>.
 425
 426 <informaltable>
 427 <tgroup cols="2">
 428 <thead>
 429 <row><entry>Old function</entry><entry>Defined As</entry></row>
 430 </thead>
 431 <tbody>
 432 <row><entry><function>gdk_draw_pixmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>
 433  <row><entry><function>gdk_draw_bitmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>
 434 <row><entry><function>gdk_window_get_size</function></entry><entry><function>gdk_drawable_get_size</function></entry></row>
 435 <row><entry><function>gdk_window_get_type</function></entry><entry><function>gdk_window_get_window_type</function></entry></row>
 436 <row><entry><function>gdk_window_get_colormap</function></entry><entry><function>gdk_drawable_get_colormap</function></entry></row>
 437 <row><entry><function>gdk_window_set_colormap</function></entry><entry><function>gdk_drawable_set_colormap</function></entry></row>
 438 <row><entry><function>gdk_window_get_visual</function></entry><entry><function>gdk_drawable_get_visual</function></entry></row>
 439 <row><entry><function>gdk_window_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
 440 <row><entry><function>gdk_window_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
 441 <row><entry><function>gdk_bitmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
 442 <row><entry><function>gdk_bitmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
 443 <row><entry><function>gdk_pixmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
 444 <row><entry><function>gdk_pixmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
 445 <row><entry><function>gdk_gc_destroy</function></entry><entry><function>gdk_gc_unref</function></entry></row>
 446 <row><entry><function>gdk_image_destroy</function></entry><entry><function>gdk_image_unref</function></entry></row>
 447 <row><entry><function>gdk_cursor_destroy</function></entry><entry><function>gdk_cursor_unref</function></entry></row>
 448 <row><entry><function>gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height)</function></entry><entry><function>gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)</function></entry></row>
 449 <row><entry><function>gdk_rgb_get_cmap</function></entry><entry><function>gdk_rgb_get_colormap</function></entry></row>
 450 </tbody>
 451 </tgroup>
 452 </informaltable>
 453   (Note that <function>g_object_ref()</function> and
 454   <function>g_object_unref()</function> may be used for all of the above ref
 455   and unref functions.)
 456
 457   <function>gtk_widget_popup()</function> was removed, it was only usable
 458   for <structname>GtkWindow</structname>s, and there the same effect can be
 459   achieved by <function>gtk_window_move()</function> and
 460   <function>gtk_widget_show()</function>.
 461 </para>
 462 </listitem>
 463
 464 <listitem>
 465 <para>
 466 <function>gdk_pixmap_foreign_new()</function> no longer calls
 467   <function>XFreePixmap()</function> on the pixmap when the
 468   <structname>GdkPixmap</structname> is finalized. This change corresponds
 469   to the behavior of <function>gdk_window_foreign_new()</function>, and fixes
 470   a lot of problems with code where the pixmap wasn't supposed to be freed.
 471   If <function>XFreePixmap()</function> is needed, it can be done using the
 472   destroy-notification facilities of <function>g_object_set_data()</function>.
 473 </para>
 474 </listitem>
 475
 476 <listitem>
 477 <para>
 478 <structname>GtkProgress</structname>/<structname>GtkProgressBar</structname>
 479   had serious problems in GTK+ 1.2.
 480 <itemizedlist>
 481 <listitem>
 482 <para>
 483 Only 3 or 4 functions are really needed for 95% of progress interfaces;
 484   <structname>GtkProgress</structname>/<structname>GtkProgressBar</structname>
 485   had about 25 functions, and didn't even include these 3 or 4.
 486 </para>
 487 </listitem>
 488
 489 <listitem>
 490 <para>
 491 In activity mode, the API involves setting the adjustment
 492     to any random value, just to have the side effect of
 493     calling the progress bar update function - the adjustment
 494     is totally ignored in activity mode.
 495 </para>
 496 </listitem>
 497
 498 <listitem>
 499 <para>
 500 You set the activity step as a pixel value, which means to
 501     set the activity step you basically need to connect to
 502     size_allocate.
 503 </para>
 504 </listitem>
 505
 506 <listitem>
 507 <para>
 508 There are <function>ctree_set_expander_style()</function>-functions, to
 509     randomly change look-and-feel for no good reason.
 510 </para>
 511 </listitem>
 512
 513 <listitem>
 514 <para>
 515 The split between <structname>GtkProgress</structname> and
 516 <structname>GtkProgressBar</structname> makes no sense to me whatsoever.
 517 </para>
 518 </listitem>
 519
 520 </itemizedlist>
 521
 522   This was a big wart on GTK+ and made people waste lots of time,
 523   both learning and using the interface.
 524   So, we have added what we feel is the correct API, and marked all the
 525   rest deprecated. However, the changes are 100% backward-compatible and
 526   should break no existing code.
 527   The following 5 functions are the new programming interface and you
 528   should consider changing your code to use them:
 529 <programlisting>
 530   void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
 531   void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
 532                                                     const gchar    *text);
 533   void       gtk_progress_bar_set_fraction         (GtkProgressBar *pbar,
 534                                                     gfloat          fraction);
 535
 536   void       gtk_progress_bar_set_pulse_step       (GtkProgressBar *pbar,
 537                                                     gfloat          fraction);
 538   void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
 539                                                     GtkProgressBarOrientation orientation);
 540 </programlisting>
 541 </para>
 542 </listitem>
 543
 544 <listitem>
 545 <para>
 546 The <structname>GtkNotebookPage</structname> structure has been removed from
 547   the public header files;
 548   this was never meant to be a public structure, and all functionality that
 549   could be done by accessing the struct fields of this structure should be
 550   accessible otherwise.
 551 </para>
 552 </listitem>
 553
 554 <listitem>
 555 <para>
 556 Negative values of the <parameter>position</parameter> parameter to
 557   <function>gtk_notebook_reorder_child()</function> now cause the page to be appended, not
 558   inserted at the beginning. (This gives consistency with
 559   <function>gtk_box_reorder_child()</function>, <function>gtk_menu_reorder_child()</function>.)
 560 </para>
 561 </listitem>
 562
 563 <listitem>
 564 <para>
 565 <function>GtkMenuPositionFunc</function> has a new parameter
 566   <literal>push_in</literal> which controls how menus placed outside the
 567   screen is handled. If this is set to <literal>TRUE</literal> and
 568   part of the menu is outside the screen then GTK+ pushes it into the visible
 569   area. Otherwise the menu is cut of at the end of the visible screen area.
 570 </para>
 571 <para>
 572   Regardless of what happens to the size of the menu, the result is always
 573   that the items are placed in the same place as if the menu was placed
 574   outside the screen, using menu scrolling if necessary.
 575 </para>
 576 </listitem>
 577
 578 <listitem>
 579 <para>
 580 The "draw" signal and virtual method on <structname>GtkWidget</structname>
 581   has been removed.
 582   All drawing should now occur by invalidating a region of the widget
 583   (call <function>gdk_window_invalidate_rect()</function> or
 584   <function>gtk_widget_queue_draw()</function> for example to invalidate
 585   a region). GTK+ merges all invalid regions, and sends expose events to
 586   the widget in an idle handler for the invalid regions.
 587   <function>gtk_widget_draw()</function> is deprecated but still works; it
 588   adds the passed-in area to the invalid region and immediately sends
 589   expose events for the current invalid region.
 590   Most widgets will work fine if you just delete their "draw"
 591   implementation, since they will already have working expose_event
 592   implementations. The draw method was rarely called in practice
 593   anyway.
 594 </para>
 595 </listitem>
 596
 597 <listitem>
 598 <para>
 599 The <structname>GdkExposeEvent</structname> has a new <structfield>region</structfield>
 600   field. This can be used instead of the <structfield>area</structfield> field if you
 601   want a more exact representation of the area to update.
 602 </para>
 603 </listitem>
 604
 605 <listitem>
 606 <para>
 607 Sending synthetic exposes using <function>gtk_widget_event()</function> is no
 608   longer allowed. If you just need an expose call you should use
 609   <function>gdk_window_invalidate_rect()</function> or
 610   <function>gdk_window_invalidate_region()</function> instead. For the case
 611   of container widgets that need to propagate expose events to
 612   <literal>NO_WINDOW</literal> children you can either use
 613   <function>gtk_container_propagate_expose()</function>, or chain to the
 614   default container expose handler.
 615 </para>
 616 </listitem>
 617
 618 <listitem>
 619 <para>
 620 The draw_default and draw_focus methods/signals on
 621   <structname>GtkWidget</structname> are gone; simply draw things in your
 622   expose handler. <function>gtk_widget_draw_focus()</function> and
 623   <function>gtk_widget_draw_default()</function> wrapper
 624   functions are also gone; just queue a draw on the widget,
 625   or the part affected by the focus/default anyway.
 626   Also, <structname>GtkWidget</structname> now has default implementations for
 627   focus_in_event and focus_out_event. These set/unset
 628   <literal>GTK_HAS_FOCUS</literal>, and queue a draw. So if your focus in/out
 629   handler just does that, you can delete it.
 630 </para>
 631 </listitem>
 632
 633 <listitem>
 634 <para>
 635 <structname>GtkText</structname> and <structname>GtkTree</structname> are
 636   buggy and broken. We don't recommend using them, and changing old code to
 637   avoid them is a good idea. The recommended alternatives are
 638   <structname>GtkTextView</structname> and <structname>GtkTreeView</structname>.
 639   The broken widgets are not declared in the headers by default; to use
 640   them, define the symbol <literal>GTK_ENABLE_BROKEN</literal> during
 641   compilation. In some future release, these widgets will be removed from GTK+.
 642 </para>
 643 </listitem>
 644
 645 <listitem>
 646 <para>
 647 <structname>GdkColorContext</structname> is gone; you probably weren't using
 648   it anyway.  Use <structname>GdkColormap</structname> and the
 649   <function>gdk_rgb_*</function> functions instead.
 650 </para>
 651 </listitem>
 652
 653 <listitem>
 654 <para>
 655 <structname>GtkMenuBar</structname> now draws the <structfield>GtkContainer::border_width</structfield>
 656   space outside the frame, not inside the frame.
 657 </para>
 658 </listitem>
 659
 660
 661 <listitem>
 662 <para>
 663 In GTK+ 1.2, if an event handler returned <literal>TRUE</literal> it prevented
 664   propagation of that event to parent widgets. That is, the
 665   event signal would not be emitted on parent widgets. In
 666   GTK+ 2.0, if an event handler returns <literal>TRUE</literal>, the current
 667   signal emission on the current widget is immediately stopped. That is,
 668   other callbacks connected to the signal will not be invoked.
 669 </para>
 670 </listitem>
 671
 672 <listitem>
 673 <para>
 674 <function>gtk_toolbar_new()</function> no longer has arguments. This function
 675   was broken because the default <literal>GtkToolbarStyle</literal> (icons,
 676   text, both) is now a user preference, which is overridden when you call
 677   <function>gtk_toolbar_set_style()</function>. The constructor forced everyone
 678   to override the preference, which was undesirable. So to port
 679   your app, decide if you want to force the toolbar style
 680   or conform to the user's global defaults; if you want to force
 681   it, call <function>gtk_toolbar_set_style()</function>.
 682 </para>
 683
 684 <para>
 685   The orientation arg was removed from <function>gtk_toolbar_new()</function>
 686   as well, just because it wasn't very useful and we were breaking the function
 687   anyway so had an opportunity to lose it. Call
 688   <function>gtk_toolbar_set_orientation()</function> to set toolbar orientation.
 689 </para>
 690 </listitem>
 691
 692
 693 <listitem>
 694 <para>
 695 <structname>GtkRange</structname>/<structname>GtkScrollbar</structname>/<structname>GtkScale</structname> were rewritten; this means that most
 696   theme engines won't draw them properly, and any custom subclasses of
 697   these widgets will need a rewrite (though if you could figure out
 698   how to subclass the old version of <structname>GtkRange</structname>, you
 699   have our respect). Also, <literal>GtkTroughType</literal> is gone.
 700 </para>
 701 <para>
 702  Here are some notable changes:
 703  <itemizedlist>
 704    <listitem>
 705      <para>
 706        <literal>stepper_size</literal> style property is the height for
 707        vertical ranges, width for horizontal; the other dimension matches
 708        the trough size.
 709      </para>
 710    </listitem>
 711    <listitem>
 712      <para>
 713        Added the ability to do NeXT-style steppers (and several other styles
 714        that don't make any sense).
 715      </para>
 716    </listitem>
 717    <listitem>
 718      <para>
 719        Added <literal>min_slider_length</literal>,
 720        <literal>fixed_slider_length</literal> properties to
 721        <structname>GtkScrollbar</structname>.
 722      </para>
 723    </listitem>
 724    <listitem>
 725      <para>
 726        Cleaned some private (or at least useless) functions out of
 727        <filename>gtkscale.h</filename>, e.g.
 728        <function>gtk_scale_value_width</function>.
 729      </para>
 730    </listitem>
 731    <listitem>
 732      <para>
 733        Moved bindings from subclasses to <structname>GtkScale</structname>,
 734        even arrow keys, since blind users don't know scale orientation.
 735      </para>
 736    </listitem>
 737    <listitem>
 738      <para>
 739        Changed <literal>move_slider</literal> action signal to use new
 740        <structname>GtkScrollType</structname>, remove
 741        <structname>GtkTroughType</structname> argument.
 742      </para>
 743    </listitem>
 744    <listitem>
 745      <para>
 746        Digits rounds the values a range will input to the given
 747        number of decimals, but will not try to force adjustment
 748        values set by other controllers. That is, we no longer
 749        modify <literal>adjustment->value</literal> inside a
 750        <literal>value_changed</literal> handler.
 751      </para>
 752    </listitem>
 753    <listitem>
 754      <para>
 755        Added getters for <structname>GtkScale</structname> setters.
 756      </para>
 757    </listitem>
 758    <listitem>
 759      <para>
 760        Middle-click begins a slider drag.
 761      </para>
 762    </listitem>
 763  </itemizedlist>
 764 </para>
 765 </listitem>
 766
 767 <listitem>
 768 <para>
 769 The GtkContainer::focus signal/virtual function and
 770   <function>gtk_container_focus()</function> call were replaced by
 771   GtkWidget::focus and <function>gtk_widget_child_focus()</function>.
 772   The semantics are the same, so you should be able to just
 773   replace <literal>container_class-&gt;focus = mywidget_focus</literal> with
 774   <literal>widget_class-&gt;focus = mywidget_focus</literal> and replace
 775   <function>gtk_container_focus()</function> calls with
 776   <function>gtk_widget_child_focus()</function> calls.
 777 </para>
 778 <para>
 779   The purpose of this change was to allow non-containers to have
 780   focusable elements.
 781 </para>
 782 </listitem>
 783
 784 <listitem>
 785 <para>
 786 <function>gtk_rc_set_image_loader()</function> and
 787 <function>gtk_rc_load_image()</function> have been removed, now
 788   that GTK+ includes decent image loading capabilities itself.
 789 </para>
 790 </listitem>
 791
 792 <listitem>
 793 <para>
 794 An extra <structname>GtkSettings</structname> argument has been added to
 795   <function>gtk_rc_find_pixmap_in_path()</function>. This function is only
 796   actually useful from a theme engine during parsing, at which point the
 797   <structname>GtkSettings</structname> is provided.
 798 </para>
 799 </listitem>
 800
 801 <listitem>
 802 <para>
 803 The child argument facility in <filename>gtkcontainer.c</filename> has been
 804   converted to a child property facility using
 805   <structname>GParamSpec</structname> and other facilities
 806   for <structname>GObject</structname>.
 807 </para>
 808 </listitem>
 809
 810  <listitem>
 811 <para>
 812 The <function>set_child_arg()</function> and <function>get_child_arg()</function>
 813      virtual methods have been replaced with <function>set_child_property()</function>/<function>get_child_property()</function>, which
 814      work similar to GObject-&gt;set_property/get_property.
 815 </para>
 816 </listitem>
 817
 818
 819  <listitem>
 820 <para>
 821 Other removed <structname>GtkContainer</structname> functions with the replacements:
 822
 823 <informaltable>
 824 <tgroup cols="2">
 825 <thead>
 826 <row><entry>Old function</entry><entry>Replacement</entry></row>
 827 </thead>
 828 <tbody>
 829 <row><entry><function>gtk_container_add_child_arg_type</function></entry><entry><function>gtk_container_class_install_child_property</function></entry></row>
 830 <row><entry><function>gtk_container_query_child_args</function></entry><entry><function>gtk_container_class_list_child_properties</function></entry></row>
 831 <row><entry><function>gtk_container_child_getv</function></entry><entry><function>gtk_container_child_set_property</function></entry></row>
 832 <row><entry><function>gtk_container_child_setv</function></entry><entry><function>gtk_container_child_get_property</function></entry></row>
 833 <row><entry><function>gtk_container_add_with_args</function></entry><entry><function>gtk_container_add_with_properties</function></entry></row>
 834 <row><entry><function>gtk_container_addv</function></entry><entry><function>gtk_container_add</function>/<function>gtk_container_child_set_property</function></entry></row>
 835 </tbody>
 836 </tgroup>
 837 </informaltable>
 838 </para>
 839 </listitem>
 840
 841
 842 <listitem>
 843 <para>
 844 <function>gdk_image_get()</function> (or rather its replacement,
 845   <function>gdk_drawable_get_image()</function>) now handles errors properly
 846   by returning <literal>NULL</literal>, previously it would crash. Also, a
 847   window being offscreen is no longer considered an error; instead, the area
 848   contains undefined contents for the offscreen areas. In most cases, code
 849   using <function>gdk_image_get()</function> should really be ported to
 850   <function>gdk_pixbuf_get_from_drawable()</function>.
 851 </para>
 852 </listitem>
 853
 854 <listitem>
 855 <para>
 856 <function>gtk_widget_set_usize()</function> has been renamed to
 857   <function>gtk_widget_set_size_request()</function>, however the old name
 858   still exists unless you define <literal>GTK_DISABLE_DEPRECATED</literal>.
 859 </para>
 860 </listitem>
 861
 862 <listitem>
 863 <para>
 864 <function>gtk_widget_set_uposition()</function> is deprecated; use
 865   <function>gtk_window_move()</function>,
 866   <function>gtk_fixed_put()</function>, or <function>gtk_layout_put()</function>
 867   instead.
 868 </para>
 869 </listitem>
 870
 871 <listitem>
 872 <para>
 873 <function>gtk_window_set_policy()</function> is deprecated. To get the effect of
 874   "allow_shrink", call
 875   <literal>gtk_widget_set_size_request (window, 0, 0)</literal>. To get the
 876   effect of "allow_grow", call
 877   <literal>gtk_window_set_resizable (window, TRUE)</literal>. You didn't want
 878   the effect of "auto_shrink", it made no sense. But maybe if you were using
 879   it you want to use <literal>gtk_window_resize (window, 1, 1)</literal> to
 880   snap a window back to its minimum size (the 1, 1 will be rounded up to the
 881   minimum window size).
 882 </para>
 883 </listitem>
 884
 885 <listitem>
 886 <para>
 887 The core GTK+ now takes care of handling mapping, unmapping and
 888   realizing the child widgets of containers in
 889   <function>gtk_widget_set_parent()</function>. In most cases, this allows
 890   container implementations to be simplified by removing the code in
 891   <function>add()</function> methods to map and realize children. However,
 892   there are a couple of things to watch out for here:
 893 </para>
 894 </listitem>
 895
 896
 897  <listitem>
 898 <para>
 899 If the parent is realized before the <function>add()</function> happens,
 900      <function>gtk_widget_set_parent_window()</function> must be called before
 901      <function>gtk_widget_set_parent()</function>, since
 902      <function>gtk_widget_set_parent()</function> will realize the child.
 903 </para>
 904 </listitem>
 905
 906  <listitem>
 907 <para>
 908 If a container depended on its children not being mapped
 909      unless it did so itself (for example, <structname>GtkNotebook</structname>
 910      only mapped the current page), then the new function
 911      <function>gtk_widget_set_child_visible()</function> must be called to keep
 912      widgets that should not be mapped not mapped.
 913 </para>
 914
 915 <para>
 916   As part of this change, most containers also will no longer need custom
 917   implementations of the <function>map()</function> and
 918   <function>unmap()</function> virtual functions. The only cases where this
 919   is necessary are:
 920
 921 <itemizedlist>
 922  <listitem>
 923 <para>
 924 For <literal>!NO_WINDOW</literal> widgets, if you create children of
 925      <literal>widget-&gt;window</literal>
 926      and don't map them in <function>realize()</function> then you must map them
 927      in <function>map()</function>. [ In almost all cases, you can simply map the
 928      windows in <function>realize()</function>. ]
 929 </para>
 930 </listitem>
 931
 932  <listitem>
 933 <para>
 934 For <literal>NO_WINDOW</literal> widgets, if you create windows in your
 935      <function>realize()</function> method, you must map then in
 936      <function>map()</function> and unmap them in <function>unmap()</function>.
 937 </para>
 938 </listitem>
 939 </itemizedlist>
 940 </para>
 941 </listitem>
 942
 943 <listitem>
 944 <para>
 945 <function>gtk_widget_set_default_style()</function>,
 946    <function>gtk_widget_push_style()</function>,
 947   and <function>gtk_widget_pop_style()</function> have been removed, since they
 948   did not work properly with themes and there were better
 949   alternatives for modifying the appearance of widgets.
 950
 951   You should generally use <function>gtk_widget_modify_*()</function>
 952   instead.
 953 </para>
 954 </listitem>
 955
 956
 957 <listitem>
 958 <para>
 959 <function>gtk_image_new()</function> now takes no arguments and creates an
 960   empty <structname>GtkImage</structname> widget. To create a
 961   <structname>GtkImage</structname> widget from a
 962   <structname>GdkImage</structname> (the least
 963   common usage of <structname>GdkImage</structname>), use
 964   <function>gtk_image_new_from_image()</function>.
 965 </para>
 966 </listitem>
 967
 968 <listitem>
 969 <para>
 970 <literal>GTK_SELECTION_EXTENDED</literal> is now deprecated, and neither the
 971   <structname>GtkList</structname>/<structname>GtkTree</structname> nor the
 972   <structname>GtkCList</structname>/<structname>GtkCTree</structname> support
 973   <literal>GTK_SELECTION_EXTENDED</literal> anymore.  However, the old extended
 974   behavior replaces <literal>MULTIPLE</literal> behavior.
 975 </para>
 976 </listitem>
 977
 978 <listitem>
 979 <para>
 980 The following variables are no longer exported from GDK. (Other variables
 981   are also no longer exported; the following are the ones found used
 982   externally in a large sample of GTK+ code.)
 983
 984 <informaltable>
 985 <tgroup cols="2">
 986 <thead>
 987 <row><entry>Variable</entry><entry>Replacement</entry></row>
 988 </thead>
 989 <tbody>
 990 <row><entry><literal>gdk_null_window_warnings</literal></entry><entry>None - did nothing in GTK+ 1.2</entry></row>
 991 <row><entry><literal>gdk_leader_window</literal></entry><entry>None - private variable</entry></row>
 992 <row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
 993 <row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
 994 <row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
 995 <row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
 996 <row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
 997 <row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
 998 <row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
 999 <row><entry><literal>gdk_wm_take_focus</literal></entry><entry><literal>gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)</literal></entry></row>
1000 <row><entry><literal>gdk_wm_protocols</literal></entry><entry><literal>gdk_atom_intern ("WM_PROTOCOLS", FALSE)</literal></entry></row>
1001 </tbody>
1002 </tgroup>
1003 </informaltable>
1004 </para>
1005 </listitem>
1006
1007
1008 <listitem>
1009 <para>
1010 The handling of colormaps and widgets has been changed:
1011
1012 <itemizedlist>
1013   <listitem>
1014 <para>
1015 The default colormap for widgets is now the <structname>GdkRGB</structname>
1016       colormap, not the system default colormap. If you try to use resources
1017       created for  a widget (e.g., <literal>widget-&gt;style</literal>) with
1018       a window using the system colormap, errors will result on some machines.
1019 </para>
1020 </listitem>
1021
1022
1023   <listitem>
1024 <para>
1025 <function>gtk_widget_push()</function>/<function>gtk_widget_pop_colormap()</function>
1026       only cause the colormap to be explicitly set on toplevel widgets, not on
1027       all widgets. The colormap for other widgets (when not set using
1028       <function>gtk_widget_set_colormap()</function>), is determined by finding
1029       the nearest ancestor with a colormap set on it explicitly, or if that
1030       fails, the default colormap.
1031 </para>
1032 </listitem>
1033
1034 </itemizedlist>
1035
1036 </para>
1037 </listitem>
1038
1039
1040 <listitem>
1041 <para>
1042 The default selected day for <structname>GtkCalendar</structname> is now the
1043   current day in the month, not the first day in the month. The current month
1044   and year were already used.
1045 </para>
1046 </listitem>
1047
1048
1049 <listitem>
1050 <para>
1051 GDK is no longer put into threaded mode automatically when
1052   <function>g_thread_init()</function> has been called. In order to use the
1053   global GDK thread mutex with <function>gdk_threads_enter()</function> and
1054   <function>gdk_threads_leave()</function>, you must call
1055   <function>gdk_threads_init()</function> explicitly.
1056
1057   If you aren't using GDK and GTK+ functions from multiple threads,
1058   there is no reason to call <function>gdk_threads_init()</function>.
1059 </para>
1060 </listitem>
1061
1062 <listitem>
1063 <para>
1064 The <structname>GtkPreviewInfo</structname> struct has had its visual and
1065   colormap fields removed.  Also, <function>gtk_preview_get_cmap()</function>
1066   and <function>gtk_preview_get_visual()</function> are deprecated, as
1067   <structname>GdkRGB</structname> works on any colormap and visual.  You no
1068   longer need to
1069   <literal>gtk_widget_push_cmap (gtk_preview_get_cmap ())</literal> in
1070   your code.
1071 </para>
1072 </listitem>
1073
1074
1075 <listitem>
1076 <para>
1077 The <structname>GtkBox</structname>, <structname>GtkTable</structname>, and
1078   <structname>GtkAlignment</structname> widgets now call
1079   <literal>gtk_widget_set_redraw_on_allocate (widget, FALSE);</literal> on
1080   themselves. If you want to actually draw contents in a widget derived from
1081   one of these widgets, you'll probably want to change this
1082   in your <function>init()</function> function.
1083 </para>
1084 </listitem>
1085
1086
1087 <listitem>
1088 <para>
1089 A number of widgets are now <literal>NO_WINDOW</literal> widgets (most
1090   importantly <structname>GtkButton</structname>, but also
1091   <structname>GtkRange</structname> and <structname>GtkNotebook</structname>)
1092
1093   This has a couple of effects:
1094
1095 <itemizedlist>
1096  <listitem>
1097 <para>
1098 If you are deriving from one of these widgets, you need to
1099      adapt your code appropriately -- for instance, drawing coordinates
1100      start from <literal>widget-&gt;allocation.x, widget-&gt;allocation.y</literal>.
1101 </para>
1102 </listitem>
1103
1104
1105  <listitem>
1106 <para>
1107 If you are embedding one of these widgets in a custom widget,
1108      you must make sure you call <function>gtk_container_propagate_expose()</function>
1109      correctly, as you must for any <literal>NO_WINDOW</literal> widgets.
1110 </para>
1111 </listitem>
1112 </itemizedlist>
1113 </para>
1114
1115 <para>
1116   <structname>GtkFixed</structname> is a little special; it is now created by
1117   default as a <literal>NO_WINDOW</literal> widget, but if you do
1118
1119 <programlisting>
1120     gtk_fixed_set_has_window (fixed, TRUE);
1121 </programlisting>
1122
1123   after creating a fixed widget, it will create a window and
1124   handle it properly.
1125 </para>
1126 </listitem>
1127
1128 <listitem>
1129 <para>
1130 <structname>GtkLayout</structname> no longer has the <structfield>xoffset</structfield>,
1131   <structfield>yoffset</structfield> fields, which used to store the difference between
1132   world and window coordinates for <literal>layout-&gt;bin_window</literal>.
1133   These coordinate systems are now always the same.
1134 </para>
1135 </listitem>
1136
1137 <listitem>
1138 <para>
1139 <function>gtk_paint_focus()</function>, <function>gtk_draw_focus()</function>
1140   and <function>GtkStyle::draw_focus()</function>
1141   have been changed a bit:
1142
1143 <itemizedlist>
1144  <listitem>
1145 <para>
1146 A <literal>GtkStateType</literal> argument has been added to <function>gtk_paint_focus()</function>.
1147 </para>
1148 </listitem>
1149
1150  <listitem>
1151 <para>
1152 The default implementation of the <function>GtkStyle::draw_focus()</function>
1153      virtual function now draws a focus rectangle whose width is
1154      determined by the GtkWidget::focus-width style property.
1155 </para>
1156 </listitem>
1157
1158  <listitem>
1159 <para>
1160 The rectangle passed in is the bounding box, instead of
1161      the rectangle used in the <function>gdk_draw_rectangle()</function> call,
1162      so it is no longer necessary to subtract 1 from the width and height.
1163 </para>
1164 </listitem>
1165
1166 </itemizedlist>
1167
1168 </para>
1169 </listitem>
1170
1171
1172 </itemizedlist>
1173
1174 </refsect1>
1175
1176 </refentry>