1 <refentry id="gtk-changes-2-0" revision="1 Jan 2002">
3 <refentrytitle>Changes from 1.2 to 2.0</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>Changes from 1.2 to 2.0</refmiscinfo>
9 <refname>Changes from 1.2 to 2.0</refname>
11 Incompatible changes made between version 1.2 and version 2.0
17 <title>Incompatible changes from 1.2 to 2.0</title>
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+.
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.
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).
53 The <function>gdk_time*</function> functions have been removed. This
54 functionality has been unused since the main loop was moved into GLib
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.
70 The detail arguments in the <structname>GtkStyleClass</structname> structure
71 are now <type>const gchar *</type>.
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.
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
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.
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>.
111 <function>gtk_widget_shape_combine_mask()</function> now keeps a reference
112 count on the mask pixmap that is passed in.
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>.
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>
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.
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>.
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.
165 The following type functions vanished/were replaced:
169 <row><entry>Old Function</entry><entry>Replacement</entry></row>
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><functiono>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
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>.
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:
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_<OBJECT>_GET_CLASS (object)</literal>
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.
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)
227 GtkLabel *label = GTK_LABEL (gobject);
229 G_OBJECT_CLASS (parent_class)->finalize (object);
231 static void gtk_label_class_init (GtkLabelClass *class)
233 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
235 gobject_class->finalize = gtk_label_finalize;
237 </programlisting></informalexample>
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->foo_data)
254 g_free (object->foo_data);
255 object->foo_data = NULL;
257 </programlisting></informalexample>
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->adjustment)
264 gtk_object_unref (object->adjustment);
265 object->adjustment = NULL;
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
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.
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
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.
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.
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>.
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.
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
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>.
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.
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.
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->klass->xthickness/style->xthickness/g</literal> and
386 same for <literal>ythickness</literal>.
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.
401 If you were using private GDK types, they have been rearranged
402 significantly. You shouldn't use private types. ;-)
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.
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>.
429 <row><entry>Old function</entry><entry>Defined As</entry></row>
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>
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.)
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>.
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>.
478 <structname>GtkProgress</structname>/<structname>GtkProgressBar</structname>
479 had serious problems in GTK+ 1.2.
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.
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.
500 You set the activity step as a pixel value, which means to
501 set the activity step you basically need to connect to
508 There are <function>ctree_set_expander_style()</function>-functions, to
509 randomly change look-and-feel for no good reason.
515 The split between <structname>GtkProgress</structname> and
516 <structname>GtkProgressBar</structname> makes no sense to me whatsoever.
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:
530 void gtk_progress_bar_pulse (GtkProgressBar *pbar);
531 void gtk_progress_bar_set_text (GtkProgressBar *pbar,
533 void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
536 void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
538 void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
539 GtkProgressBarOrientation orientation);
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.
556 <function>GtkMenuPositionFunc</function> has a new parameter
557 <literal>push_in</literal> which controls how menus placed outside the
558 screen is handled. If this is set to <literal>TRUE</literal> and
559 part of the menu is outside the screen then GTK+ pushes it into the visible
560 area. Otherwise the menu is cut of at the end of the visible screen area.
563 Regardless of what happens to the size of the menu, the result is always
564 that the items are placed in the same place as if the menu was placed
565 outside the screen, using menu scrolling if necessary.
571 The "draw" signal and virtual method on <structname>GtkWidget</structname>
573 All drawing should now occur by invalidating a region of the widget
574 (call <function>gdk_window_invalidate_rect()</function> or
575 <function>gtk_widget_queue_draw()</function> for example to invalidate
576 a region). GTK+ merges all invalid regions, and sends expose events to
577 the widget in an idle handler for the invalid regions.
578 <function>gtk_widget_draw()</function> is deprecated but still works; it
579 adds the passed-in area to the invalid region and immediately sends
580 expose events for the current invalid region.
581 Most widgets will work fine if you just delete their "draw"
582 implementation, since they will already have working expose_event
583 implementations. The draw method was rarely called in practice
590 The <structname>GdkExposeEvent</structname> has a new <structfield>region</structfield>
591 field. This can be used instead of the <structfield>area</structfield> field if you
592 want a more exact representation of the area to update.
598 Sending synthetic exposes using <function>gtk_widget_event()</function> is no
599 longer allowed. If you just need an expose call you should use
600 <function>gdk_window_invalidate_rect()</function> or
601 <function>gdk_window_invalidate_region()</function> instead. For the case
602 of container widgets that need to propagate expose events to
603 <literal>NO_WINDOW</literal> children you can either use
604 <function>gtk_container_propagate_expose()</function>, or chain to the
605 default container expose handler.
611 The draw_default and draw_focus methods/signals on
612 <structname>GtkWidget</structname> are gone; simply draw things in your
613 expose handler. <function>gtk_widget_draw_focus()</function> and
614 <function>gtk_widget_draw_default()</function> wrapper
615 functions are also gone; just queue a draw on the widget,
616 or the part affected by the focus/default anyway.
617 Also, <structname>GtkWidget</structname> now has default implementations for
618 focus_in_event and focus_out_event. These set/unset
619 <literal>GTK_HAS_FOCUS</literal>, and queue a draw. So if your focus in/out
620 handler just does that, you can delete it.
626 <structname>GtkText</structname> and <structname>GtkTree</structname> are
627 buggy and broken. We don't recommend using them, and changing old code to
628 avoid them is a good idea. The recommended alternatives are
629 <structname>GtkTextView</structname> and <structname>GtkTreeView</structname>.
630 The broken widgets are not declared in the headers by default; to use
631 them, define the symbol <literal>GTK_ENABLE_BROKEN</literal> during
632 compilation. In some future release, these widgets will be removed from GTK+.
638 <structname>GdkColorContext</structname> is gone; you probably weren't using
639 it anyway. Use <structname>GdkColormap</structname> and the
640 <function>gdk_rgb_*</function> functions instead.
646 <structname>GtkMenuBar</structname> now draws the <structfield>GtkContainer::border_width</structfield>
647 space outside the frame, not inside the frame.
654 In GTK+ 1.2, if an event handler returned <literal>TRUE</literal> it prevented
655 propagation of that event to parent widgets. That is, the
656 event signal would not be emitted on parent widgets. In
657 GTK+ 2.0, if an event handler returns <literal>TRUE</literal>, the current
658 signal emission on the current widget is immediately stopped. That is,
659 other callbacks connected to the signal will not be invoked.
665 <function>gtk_toolbar_new()</function> no longer has arguments. This function
666 was broken because the default <literal>GtkToolbarStyle</literal> (icons,
667 text, both) is now a user preference, which is overridden when you call
668 <function>gtk_toolbar_set_style()</function>. The constructor forced everyone
669 to override the preference, which was undesirable. So to port
670 your app, decide if you want to force the toolbar style
671 or conform to the user's global defaults; if you want to force
672 it, call <function>gtk_toolbar_set_style()</function>.
676 The orientation arg was removed from <function>gtk_toolbar_new()</function>
677 as well, just because it wasn't very useful and we were breaking the function
678 anyway so had an opportunity to lose it. Call
679 <function>gtk_toolbar_set_orientation()</function> to set toolbar orientation.
686 <structname>GtkRange</structname>/</structname>GtkScrollbar</structname>/<structname>GtkScale</structname> were rewritten; this means that most
687 theme engines won't draw them properly, and any custom subclasses of
688 these widgets will need a rewrite (though if you could figure out
689 how to subclass the old version of <structname>GtkRange</structname>, you
690 have our respect). Also, <literal>GtkTroughType</literal> is gone.
696 The GtkContainer::focus signal/virtual function and
697 <function>gtk_container_focus()</function> call were replaced by
698 GtkWidget::focus and <function>gtk_widget_child_focus()</function>.
699 The semantics are the same, so you should be able to just
700 replace <literal>container_class->focus = mywidget_focus</literal> with
701 <literal>widget_class->focus = mywidget_focus</literal> and replace
702 <function>gtk_container_focus()</function> calls with
703 <function>gtk_widget_child_focus()</function> calls.
706 The purpose of this change was to allow non-containers to have
713 <function>gtk_rc_set_image_loader()</function> and
714 <function>gtk_rc_load_image()</function> have been removed, now
715 that GTK+ includes decent image loading capabilities itself.
721 An extra <structname>GtkSettings</structname> argument has been added to
722 <function>gtk_rc_find_pixmap_in_path()</function>. This function is only
723 actually useful from a theme engine during parsing, at which point the
724 <structname>GtkSettings</structname> is provided.
730 The child argument facility in <filename>gtkcontainer.c</filename> has been
731 converted to a child property facility using
732 <structname>GParamSpec</structname> and other facilities
733 for <structname>GObject</structname>.
739 The <function>set_child_arg()</function> and <function>get_child_arg()</function>
740 virtual methods have been replaced with <function>set_child_property()</function>/<function>get_child_property()</function>, which
741 work similar to GObject->set_property/get_property.
748 Other removed <structname>GtkContainer</structname> functions with the replacements:
753 <row><entry>Old function</entry><entry>Replacement</entry></row>
756 <row><entry><function>gtk_container_add_child_arg_type</function></entry><entry><function>gtk_container_class_install_child_property</function></entry></row>
757 <row><entry><function>gtk_container_query_child_args</function></entry><entry><function>gtk_container_class_list_child_properties</function></entry></row>
758 <row><entry><function>gtk_container_child_getv</function></entry><entry><function>gtk_container_child_set_property</function></entry></row>
759 <row><entry><function>gtk_container_child_setv</function></entry><entry><function>gtk_container_child_get_property</function></entry></row>
760 <row><entry><function>gtk_container_add_with_args</function></entry><entry><function>gtk_container_add_with_properties</function></entry></row>
761 <row><entry><function>gtk_container_addv</function></entry><entry><function>gtk_container_add</function>/<function>gtk_container_child_set_property</function></entry></row>
771 <function>gdk_image_get()</function> (or rather its replacement,
772 <function>gdk_drawable_get_image()</function>) now handles errors properly
773 by returning <literal>NULL</literal>, previously it would crash. Also, a
774 window being offscreen is no longer considered an error; instead, the area
775 contains undefined contents for the offscreen areas. In most cases, code
776 using <function>gdk_image_get()</function> should really be ported to
777 <function>gdk_pixbuf_get_from_drawable()</function>.
783 <function>gtk_widget_set_usize()</function> has been renamed to
784 <function>gtk_widget_set_size_request()</function>, however the old name
785 still exists unless you define <literal>GTK_DISABLE_DEPRECATED</literal>.
791 <function>gtk_widget_set_uposition()</function> is deprecated; use
792 <function>gtk_window_move()</function>,
793 <function>gtk_fixed_put()</function>, or <function>gtk_layout_put()</function>
800 <function>gtk_window_set_policy()</function> is deprecated. To get the effect of
802 <literal>gtk_widget_set_size_request (window, 0, 0)</literal>. To get the
803 effect of "allow_grow", call
804 <literal>gtk_window_set_resizable (window, TRUE)</literal>. You didn't want
805 the effect of "auto_shrink", it made no sense. But maybe if you were using
806 it you want to use <literal>gtk_window_resize (window, 1, 1)</literal> to
807 snap a window back to its minimum size (the 1, 1 will be rounded up to the
808 minimum window size).
814 The core GTK+ now takes care of handling mapping, unmapping and
815 realizing the child widgets of containers in
816 <function>gtk_widget_set_parent()</function>. In most cases, this allows
817 container implementations to be simplified by removing the code in
818 <function>add()</function> methods to map and realize children. However,
819 there are a couple of things to watch out for here:
826 If the parent is realized before the <function>add()</function> happens,
827 <function>gtk_widget_set_parent_window()</function> must be called before
828 <function>gtk_widget_set_parent()</function>, since
829 <function>gtk_widget_set_parent()</function> will realize the child.
835 If a container depended on its children not being mapped
836 unless it did so itself (for example, <structname>GtkNotebook</structname>
837 only mapped the current page), then the new function
838 <function>gtk_widget_set_child_visible()</function> must be called to keep
839 widgets that should not be mapped not mapped.
843 As part of this change, most containers also will no longer need custom
844 implementations of the <function>map()</function> and
845 <function>unmap()</function> virtual functions. The only cases where this
851 For <literal>!NO_WINDOW</literal> widgets, if you create children of
852 <literal>widget->window</literal>
853 and don't map them in <function>realize()</function> then you must map them
854 in <function>map()</function. [ In almost all cases, you can simply map the
855 windows in <function>realize()</function>. ]
861 For <literal>NO_WINDOW</literal> widgets, if you create windows in your
862 <function>realize()</function> method, you must map then in
863 <function>map()</function> and unmap them in <function>unmap()</function>.
872 <function>gtk_widget_set_default_style()</function>,
873 <function>gtk_widget_push_style()</function>,
874 and <function>gtk_widget_pop_style()</function> have been removed, since they
875 did not work properly with themes and there were better
876 alternatives for modifying the appearance of widgets.
878 You should generally use <function>gtk_widget_modify_*()</function>
886 <function>gtk_image_new()</function> now takes no arguments and creates an
887 empty <structname>GtkImage</structname> widget. To create a
888 <structname>GtkImage</structname> widget from a
889 <structname>GdkImage</structname> (the least
890 common usage of <structname>GdkImage</structname>), use
891 <function>gtk_image_new_from_image()</function>.
897 <literal>GTK_SELECTION_EXTENDED</literal> is now deprecated, and neither the
898 <structname>GtkList</structname>/<structname>GtkTree</structname> nor the
899 <structname>GtkCList</structname>/<structname>GtkCTree</structname> support
900 <literal>GTK_SELECTION_EXTENDED</literal> anymore. However, the old extended
901 behavior replaces <literal>MULTIPLE</literal> behavior.
907 The following variables are no longer exported from GDK. (Other variables
908 are also no longer exported; the following are the ones found used
909 externally in a large sample of GTK+ code.)
914 <row><entry>Variable</entry><entry>Replacement</entry></row>
917 <row><entry><literal>gdk_null_window_warnings</literal></entry><entry>None - did nothing in GTK+ 1.2</entry></row>
918 <row><entry><literal>gdk_leader_window</literal></entry><entry>None - private variable</entry></row>
919 <row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
920 <row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
921 <row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
922 <row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function>/entry></row>
923 <row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
924 <row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
925 <row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
926 <row><entry><literal>gdk_wm_take_focus</literal></entry><entry><literal>gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)</literal></entry></row>
927 <row><entry><literal>gdk_wm_protocols</literal></entry><entry><literal>gdk_atom_intern ("WM_PROTOCOLS", FALSE)</literal></entry></row>
937 The handling of colormaps and widgets has been changed:
942 The default colormap for widgets is now the <structname>GdkRGB</structname>
943 colormap, not the system default colormap. If you try to use resources
944 created for a widget (e.g., <literal>widget->style</literal>) with
945 a window using the system colormap, errors will result on some machines.
952 <function>gtk_widget_push()</function>/<function>gtk_widget_pop_colormap()</function>
953 only cause the colormap to be explicitly set on toplevel widgets, not on
954 all widgets. The colormap for other widgets (when not set using
955 <function>gtk_widget_set_colormap()</function>), is determined by finding
956 the nearest ancestor with a colormap set on it explicitly, or if that
957 fails, the default colormap.
969 The default selected day for <structname>GtkCalendar</structname> is now the
970 current day in the month, not the first day in the month. The current month
971 and year were already used.
978 GDK is no longer put into threaded mode automatically when
979 <function>g_thread_init()</function> has been called. In order to use the
980 global GDK thread mutex with <function>gdk_threads_enter()</function> and
981 <function>gdk_threads_leave()</function>, you must call
982 <function>gdk_threads_init()</function> explicitly.
984 If you aren't using GDK and GTK+ functions from multiple threads,
985 there is no reason to call <function>gdk_threads_init()</function>.
991 The <structname>GtkPreviewInfo</structname> struct has had its visual and
992 colormap fields removed. Also, <function>gtk_preview_get_cmap()</function>
993 and <function>gtk_preview_get_visual()<function> are deprecated, as
994 <structname>GdkRGB</structname> works on any colormap and visual. You no
996 <literal>gtk_widget_push_cmap (gtk_preview_get_cmap ())</literal> in
1004 The <structname>GtkBox</structname>, <structname>GtkTable</structname>, and
1005 <structname>GtkAlignment</structname> widgets now call
1006 <literal>gtk_widget_set_redraw_on_allocate (widget, FALSE);</literal> on
1007 themselves. If you want to actually draw contents in a widget derived from
1008 one of these widgets, you'll probably want to change this
1009 in your <function>init()</function> function.
1016 A number of widgets are now <literal>NO_WINDOW</literal> widgets (most
1017 importantly <structname>GtkButton</structname>, but also
1018 <structname>GtkRange</structname> and <structname>GtkNotebook</structname>)
1020 This has a couple of effects:
1025 If you are deriving from one of these widgets, you need to
1026 adapt your code appropriately -- for instance, drawing coordinates
1027 start from <literal>widget->allocation.x, widget->allocation.y</literal>.
1034 If you are embedding one of these widgets in a custom widget,
1035 you must make sure you call <function>gtk_container_propagate_expose()</function>
1036 correctly, as you must for any <literal>NO_WINDOW</literal> widgets.
1043 <structname>GtkFixed</structname> is a little special; it is now created by
1044 default as a <literal>NO_WINDOW</literal> widget, but if you do
1047 gtk_fixed_set_has_window (fixed, TRUE);
1050 after creating a fixed widget, it will create a window and
1057 <structname>GtkLayout</structname> no longer has the <structfield>xoffset</structfield>,
1058 <structfield>yoffset</structfield> fields, which used to store the difference between
1059 world and window coordinates for <literal>layout->bin_window</literal>.
1060 These coordinate systems are now always the same.
1066 <function>gtk_paint_focus()</function>, <function>gtk_draw_focus()</function>
1067 and <function>GtkStyle::draw_focus()</function>
1068 have been changed a bit:
1073 A <literal>GtkStateType</literal> argument has been added to <function>gtk_paint_focus()</function>.
1079 The default implementation of the <function>GtkStyle::draw_focus()</function>
1080 virtual function now draws a focus rectangle whose width is
1081 determined by the GtkWidget::focus-width style property.
1087 The rectangle passed in is the bounding box, instead of
1088 the rectangle used in the <function>gdk_draw_rectangle()</function> call,
1089 so it is no longer necessary to subtract 1 from the width and height.