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_COMPAT_H.
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.