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.
139 * Inserting and deleting text in GtkEntry though functions such
140 as gtk_entry_insert_text() now leave the cursor at its original
141 position in the text instead of moving it to the location of
142 the insertion/deletion.
144 * The ->label field of GtkFrame widgets has been removed. (As part of
145 a change to allow the arbitrary widgets in the title position.) The
146 text can now be retrieved with the new function gtk_frame_get_text().
148 * The 'font' and 'font_set' declarations in RC files are now ignored. There
149 is a new 'font_name' field that holds the string form of a Pango font
151 * A number of types in GDK have become subclasses of GObject. For the
152 most part, this should not break anyone's code. However, it's now
153 possible/encouraged to use g_object_ref()/g_object_unref() and other
154 GObject features with these GDK types. The converted types are:
155 GdkWindow, GdkDrawable, GdkPixmap, GdkImage, GdkGC, GdkDragContext,
158 * All drawables including pixmaps used to have a type tag, the
159 GdkWindowType enumeration, which included GDK_WINDOW_PIXMAP.
160 GdkWindowType is now a property of GdkWindow _only_, and there is
161 no GDK_WINDOW_PIXMAP. You can use the GDK_IS_PIXMAP() macro to see
162 if you have a pixmap, if you need to know that.
164 * GtkStyle and GtkRcStyle are now subclasses of GObject as well. This
165 requires fairly extensive changes to theme engines quite badly, but
166 shouldn't affect most other code.
168 * xthickness/ythickness have moved from GtkStyleClass to GtkStyle
169 (from class to instance). This gives themes a bit more flexibility
170 and is generally more of the Right Thing. You can trivially fix
171 your code with s/style->klass->xthickness/style->xthickness/g and
174 * Some GtkStyle draw_ methods have been removed (cross, oval, ramp)
175 and others have been added (expander, layout). This will require
176 changes to theme engines.
178 * If you were using private GDK types, they have been rearranged
179 significantly. You shouldn't use private types. ;-)
181 * The visual for a widget, and also the default visual is now derived
182 from the colormap for the widget and the default colormap.
183 gtk_widget_set_visual(), gtk_widget_set_default_visual(), gtk_widget_push_visual()
184 and gtk_widget_pop_visual() now do nothing. Since the visual always
185 had to match that of the colormap, it is safe to simply delete
186 all references to these functions.
188 * A number of functions in GDK have been renamed for consistency and
189 clarity. #defines to provide backwards compatibility have been
190 included, but can be disabled by defineing GDK_DISABLE_COMPAT_H.
192 #define gdk_draw_pixmap gdk_draw_drawable
193 #define gdk_draw_bitmap gdk_draw_drawable
195 #define gdk_window_get_size gdk_drawable_get_size
196 #define gdk_window_get_type gdk_window_get_window_type
197 #define gdk_window_get_colormap gdk_drawable_get_colormap
198 #define gdk_window_set_colormap gdk_drawable_set_colormap
199 #define gdk_window_get_visual gdk_drawable_get_visual
201 #define gdk_window_ref gdk_drawable_ref
202 #define gdk_window_unref gdk_drawable_unref
203 #define gdk_bitmap_ref gdk_drawable_ref
204 #define gdk_bitmap_unref gdk_drawable_unref
205 #define gdk_pixmap_ref gdk_drawable_ref
206 #define gdk_pixmap_unref gdk_drawable_unref
208 #define gdk_gc_destroy gdk_gc_unref
209 #define gdk_image_destroy gdk_image_unref
210 #define gdk_cursor_destroy gdk_cursor_unref
212 (Note that g_object_ref() and g_object_unref() may be used for all of
213 the above _ref and _unref functions.)
215 #define gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height) \
216 gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)
218 #define gdk_rgb_get_cmap gdk_rgb_get_colormap
220 gtk_widget_popup() was removed, it was only usable for GtkWindows, and
221 there the same effect can be achived by gtk_widget_set_uposition() and
224 * gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the
225 pixmap when the GdkPixmap is finalized. This change corresponds
226 to the behavior of gdk_window_foreign_new(), and fixes a lot
227 of problems with code where the pixmap wasn't supposed to be
228 freed. If XFreePixmap() is needed, it can be done using the
229 destroy-notification facilities of g_object_set_data().
231 * GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
232 - Only 3 or 4 functions are really needed for 95% of progress
233 interfaces; GtkProgress[Bar] had about 25 functions, and
234 didn't even include these 3 or 4.
235 - In activity mode, the API involves setting the adjustment
236 to any random value, just to have the side effect of
237 calling the progress bar update function - the adjustment
238 is totally ignored in activity mode
239 - You set the activity step as a pixel value, which means to
240 set the activity step you basically need to connect to
242 - There are ctree_set_expander_style()-functions, to randomly
243 change look-and-feel for no good reason
244 - The split between GtkProgress and GtkProgressBar makes no sense
246 This was a big wart on GTK and made people waste lots of time,
247 both learning and using the interface.
248 So, we have added what we feel is the correct API, and marked all the
249 rest deprecated. However, the changes are 100% backward-compatible and
250 should break no existing code.
251 The following 5 functions are the new programming interface and you
252 should consider changing your code to use them:
253 void gtk_progress_bar_pulse (GtkProgressBar *pbar);
254 void gtk_progress_bar_set_text (GtkProgressBar *pbar,
256 void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
259 void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
261 void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
262 GtkProgressBarOrientation orientation);
264 * The GtkNotebookPage structure has been removed from the public header files;
265 this was never meant to be a public structure, and all functionality that
266 could be done by accessing the struct fields of this structure should be
269 * GtkMenuPositionFunc has a new parameter push_in which controls how
270 menus placed outside the screen is handled. If this is set to true and
271 part of the menu is outside the screen then Gtk+ pushes it into the visible
272 area. Otherwise the menu is cut of at the end of the visible screen area.
274 Regardles of what happens to the size of the menu, the result is always
275 that the items are placed in the same place as if the menu was placed
276 outside the screen, using menu scrolling if necessary.
278 * The "draw" signal and virtual method on GtkWidget has been removed.
279 All drawing should now occur by invalidating a region of the widget
280 (call gdk_window_invalidate_rect() or gtk_widget_queue_draw() for
281 example to invalidate a region). GTK+ merges all invalid regions,
282 and sends expose events to the widget in an idle handler for the
283 invalid regions. gtk_widget_draw() is deprecated but still works; it
284 adds the passed-in area to the invalid region and immediately sends
285 expose events for the current invalid region.
286 Most widgets will work fine if you just delete their "draw"
287 implementation, since they will already have working expose_event
288 implementations. The draw method was rarely called in practice
291 * The GdkExposeEvent has a new region field. This can be used instead
292 of the area field if you want a more exact representation of the
295 * Sending synthetic exposes using gtk_widget_event is no longer allowed.
296 If you just need an expose call you should use gdk_window_invalidate_rect()
297 or gdk_window_invalidate_region() instead. For the case of container
298 widgets that need to propagate expose events to NO_WINDOW children
299 you can either use gtk_container_propagate_expose(), or chain to the
300 default container expose handler.
302 * The draw_default and draw_focus methods/signals on GtkWidget are
303 gone; simply draw things in your expose handler.
304 gtk_widget_draw_focus() and gtk_widget_draw_default() wrapper
305 functions are also gone; just queue a draw on the widget,
306 or the part affected by the focus/default anyway.
307 Also, GtkWidget now has default implementations for focus_in_event
308 and focus_out_event. These set/unset GTK_HAS_FOCUS, and queue a
309 draw. So if your focus in/out handler just does that, you can delete
312 * GtkText and GtkTree are buggy and broken. We don't recommend using
313 them, and changing old code to avoid them is a good idea. The
314 recommended alternatives are GtkTextView and GtkTreeView. The
315 broken widgets are not declared in the headers by default; to use
316 them, define the symbol GTK_ENABLE_BROKEN during compilation. In
317 some future release, these widgets will be removed from GTK+.
319 * GdkColorContext is gone; you probably weren't using it anyway.
320 Use GdkColormap and the gdk_rgb_* functions instead.