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

   1 <refentry id="gtk-changes-1-2" revision="1 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Changes from 1.0 to 1.2</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Changes from 1.0 to 1.2</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Changes from 1.0 to 1.2</refname>
  10 <refpurpose>
  11 Incompatible changes made between version 1.0 and version 1.2
  12 </refpurpose>
  13 </refnamediv>
  14
  15
  16 <refsect1>
  17 <title>Incompatible changes from 1.0 to 1.2</title>
  18
  19 <itemizedlist>
  20
  21 <listitem>
  22 <para>
  23 <structname>GtkAcceleratorTable</structname> has been replaced with
  24 <structname>GtkAccelGroup</structname>.
  25 </para>
  26 </listitem>
  27
  28 <listitem>
  29 <para>
  30 <structname>GtkMenuFactory</structname> has been replaced with
  31 <structname>GtkItemFactory</structname>, although
  32 a version of <structname>GtkMenuFactory</structname> is currently still
  33 provided to ease the migration phase.
  34 </para>
  35 </listitem>
  36
  37 <listitem>
  38 <para>
  39 The <structname>GtkTypeInfo</structname> structures used in the
  40 <function>gtk_*_type_init()</function> functions have
  41 changed a bit, the old format:
  42 <programlisting>
  43       GtkTypeInfo bin_info =
  44       {
  45         "GtkBin",
  46         sizeof (GtkBin),
  47         sizeof (GtkBinClass),
  48         (GtkClassInitFunc) gtk_bin_class_init,
  49         (GtkObjectInitFunc) gtk_bin_init,
  50         (GtkArgSetFunc) NULL,
  51         (GtkArgGetFunc) NULL,
  52       };
  53 </programlisting>
  54
  55   needs to be converted to:
  56
  57 <programlisting>
  58       static const GtkTypeInfo bin_info =
  59       {
  60         "GtkBin",
  61         sizeof (GtkBin),
  62         sizeof (GtkBinClass),
  63         (GtkClassInitFunc) gtk_bin_class_init,
  64         (GtkObjectInitFunc) gtk_bin_init,
  65         /* reserved_1 */ NULL,
  66         /* reserved_2 */ NULL,
  67         (GtkClassInitFunc) NULL,
  68       };
  69 </programlisting>
  70
  71   the <function>GtkArgSetFunc</function> and <function>GtkArgGetFunc</function>
  72   functions are not supported from the type system anymore, and you should make
  73   sure that your code only fills in these fields with <literal>NULL</literal>
  74   and doesn't use the deprecated function typedefs
  75   <literal>(GtkArgSetFunc)</literal> and <literal>(GtkArgGetFunc)</literal>
  76   anymore.
  77 </para>
  78 </listitem>
  79
  80 <listitem>
  81 <para>
  82 A number of GTK+ functions were renamed. For compatibility,
  83   <filename>gtkcompat.h</filename> #define's the old 1.0.x function names in
  84   terms of the new names. To assure your GTK+ program doesn't rely on outdated
  85   function variants, compile your program with
  86   <option>-DGTK_DISABLE_COMPAT_H</option> to disable
  87   the compatibility aliases.
  88
  89   Here is the list of the old names and replacements:
  90
  91 <informaltable>
  92 <tgroup>
  93 <thead>
  94 <row><entry>Old</entry><entry>Replacement</entry></row>
  95 </thead>
  96 <tbody>
  97 <row><entry><function>gtk_accel_label_accelerator_width</function></entry><entry><function>gtk_accel_label_get_accel_width</function></entry></row>
  98 <row><entry><function>gtk_check_menu_item_set_state</function></entry><entry><function>gtk_check_menu_item_set_active</function></entry></row>
  99 <row><entry><function>gtk_container_border_width</function></entry><entry><function>gtk_container_set_border_width</function></entry></row>
 100 <row><entry><function>gtk_label_set</function></entry><entry><function>gtk_label_set_text</function></entry></row>
 101 <row><entry><function>gtk_notebook_current_page</function></entry><entry><function>gtk_notebook_get_current_page</function></entry></row>
 102 <row><entry><function>gtk_packer_configure</function></entry><entry><function>gtk_packer_set_child_packing</function></entry></row>
 103 <row><entry><function>gtk_paned_gutter_size</function></entry><entry><function>gtk_paned_set_gutter_size</function></entry></row>
 104 <row><entry><function>gtk_paned_handle_size</function></entry><entry><function>gtk_paned_set_handle_size</function></entry></row>
 105 <row><entry><function>gtk_scale_value_width</function></entry><entry><function>gtk_scale_get_value_width</function></entry></row>
 106 <row><entry><function>gtk_style_apply_default_pixmap</function></entry><entry><function>gtk_style_apply_default_background</function></entry></row>
 107 <row><entry><function>gtk_toggle_button_set_state</function></entry><entry><function>gtk_toggle_button_set_active</function></entry></row>
 108 <row><entry><function>gtk_window_position</function></entry><entry><function>gtk_window_set_position</function></entry></row>
 109 </tbody>
 110 </tgroup>
 111 </informaltable>
 112 Note that <function>gtk_style_apply_default_background()</function> has an
 113       additional argument, <literal>set_bg</literal>. This parameter should be
 114       <literal>FALSE</literal> if the background is being set for a
 115       <literal>NO_WINDOW</literal> widget, otherwise <literal>TRUE</literal>.
 116 </para>
 117 </listitem>
 118
 119 <listitem>
 120 <para>
 121 During the development phase of the 1.1.x line of GTK+ certain functions
 122   were deprecated and later removed. Functions affected are:
 123
 124 <informaltable>
 125 <tgroup>
 126 <thead>
 127 <row><entry>Removed</entry><entry>Replacement</entry></row>
 128 </thead>
 129 <tbody>
 130 <row><entry><function>gtk_clist_set_border</function></entry><entry><function>gtk_clist_set_shadow_type</function></entry></row>
 131 <row><entry><function>gtk_container_block_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
 132 <row><entry><function>gtk_container_unblock_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
 133 <row><entry><function>gtk_container_need_resize</function></entry><entry><function>gtk_container_check_resize</function></entry></row>
 134 <row><entry><function>gtk_ctree_show_stub</function></entry><entry><function>gtk_ctree_set_show_stub</function></entry></row>
 135 <row><entry><function>gtk_ctree_set_reorderable</function></entry><entry><function>gtk_clist_set_reorderable</function></entry></row>
 136 <row><entry><function>gtk_ctree_set_use_drag_icons</function></entry><entry><function>gtk_clist_set_use_drag_icons</function></entry></row>
 137 <row><entry><function>gtk_entry_adjust_scroll</function></entry><entry><function>-</function></entry></row>
 138 <row><entry><function>gtk_object_class_add_user_signal</function></entry><entry><function>gtk_object_class_user_signal_new</function></entry></row>
 139 <row><entry><function>gtk_preview_put_row</function></entry><entry><function>gtk_preview_put</function></entry></row>
 140 <row><entry><function>gtk_progress_bar_construct</function></entry><entry><function>gtk_progress_set_adjustment</function></entry></row>
 141 <row><entry><function>gtk_scrolled_window_construct</function></entry><entry><function>gtk_scrolled_window_set_{h|v}adjustment</function></entry></row>
 142 <row><entry><function>gtk_spin_button_construct</function></entry><entry><function>gtk_spin_button_configure</function></entry></row>
 143 <row><entry><function>gtk_widget_thaw_accelerators</function></entry><entry><function>gtk_widget_unlock_accelerators</function></entry></row>
 144 <row><entry><function>gtk_widget_freeze_accelerators</function></entry><entry><function>gtk_widget_lock_accelerators</function></entry></row>
 145 </tbody>
 146 </tgroup>
 147 </informaltable>
 148
 149 Note that <function>gtk_entry_adjust_scroll()</function> is no longer needed
 150     as <structname>GtkEntry</structname> should automatically keep the scroll
 151     adjusted properly.
 152 </programlisting>
 153 </para>
 154 </listitem>
 155
 156
 157 <listitem>
 158 <para>
 159 Additionally, all <function>gtk_*_interp()</function> functions were removed.
 160   <function>gtk_*_full()</function> versions were provided as of GTK+ 1.0 and
 161   should be used instead.
 162 </para>
 163 </listitem>
 164
 165 <listitem>
 166 <para>
 167 <structname>GtkButton</structname> has been changed to derive from
 168 <structname>GtkBin</structname>.
 169   To access a button's child, use <literal>GTK_BIN (button)-&gt;child</literal>,
 170   instead of the old <literal>GTK_BUTTON (button)-&gt;child</literal>.
 171 </para>
 172 </listitem>
 173
 174 <listitem>
 175 <para>
 176 The selection API has been slightly modified:
 177
 178  <function>gtk_selection_add_handler()</function> and
 179  <function>gtk_selection_add_handler_full()</function>
 180  have been removed. To supply the selection, one now registers
 181  the targets one is interested in with:
 182
 183 <programlisting>
 184   void gtk_selection_add_target (GtkWidget           *widget,
 185                                  GdkAtom              selection,
 186                                  GdkAtom              target,
 187                                  guint                info);
 188 </programlisting>
 189
 190  or:
 191
 192 <programlisting>
 193   void gtk_selection_add_targets (GtkWidget           *widget,
 194                                   GdkAtom              selection,
 195                                   GtkTargetEntry      *targets,
 196                                   guint                ntargets);
 197 </programlisting>
 198
 199  When a request for a selection is received, the new "selection_get"
 200  signal will be called:
 201
 202 <programlisting>
 203    void  "selection_get"           (GtkWidget          *widget,
 204                                     GtkSelectionData   *selection_data,
 205                                     guint               info,
 206                                     guint               time);
 207 </programlisting>
 208
 209  A "time" parameter has also been added to the "selection_received"
 210  signal.
 211
 212 <programlisting>
 213   void  "selection_received"       (GtkWidget          *widget,
 214                                     GtkSelectionData   *selection_data,
 215                                     guint               time);
 216 </programlisting>
 217 </para>
 218 </listitem>
 219
 220 <listitem>
 221 <para>
 222 The old drag and drop API has been completely removed and replaced.
 223   See the reference documentation for details on the new API.
 224 </para>
 225 </listitem>
 226
 227 <listitem>
 228 <para>
 229 Support for Themes has been added. In general, this does
 230   not affect application code, however, a few new rules should
 231   be observed:
 232
 233   <itemizedlist>
 234   <listitem>
 235   <para>To set a shape for a window, you must use
 236      <function>gtk_widget_shape_combine_mask()</function> instead of
 237      <function>gdk_window_shape_combine_mask()</function>, or the shape will be
 238      reset when switching themes.
 239   </para>
 240   </listitem>
 241
 242   <listitem>
 243   <para>It is no longer permissable to draw directly on an arbitrary
 244      widget, or to set an arbitrary widget's background pixmap.
 245      If you need to do that, use a <structname>GtkDrawingArea</structname> or
 246      (for a toplevel) a <structname>GtkWindow</structname> where
 247      <function>gtk_widget_set_app_paintable()</function>
 248      has been called.
 249   </para>
 250   </listitem>
 251   </itemizedlist>
 252 </para>
 253 </listitem>
 254
 255 <listitem>
 256 <para>
 257 The <structname>GtkScrolledWindow</structname> widget no longer creates a
 258   <structname>GtkViewport</structname> automatically. Instead, it has been
 259   generalized to accept any "self-scrolling" widget.
 260 </para>
 261
 262 <para>
 263   The self-scrolling widgets in the GTK+ core are
 264   <structname>GtkViewport</structname>,
 265   <structname>GtkCList</structname>, <structname>GtkCTree</structname>,
 266   <structname>GtkText</structname>, and <structname>GtkLayout</structname>.
 267   All of these widgets can be added to a scrolled window as normal children with
 268   <function>gtk_container_add()</function> and scrollbars will be set up
 269   automatically.
 270 </para>
 271
 272 <para>
 273   To add scrollbars to a non self-scrolling widget, (such as a
 274   <structname>GtkList</structname>),
 275   first add it to a viewport, then add the viewport to a scrolled window.
 276   The scrolled window code provides a convenience function to do this:
 277
 278 <programlisting>
 279   void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
 280                                               GtkWidget         *child);
 281 </programlisting>
 282
 283   This does exactly what it says - it creates a viewport, adds the child
 284   widget to it, then adds the viewport to the scrolled window.
 285 </para>
 286
 287 <para>
 288   The scrollbars have been removed from the <structname>GtkCList</structname>
 289   and <structname>GtkCTree</structname>, because they are now scrolled by simply
 290   adding them to a scrolled window. The scrollbar policy is set on the scrolled
 291   window with <function>gtk_scrolled_window_set_policy()</function> and not on
 292   the child widgets (e.g. <structname>GtkCList</structname>'s
 293   <function>gtk_clist_set_policy()</function> was removed).
 294 </para>
 295 </listitem>
 296
 297 <listitem>
 298 <para>
 299 The "main loop" of GTK+ has been moved to GLib. This should not
 300   affect existing programs, since compatibility functions have
 301   been provided. However, you may want to consider migrating
 302   your code to use the GLib main loop directly.
 303 </para>
 304 </listitem>
 305
 306 <listitem>
 307 <para>
 308 the <literal>GTK_BASIC</literal> flag was removed, and with it the corresponding
 309   macro and function <function>GTK_WIDGET_BASIC()</function> and
 310   <function>gtk_widget_basic()</function>.
 311 </para>
 312 </listitem>
 313
 314 <listitem>
 315 <para>
 316 All freeze/thaw methods are now recursive - that is, if you
 317   freeze a widget n times, you must also thaw it n times.
 318
 319   Therefore, if you have code like:
 320
 321 <informalexample><programlisting>
 322   gboolean frozen;
 323   frozen = GTK_CLIST_FROZEN (clist);
 324   gtk_clist_freeze (clist);
 325   [...]
 326   if (!frozen)
 327     gtk_clist_thaw (clist);
 328 </programlisting></informalexample>
 329
 330   it will not work anymore. It must be, simply:
 331
 332 <informalexample><programlisting>
 333   gtk_clist_freeze (clist);
 334   [...]
 335   gtk_clist_thaw (clist);
 336 </programlisting></informalexample>
 337 </para>
 338 </listitem>
 339
 340 <listitem>
 341 <para>
 342 The thread safety in GTK+ 1.2 is slightly different than
 343   that which appeared in early versions in the 1.1
 344   development track. The main difference is that it relies on
 345   the thread primitives in GLib, and on the thread-safe
 346   GLib main loop.
 347 </para>
 348
 349 <para>
 350   This means:
 351
 352 <itemizedlist>
 353    <listitem>
 354      <para>You must call <function>g_thread_init()</function> before
 355        executing any other GTK+ or GDK functions in a threaded GTK+ program.
 356      </para>
 357    </listitem>
 358
 359    <listitem>
 360      <para>Idles, timeouts, and input functions are executed outside
 361        of the main GTK+ lock. So, if you need to call GTK+
 362        inside of such a callback, you must surround the callback
 363        with a <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
 364        pair.
 365      </para>
 366
 367      <para>However, signals are still executed within the main
 368        GTK+ lock.
 369      </para>
 370
 371      <para>In particular, this means, if you are writing widgets
 372        that might be used in threaded programs, you <emphasis>must</emphasis>
 373        surround timeouts and idle functions in this matter.
 374      </para>
 375
 376      <para>As always, you must also surround any calls to GTK+
 377        not made within a signal handler with a
 378        <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
 379        pair.
 380      </para>
 381    </listitem>
 382
 383    <listitem>
 384      <para>There is no longer a special <option>--with-threads</option>
 385        <command>configure</command> option for GTK+. To use threads in a GTK+
 386        program, you must:
 387
 388        <orderedlist>
 389          <listitem>
 390            <para>If you want to use the native thread implementation,
 391               make sure GLib found this in configuration, otherwise,
 392               call you must provide a thread implementation to
 393               <function>g_thread_init()</function>.
 394            </para>
 395          </listitem>
 396          <listitem>
 397            <para>Link with the libraries returned by
 398              <command>gtk-config --libs gthread</command>
 399              and use the cflags from
 400              <command>gtk-config --cflags gthread</command>.
 401              You can get these <envar>CFLAGS</envar> and <envar>LIBS</envar> by
 402              passing <literal>gthread</literal> as the fourth parameter to the
 403              <literal>AM_PATH_GTK</literal> <application>automake</application>
 404              macro.
 405            </para>
 406          </listitem>
 407        </orderedlist>
 408      </para>
 409    </listitem>
 410   </itemizedlist>
 411 </para>
 412 </listitem>
 413
 414 <listitem>
 415 <para>
 416 Prior to GTK+ 1.2, there were two conflicting interpretations
 417   of <literal>widget->requisition</literal>. It was either taken to be
 418   the size that the widget requested, or that size modified by calls to
 419   <function>gtk_widget_set_usize()</function>. In GTK+ 1.2,
 420   it is always interpreted the first way.
 421 </para>
 422
 423 <para>
 424   Container widgets are affected in two ways by this:
 425
 426   <orderedlist>
 427     <listitem>
 428       <para>Container widgets should not pass
 429         <literal>widget->requisition</literal> as the second parameter to
 430         <function>gtk_widget_size_request()</function>.
 431         Instead they should call it like:
 432         <programlisting>
 433           GtkRequisition child_requisition;
 434           gtk_widget_size_request (widget, &amp;child_requisition);
 435         </programlisting>
 436       </para>
 437     </listitem>
 438     <listitem>
 439       <para>Container widgets should not access
 440         <literal>child->requisition</literal> directly. Either they should use
 441         the values returned by <function>gtk_widget_size_request()</function>,
 442         or they should call the new function:
 443         <programlisting>
 444     void gtk_widget_get_child_requisition (GtkWidget      *widget,
 445                                            GtkRequisition *requisition);
 446         </programlisting>
 447         which returns the requisition of the given widget, modified
 448         by calls to <function>gtk_widget_set_usize()</function>.
 449       </para>
 450     </listitem>
 451   </orderedlist>
 452 </para>
 453 </listitem>
 454
 455
 456 </itemizedlist>
 457
 458 </refsect1>
 459
 460 </refentry>
 461