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