1 Incompatible Changes from GTK+-1.2 to GTK+-2.0:
3 * gtk_container_get_toplevels() was removed and replaced with
4 gtk_window_list_toplevels(), which has different memory management
5 on the return value (gtk_window_list_toplevels() copies the GList
6 and also references each widget in the list, so you have to
7 g_list_free() the list after first unref'ing each list member).
9 * The gdk_time* functions have been removed. This functionality
10 has been unused since the main loop was moved into GLib
13 * The signature for GtkPrintFunc (used for gtk_item_factory_dump_items)
14 has been changed to take a 'const gchar *' instead of 'gchar *', to
15 match what we do for glib, and other similar cases.
17 * The detail arguments in the GtkStyleClass structure are now 'const gchar *'.
19 * gtk_paned_set_gutter_size() has been removed, since the small handle tab
20 has been changed to include the entire area previously occupied by
23 * GDK no longer selects OwnerGrabButtonMask for button presses. This means
24 that the automatic grab that occurs when the user presses a button
25 will have owner_events = FALSE, so all events are redirected to the
26 grab window, even events that would normally go to other windows of the
29 * GtkColorSelectionDialog has now been moved into it's own set of files,
30 gtkcolorseldialog.c and gtkcolorseldialog.h.
32 * gtk_widget_shape_combine_mask() now keeps a reference count on the
33 mask pixmap that is passed in.
35 * the GtkPatternSpec has been moved to glib as GPatternSpec, the pattern
36 arguments to gtk_item_factory_dump_items() and gtk_item_factory_dump_rc()
37 have thusly been changed to take a GPatternSpec instead of GtkPatternSpec.
39 * Type system changes:
40 - GTK_TYPE_OBJECT is not a fundamental type anymore. Type checks of the
41 style (GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)
42 will not work anymore. As a replacement, (GTK_TYPE_IS_OBJECT (some_type))
44 - The following types vanished: GTK_TYPE_ARGS, GTK_TYPE_CALLBACK,
45 GTK_TYPE_C_CALLBACK, GTK_TYPE_FOREIGN. The corresponding GtkArg
46 fields and field access macros are also gone.
47 - The following type aliases vanished: GTK_TYPE_FLAT_FIRST,
48 GTK_TYPE_FLAT_LAST, GTK_TYPE_STRUCTURED_FIRST, GTK_TYPE_STRUCTURED_LAST.
49 - The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQNO() vanished, use of
50 GTK_FUNDAMENTAL_TYPE() is discouraged. Instead, the corresponding GType
51 API should be used: G_TYPE_FUNDAMENTAL(), G_TYPE_DERIVE_ID(),
52 G_TYPE_BRANCH_SEQNO(). Note that the GLib type system doesn't build new
53 type ids based on a global incremental sequential number anymore, but
54 numbers new type ids sequentially per fundamental type branch.
55 - The following type functions vanished/were replaced:
56 Old Function Replacement
57 gtk_type_query() - being investigated -
58 gtk_type_set_varargs_type() -
59 gtk_type_get_varargs_type() -
60 gtk_type_check_object_cast() g_type_check_instance_cast()
61 gtk_type_check_class_cast() g_type_check_class_cast()
62 gtk_type_describe_tree() -
63 gtk_type_describe_heritage() -
65 gtk_type_children_types() g_type_children()
66 gtk_type_set_chunk_alloc() GTypeInfo.n_preallocs
67 gtk_type_register_enum() g_enum_register_static()
68 gtk_type_register_flags() g_flags_register_static()
69 gtk_type_parent_class() g_type_parent() / g_type_class_peek_parent()
70 Use of g_type_class_ref() / g_type_class_unref() and g_type_class_peek()
71 is recommended over usage of gtk_type_class().
72 Use of g_type_register_static() / g_type_register_dynamic() is recommended
73 over usage of gtk_type_unique().
75 * Object system changes:
76 GtkObject derives from GObject, so is not the basic object type anymore.
77 This imposes the following source incompatible changes:
78 - GtkObject has no klass field anymore, an object's class can be retrived
79 with the object's coresponding GTK_<OBJECT>_GET_CLASS (object) macro.
80 - GtkObjectClass has no type field anymore, a class's type can be retrived
81 with the GTK_CLASS_TYPE (class) macro.
82 - GtkObjectClass does not introduce the finalize() and shutdown() methods
83 anymore. While shutdown() is intended for GTK+ internal use only, finalize()
84 is required by a variety of object implementations. GObjectClass.finalize
85 should be overriden here, e.g.:
86 static void gtk_label_finalize (GObject *gobject)
88 GtkLabel *label = GTK_LABEL (gobject);
90 G_OBJECT_CLASS (parent_class)->finalize (object);
92 static void gtk_label_class_init (GtkLabelClass *class)
94 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
96 gobject_class->finalize = gtk_label_finalize;
99 - the GtkObject::destroy signal can now be emitted multiple times on an object.
100 ::destroy implementations should check that make sure that they take this
101 into account, by checking to make sure that resources are there before
102 freeing them. For example:
103 if (object->foo_data)
105 g_free (object->foo_data);
106 object->foo_data = NULL;
109 Also, ::destroy implementations have to release object references that
110 the object holds. Code in finalize implementations such as:
111 if (object->adjustment)
113 gtk_object_unref (object->adjustment);
114 object->adjustment = NULL;
116 have to be moved into the ::destroy implementations. The reason for doing
117 this is that all object reference cycles should be broken at destruction
120 * Signal system changes:
121 The Gtk 2.0 signal merly proxies the GSignal system now.
122 For future usage, direct use of the GSignal API is recommended,
123 this avoids significant performance hits where GtkArg structures
124 have to be converted into GValues. For language bindings,
125 GSignal+GClosure provide a much more flexible and convenient
126 mechanism to hook into signal emissions or install class default
127 handlers, so the old GtkSignal API for language bindings is not
129 Functions that got removed in the Gtk signal API:
130 gtk_signal_n_emissions(), gtk_signal_n_emissions_by_name(),
131 gtk_signal_set_funcs(), gtk_signal_handler_pending_by_id(),
132 gtk_signal_add_emission_hook(), gtk_signal_add_emission_hook_full(),
133 gtk_signal_remove_emission_hook(), gtk_signal_query().
134 Also, the GtkCallbackMarshal argument to gtk_signal_connect_full() is
135 not supported anymore.
136 For many of the removed functions, similar variants are available
137 in the g_signal_* namespace.
138 The GSignal system perfomrs emissions in a slightly different manner than
139 the old GtkSignal code. Signal handlers that are connected to signal "foo"
140 on object "bar" while "foo" is being emitted, will not be called anymore
141 during the emission they were connected within.
143 * Inserting and deleting text in GtkEntry though functions such
144 as gtk_entry_insert_text() now leave the cursor at its original
145 position in the text instead of moving it to the location of
146 the insertion/deletion.
148 * The ->label field of GtkFrame widgets has been removed. (As part of
149 a change to allow the arbitrary widgets in the title position.) The
150 text can now be retrieved with the new function gtk_frame_get_text().
152 * The 'font' and 'font_set' declarations in RC files are now ignored. There
153 is a new 'font_name' field that holds the string form of a Pango font
155 * A number of types in GDK have become subclasses of GObject. For the
156 most part, this should not break anyone's code. However, it's now
157 possible/encouraged to use g_object_ref()/g_object_unref() and other
158 GObject features with these GDK types. The converted types are:
159 GdkWindow, GdkDrawable, GdkPixmap, GdkImage, GdkGC, GdkDragContext,
162 * All drawables including pixmaps used to have a type tag, the
163 GdkWindowType enumeration, which included GDK_WINDOW_PIXMAP.
164 GdkWindowType is now a property of GdkWindow _only_, and there is
165 no GDK_WINDOW_PIXMAP. You can use the GDK_IS_PIXMAP() macro to see
166 if you have a pixmap, if you need to know that.
168 * GtkStyle and GtkRcStyle are now subclasses of GObject as well. This
169 requires fairly extensive changes to theme engines quite badly, but
170 shouldn't affect most other code.
172 * xthickness/ythickness have moved from GtkStyleClass to GtkStyle
173 (from class to instance). This gives themes a bit more flexibility
174 and is generally more of the Right Thing. You can trivially fix
175 your code with s/style->klass->xthickness/style->xthickness/g and
178 * Some GtkStyle draw_ methods have been removed (cross, oval, ramp)
179 and others have been added (expander, layout). This will require
180 changes to theme engines.
182 * If you were using private GDK types, they have been rearranged
183 significantly. You shouldn't use private types. ;-)
185 * The visual for a widget, and also the default visual is now derived
186 from the colormap for the widget and the default colormap.
187 gtk_widget_set_visual(), gtk_widget_set_default_visual(), gtk_widget_push_visual()
188 and gtk_widget_pop_visual() now do nothing. Since the visual always
189 had to match that of the colormap, it is safe to simply delete
190 all references to these functions.
192 * A number of functions in GDK have been renamed for consistency and
193 clarity. #defines to provide backwards compatibility have been
194 included, but can be disabled by defineing GDK_DISABLE_DEPRECATED.
196 #define gdk_draw_pixmap gdk_draw_drawable
197 #define gdk_draw_bitmap gdk_draw_drawable
199 #define gdk_window_get_size gdk_drawable_get_size
200 #define gdk_window_get_type gdk_window_get_window_type
201 #define gdk_window_get_colormap gdk_drawable_get_colormap
202 #define gdk_window_set_colormap gdk_drawable_set_colormap
203 #define gdk_window_get_visual gdk_drawable_get_visual
205 #define gdk_window_ref gdk_drawable_ref
206 #define gdk_window_unref gdk_drawable_unref
207 #define gdk_bitmap_ref gdk_drawable_ref
208 #define gdk_bitmap_unref gdk_drawable_unref
209 #define gdk_pixmap_ref gdk_drawable_ref
210 #define gdk_pixmap_unref gdk_drawable_unref
212 #define gdk_gc_destroy gdk_gc_unref
213 #define gdk_image_destroy gdk_image_unref
214 #define gdk_cursor_destroy gdk_cursor_unref
216 (Note that g_object_ref() and g_object_unref() may be used for all of
217 the above _ref and _unref functions.)
219 #define gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height) \
220 gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)
222 #define gdk_rgb_get_cmap gdk_rgb_get_colormap
224 gtk_widget_popup() was removed, it was only usable for GtkWindows, and
225 there the same effect can be achived by gtk_widget_set_uposition() and
228 * gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the
229 pixmap when the GdkPixmap is finalized. This change corresponds
230 to the behavior of gdk_window_foreign_new(), and fixes a lot
231 of problems with code where the pixmap wasn't supposed to be
232 freed. If XFreePixmap() is needed, it can be done using the
233 destroy-notification facilities of g_object_set_data().
235 * GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
236 - Only 3 or 4 functions are really needed for 95% of progress
237 interfaces; GtkProgress[Bar] had about 25 functions, and
238 didn't even include these 3 or 4.
239 - In activity mode, the API involves setting the adjustment
240 to any random value, just to have the side effect of
241 calling the progress bar update function - the adjustment
242 is totally ignored in activity mode
243 - You set the activity step as a pixel value, which means to
244 set the activity step you basically need to connect to
246 - There are ctree_set_expander_style()-functions, to randomly
247 change look-and-feel for no good reason
248 - The split between GtkProgress and GtkProgressBar makes no sense
250 This was a big wart on GTK and made people waste lots of time,
251 both learning and using the interface.
252 So, we have added what we feel is the correct API, and marked all the
253 rest deprecated. However, the changes are 100% backward-compatible and
254 should break no existing code.
255 The following 5 functions are the new programming interface and you
256 should consider changing your code to use them:
257 void gtk_progress_bar_pulse (GtkProgressBar *pbar);
258 void gtk_progress_bar_set_text (GtkProgressBar *pbar,
260 void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
263 void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
265 void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
266 GtkProgressBarOrientation orientation);
268 * The GtkNotebookPage structure has been removed from the public header files;
269 this was never meant to be a public structure, and all functionality that
270 could be done by accessing the struct fields of this structure should be
273 * GtkMenuPositionFunc has a new parameter push_in which controls how
274 menus placed outside the screen is handled. If this is set to true and
275 part of the menu is outside the screen then Gtk+ pushes it into the visible
276 area. Otherwise the menu is cut of at the end of the visible screen area.
278 Regardles of what happens to the size of the menu, the result is always
279 that the items are placed in the same place as if the menu was placed
280 outside the screen, using menu scrolling if necessary.
282 * The "draw" signal and virtual method on GtkWidget has been removed.
283 All drawing should now occur by invalidating a region of the widget
284 (call gdk_window_invalidate_rect() or gtk_widget_queue_draw() for
285 example to invalidate a region). GTK+ merges all invalid regions,
286 and sends expose events to the widget in an idle handler for the
287 invalid regions. gtk_widget_draw() is deprecated but still works; it
288 adds the passed-in area to the invalid region and immediately sends
289 expose events for the current invalid region.
290 Most widgets will work fine if you just delete their "draw"
291 implementation, since they will already have working expose_event
292 implementations. The draw method was rarely called in practice
295 * The GdkExposeEvent has a new region field. This can be used instead
296 of the area field if you want a more exact representation of the
299 * Sending synthetic exposes using gtk_widget_event is no longer allowed.
300 If you just need an expose call you should use gdk_window_invalidate_rect()
301 or gdk_window_invalidate_region() instead. For the case of container
302 widgets that need to propagate expose events to NO_WINDOW children
303 you can either use gtk_container_propagate_expose(), or chain to the
304 default container expose handler.
306 * The draw_default and draw_focus methods/signals on GtkWidget are
307 gone; simply draw things in your expose handler.
308 gtk_widget_draw_focus() and gtk_widget_draw_default() wrapper
309 functions are also gone; just queue a draw on the widget,
310 or the part affected by the focus/default anyway.
311 Also, GtkWidget now has default implementations for focus_in_event
312 and focus_out_event. These set/unset GTK_HAS_FOCUS, and queue a
313 draw. So if your focus in/out handler just does that, you can delete
316 * GtkText and GtkTree are buggy and broken. We don't recommend using
317 them, and changing old code to avoid them is a good idea. The
318 recommended alternatives are GtkTextView and GtkTreeView. The
319 broken widgets are not declared in the headers by default; to use
320 them, define the symbol GTK_ENABLE_BROKEN during compilation. In
321 some future release, these widgets will be removed from GTK+.
323 * GdkColorContext is gone; you probably weren't using it anyway.
324 Use GdkColormap and the gdk_rgb_* functions instead.
326 * GtkMenuBar now draws the GtkContainer::border_width space outside
327 the frame, not inside the frame
329 * In GTK 1.2, if an event handler returned TRUE it prevented
330 propagation of that event to parent widgets. That is, the
331 event signal would not be emitted on parent widgets. In
332 GTK 2.0, if an event handler returns TRUE, the current signal
333 emission on the current widget is immediately stopped. That is,
334 other callbacks connected to the signal will not be invoked.
336 * gtk_toolbar_new() no longer has arguments. This function
337 was broken because the default GtkToolbarStyle (icons, text, both)
338 is now a user preference, which is overridden when you call
339 gtk_toolbar_set_style(). The constructor forced everyone to
340 override the preference, which was undesirable. So to port
341 your app, decide if you want to force the toolbar style
342 or conform to the user's global defaults; if you want to force
343 it, call gtk_toolbar_set_style().
345 The orientation arg was removed from toolbar_new() as well, just
346 because it wasn't very useful and we were breaking the function
347 anyway so had an opportunity to lose it. Call
348 gtk_toolbar_set_orientation() to set toolbar orientation.
350 * GtkRange/GtkScrollbar/GtkScale were rewritten; this means that most
351 theme engines won't draw them properly, and any custom subclasses of
352 these widgets will need a rewrite (though if you could figure out
353 how to subclass the old version of GtkRange, you have our
354 respect). Also, GtkTroughType is gone.
356 * The GtkContainer::focus signal/virtualfunction and
357 gtk_container_focus() call were replaced by
358 GtkWidget::focus and gtk_widget_child_focus().
359 The semantics are the same, so you should be able to just
360 replace "container_class->focus = mywidget_focus" with
361 "widget_class->focus = mywidget_focus" and replace
362 gtk_container_focus() calls with gtk_widget_child_focus() calls.
364 The purpose of this change was to allow non-containers to have
367 * gtk_rc_set_image_loader() and gtk_rc_load_image() has been removed, now
368 that GTK+ includes decent image loading capabilities itself.
370 * An extra GtkSettings argument has been added to
371 gtk_rc_find_pixmap_in_path(). This function is only actually useful
372 from a theme engine during parsing, at which point the GtkSettings
375 * The child argument facility in gtkcontainer.c has been converted
376 to a child property facility using GParamSpec and other facilities
379 - The set_child_arg and get_child_arg virtual methods have been
380 replaced with set_child_property / get_child_property, which
381 work similar to GObject->set_property/get_property.
383 - Other removed functions with the replacements:
385 gtk_container_add_child_arg_type => gtk_container_class_install_child_property
386 gtk_container_query_child_args => gtk_container_class_list_child_properties
387 gtk_container_child_getv => gtk_container_child_set_property
388 gtk_container_child_setv => gtk_container_child_get_property
389 gtk_container_add_with_args => gtk_container_add_with_properties
390 gtk_container_addv => gtk_container_add / gtk_container_child_set_property
392 * gdk_image_get() (or rather its replacement,
393 gdk_drawable_get_image()) now handles errors properly by returning
394 NULL, previously it would crash. Also, a window being offscreen is
395 no longer considered an error; instead, the area being contains
396 undefined contents for the offscreen areas. In most cases, code
397 using gdk_image_get() should really be ported to
398 gdk_pixbuf_get_from_drawable().
400 * gtk_widget_set_usize() has been renamed to
401 gtk_widget_set_size_request(), however the old name still exists
402 unless you define GTK_DISABLE_DEPRECATED.
404 * gtk_widget_set_uposition() is deprecated; use gtk_window_move(),
405 gtk_fixed_put(), or gtk_layout_put() instead.
407 * gtk_window_set_policy() is deprecated. To get the effect of
408 "allow_shrink", call gtk_widget_set_size_request(window, 0, 0). To
409 get the effect of "allow_grow", call
410 gtk_window_set_resizable(window, TRUE). You didn't want the effect
411 of auto_shrink, it made no sense. But maybe if you were using it you
412 want to use gtk_window_resize (window, 1, 1) to snap a window back
413 to its minimum size (the 1, 1 will be rounded up to the minimum
416 * The core GTK+ now takes care of handling mapping, unmapping and
417 realizing the child widgets of containers in
418 gtk_widget_set_parent(). In most cases, this allows container
419 implementations to be simplifid by removing the code in add()
420 methods to map and realize children. However, there are
421 a couple of things to watch out for here:
423 - If the parent is realized before the add() happens,
424 gtk_widget_set_parent_window() must be called before
425 gtk_widget_set_parent(), since gtk_widget_set_parent()
426 will realize the child.
428 - If a container depended on its children not being mapped
429 unless it did so itself (for example, GtkNotebook only
430 mapped the current page), then the new function
431 gtk_widget_set_child_visible() must be called to keep
432 widgets that should not be mapped not mapped.
434 As part of this change, most containers also will no longer need
435 custom implementations of the map() and unmap() virtual
436 functions. The only cases where this is necessary are:
438 - For !NO_WINDOW widgets, if you create children of widget->window
439 and don't map them in realize() then you must map them
440 in map(). [ In almost all cases, you can simply map the
441 windows in realize() ]
443 - For NO_WINDOW widgets, if you create windows in your realize()
444 method, you must map then in map() and unmap them in unmap().
446 * gtk_widget_set_default_style (), gtk_widget_push_style (),
447 and gtk_widget_pop_style () have been removed, since they
448 did not work properly with themes and there were better
449 alternatives for modifying the appearance of widgets.
451 You should generally use gtk_widget_modify_fg/bg/base/text/font
454 * gtk_image_new() now takes no arguments and creates an empty GtkImage
455 widget. To create a GtkImage widget from a GdkImage (the least
456 common usage of GdkImage), use gtk_image_new_from_image.
458 * GTK_SELECTION_EXTENDED is now deprecated, and neither the
459 GtkList/GtkTree nor the GtkCList/GtkCTree support
460 GTK_SELECTION_EXTENDED anymore. However, the old extended behavior
461 replaces MULTIPLE behavior.
463 * The following variables are no longer exported from GDK. (Other variables
464 are also no longer exported; the following are the ones found used
465 externally in a large sample of GTK+ code.)
469 gdk_null_window_warnings None - did nothing in GTK+-1.2.
470 gdk_leader_window None - private variable
471 gdk_screen gdk_x11_get_default_screen ()
472 gdk_root_window gdk_x11_get_default_root_xwindow ()
473 gdk_root_parent gdk_get_default_root_window ()
474 gdk_error_code/gdk_error_warnings gdk_error_trap_push()/pop()
475 gdk_display_name gdk_get_display ()
476 gdk_wm_delete_window gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)
477 gdk_wm_take_focus gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)
478 gdk_wm_protocols gdk_atom_intern ("WM_PROTOCOLS", FALSE)
480 * The handling of Colormaps and widgets has been changed:
482 - The default colormap for widgets is now the GdkRGB colormap, not
483 the system default colormap. If you try to use resources created for
484 a widget (e.g., widget->style) with a window using the system
485 colormap, errors will result on some machines.
487 - gtk_widget_push/pop_colormap() only cause the colormap to be
488 explicitely set on toplevel widgets not on all widgets. The
489 colormap for other widgets (when not set using
490 gtk_widget_set_colormap()), is determined by finding the nearest
491 ancestor with a colormap set on it explicitely, or if that
492 fails, the default colormap.
494 * The default selected day for GtkCalendar is now the current day in the
495 month, not the first day in the month. The current month and year
498 * GDK is no longer put into threaded mode automatically when
499 g_thread_init() has been called. In order to use the
500 global GDK thread mutex with gdk_threads_enter() and
501 gdk_threads_leave(), you must call gdk_threads_init() explicitely.
503 If you aren't using GDK and GTK+ functions from multiple threads,
504 there is no reason to call gdk_threads_init().
506 * The GtkPreviewInfo struct has had its visual and colormap fields
507 removed. Also, gtk_preview_get_cmap() and gtk_preview_get_visual()
508 are deprecated, as GdkRgb works on any colormap and visual. You no
509 longer need to gtk_widget_push_cmap (gtk_preview_get_cmap ()) in