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 cols="2">
  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 cols="2">
 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 </para>
 153 </listitem>
 154
 155
 156 <listitem>
 157 <para>
 158 Additionally, all <function>gtk_*_interp()</function> functions were removed.
 159   <function>gtk_*_full()</function> versions were provided as of GTK+ 1.0 and
 160   should be used instead.
 161 </para>
 162 </listitem>
 163
 164 <listitem>
 165 <para>
 166 <structname>GtkButton</structname> has been changed to derive from
 167 <structname>GtkBin</structname>.
 168   To access a button's child, use <literal>GTK_BIN (button)-&gt;child</literal>,
 169   instead of the old <literal>GTK_BUTTON (button)-&gt;child</literal>.
 170 </para>
 171 </listitem>
 172
 173 <listitem>
 174 <para>
 175 The selection API has been slightly modified:
 176
 177  <function>gtk_selection_add_handler()</function> and
 178  <function>gtk_selection_add_handler_full()</function>
 179  have been removed. To supply the selection, one now registers
 180  the targets one is interested in with:
 181
 182 <programlisting>
 183   void gtk_selection_add_target (GtkWidget           *widget,
 184                                  GdkAtom              selection,
 185                                  GdkAtom              target,
 186                                  guint                info);
 187 </programlisting>
 188
 189  or:
 190
 191 <programlisting>
 192   void gtk_selection_add_targets (GtkWidget           *widget,
 193                                   GdkAtom              selection,
 194                                   GtkTargetEntry      *targets,
 195                                   guint                ntargets);
 196 </programlisting>
 197
 198  When a request for a selection is received, the new "selection_get"
 199  signal will be called:
 200
 201 <programlisting>
 202    void  "selection_get"           (GtkWidget          *widget,
 203                                     GtkSelectionData   *selection_data,
 204                                     guint               info,
 205                                     guint               time);
 206 </programlisting>
 207
 208  A "time" parameter has also been added to the "selection_received"
 209  signal.
 210
 211 <programlisting>
 212   void  "selection_received"       (GtkWidget          *widget,
 213                                     GtkSelectionData   *selection_data,
 214                                     guint               time);
 215 </programlisting>
 216 </para>
 217 </listitem>
 218
 219 <listitem>
 220 <para>
 221 The old drag and drop API has been completely removed and replaced.
 222   See the reference documentation for details on the new API.
 223 </para>
 224 </listitem>
 225
 226 <listitem>
 227 <para>
 228 Support for Themes has been added. In general, this does
 229   not affect application code, however, a few new rules should
 230   be observed:
 231
 232   <itemizedlist>
 233   <listitem>
 234   <para>To set a shape for a window, you must use
 235      <function>gtk_widget_shape_combine_mask()</function> instead of
 236      <function>gdk_window_shape_combine_mask()</function>, or the shape will be
 237      reset when switching themes.
 238   </para>
 239   </listitem>
 240
 241   <listitem>
 242   <para>It is no longer permissable to draw directly on an arbitrary
 243      widget, or to set an arbitrary widget's background pixmap.
 244      If you need to do that, use a <structname>GtkDrawingArea</structname> or
 245      (for a toplevel) a <structname>GtkWindow</structname> where
 246      <function>gtk_widget_set_app_paintable()</function>
 247      has been called.
 248   </para>
 249   </listitem>
 250   </itemizedlist>
 251 </para>
 252 </listitem>
 253
 254 <listitem>
 255 <para>
 256 The <structname>GtkScrolledWindow</structname> widget no longer creates a
 257   <structname>GtkViewport</structname> automatically. Instead, it has been
 258   generalized to accept any "self-scrolling" widget.
 259 </para>
 260
 261 <para>
 262   The self-scrolling widgets in the GTK+ core are
 263   <structname>GtkViewport</structname>,
 264   <structname>GtkCList</structname>, <structname>GtkCTree</structname>,
 265   <structname>GtkText</structname>, and <structname>GtkLayout</structname>.
 266   All of these widgets can be added to a scrolled window as normal children with
 267   <function>gtk_container_add()</function> and scrollbars will be set up
 268   automatically.
 269 </para>
 270
 271 <para>
 272   To add scrollbars to a non self-scrolling widget, (such as a
 273   <structname>GtkList</structname>),
 274   first add it to a viewport, then add the viewport to a scrolled window.
 275   The scrolled window code provides a convenience function to do this:
 276
 277 <programlisting>
 278   void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
 279                                               GtkWidget         *child);
 280 </programlisting>
 281
 282   This does exactly what it says - it creates a viewport, adds the child
 283   widget to it, then adds the viewport to the scrolled window.
 284 </para>
 285
 286 <para>
 287   The scrollbars have been removed from the <structname>GtkCList</structname>
 288   and <structname>GtkCTree</structname>, because they are now scrolled by simply
 289   adding them to a scrolled window. The scrollbar policy is set on the scrolled
 290   window with <function>gtk_scrolled_window_set_policy()</function> and not on
 291   the child widgets (e.g. <structname>GtkCList</structname>'s
 292   <function>gtk_clist_set_policy()</function> was removed).
 293 </para>
 294 </listitem>
 295
 296 <listitem>
 297 <para>
 298 The "main loop" of GTK+ has been moved to GLib. This should not
 299   affect existing programs, since compatibility functions have
 300   been provided. However, you may want to consider migrating
 301   your code to use the GLib main loop directly.
 302 </para>
 303 </listitem>
 304
 305 <listitem>
 306 <para>
 307 the <literal>GTK_BASIC</literal> flag was removed, and with it the corresponding
 308   macro and function <function>GTK_WIDGET_BASIC()</function> and
 309   <function>gtk_widget_basic()</function>.
 310 </para>
 311 </listitem>
 312
 313 <listitem>
 314 <para>
 315 All freeze/thaw methods are now recursive - that is, if you
 316   freeze a widget n times, you must also thaw it n times.
 317
 318   Therefore, if you have code like:
 319
 320 <informalexample><programlisting>
 321   gboolean frozen;
 322   frozen = GTK_CLIST_FROZEN (clist);
 323   gtk_clist_freeze (clist);
 324   [...]
 325   if (!frozen)
 326     gtk_clist_thaw (clist);
 327 </programlisting></informalexample>
 328
 329   it will not work anymore. It must be, simply:
 330
 331 <informalexample><programlisting>
 332   gtk_clist_freeze (clist);
 333   [...]
 334   gtk_clist_thaw (clist);
 335 </programlisting></informalexample>
 336 </para>
 337 </listitem>
 338
 339 <listitem>
 340 <para>
 341 The thread safety in GTK+ 1.2 is slightly different than
 342   that which appeared in early versions in the 1.1
 343   development track. The main difference is that it relies on
 344   the thread primitives in GLib, and on the thread-safe
 345   GLib main loop.
 346 </para>
 347
 348 <para>
 349   This means:
 350
 351 <itemizedlist>
 352    <listitem>
 353      <para>You must call <function>g_thread_init()</function> before
 354        executing any other GTK+ or GDK functions in a threaded GTK+ program.
 355      </para>
 356    </listitem>
 357
 358    <listitem>
 359      <para>Idles, timeouts, and input functions are executed outside
 360        of the main GTK+ lock. So, if you need to call GTK+
 361        inside of such a callback, you must surround the callback
 362        with a <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
 363        pair.
 364      </para>
 365
 366      <para>However, signals are still executed within the main
 367        GTK+ lock.
 368      </para>
 369
 370      <para>In particular, this means, if you are writing widgets
 371        that might be used in threaded programs, you <emphasis>must</emphasis>
 372        surround timeouts and idle functions in this matter.
 373      </para>
 374
 375      <para>As always, you must also surround any calls to GTK+
 376        not made within a signal handler with a
 377        <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
 378        pair.
 379      </para>
 380    </listitem>
 381
 382    <listitem>
 383      <para>There is no longer a special <option>--with-threads</option>
 384        <command>configure</command> option for GTK+. To use threads in a GTK+
 385        program, you must:
 386
 387        <orderedlist>
 388          <listitem>
 389            <para>If you want to use the native thread implementation,
 390               make sure GLib found this in configuration, otherwise,
 391               call you must provide a thread implementation to
 392               <function>g_thread_init()</function>.
 393            </para>
 394          </listitem>
 395          <listitem>
 396            <para>Link with the libraries returned by
 397              <command>gtk-config --libs gthread</command>
 398              and use the cflags from
 399              <command>gtk-config --cflags gthread</command>.
 400              You can get these <envar>CFLAGS</envar> and <envar>LIBS</envar> by
 401              passing <literal>gthread</literal> as the fourth parameter to the
 402              <literal>AM_PATH_GTK</literal> <application>automake</application>
 403              macro.
 404            </para>
 405          </listitem>
 406        </orderedlist>
 407      </para>
 408    </listitem>
 409   </itemizedlist>
 410 </para>
 411 </listitem>
 412
 413 <listitem>
 414 <para>
 415 Prior to GTK+ 1.2, there were two conflicting interpretations
 416   of <literal>widget->requisition</literal>. It was either taken to be
 417   the size that the widget requested, or that size modified by calls to
 418   <function>gtk_widget_set_usize()</function>. In GTK+ 1.2,
 419   it is always interpreted the first way.
 420 </para>
 421
 422 <para>
 423   Container widgets are affected in two ways by this:
 424
 425   <orderedlist>
 426     <listitem>
 427       <para>Container widgets should not pass
 428         <literal>widget->requisition</literal> as the second parameter to
 429         <function>gtk_widget_size_request()</function>.
 430         Instead they should call it like:
 431         <programlisting>
 432           GtkRequisition child_requisition;
 433           gtk_widget_size_request (widget, &amp;child_requisition);
 434         </programlisting>
 435       </para>
 436     </listitem>
 437     <listitem>
 438       <para>Container widgets should not access
 439         <literal>child->requisition</literal> directly. Either they should use
 440         the values returned by <function>gtk_widget_size_request()</function>,
 441         or they should call the new function:
 442         <programlisting>
 443     void gtk_widget_get_child_requisition (GtkWidget      *widget,
 444                                            GtkRequisition *requisition);
 445         </programlisting>
 446         which returns the requisition of the given widget, modified
 447         by calls to <function>gtk_widget_set_usize()</function>.
 448       </para>
 449     </listitem>
 450   </orderedlist>
 451 </para>
 452 </listitem>
 453
 454
 455 </itemizedlist>
 456
 457 </refsect1>
 458
 459 </refentry>
 460