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 * Type system changes:
36 - GTK_TYPE_OBJECT is not a fundamental type anymore. Type checks of the
37 style (GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)
38 will not work anymore. As a replacement, (GTK_TYPE_IS_OBJECT (some_type))
40 - The following types vanished: GTK_TYPE_ARGS, GTK_TYPE_CALLBACK,
41 GTK_TYPE_C_CALLBACK, GTK_TYPE_FOREIGN. The corresponding GtkArg
42 fields and field access macros are also gone.
43 - The following type aliases vanished: GTK_TYPE_FLAT_FIRST,
44 GTK_TYPE_FLAT_LAST, GTK_TYPE_STRUCTURED_FIRST, GTK_TYPE_STRUCTURED_LAST.
45 - The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQNO() vanished, use of
46 GTK_FUNDAMENTAL_TYPE() is discouraged. Instead, the corresponding GType
47 API should be used: G_TYPE_FUNDAMENTAL(), G_TYPE_DERIVE_ID(),
48 G_TYPE_BRANCH_SEQNO(). Note that the GLib type system doesn't build new
49 type ids based on a global incremental sequential number anymore, but
50 numbers new type ids sequentially per fundamental type branch.
51 - The following type functions vanished/were replaced:
52 Old Function Replacement
53 gtk_type_query() - being investigated -
54 gtk_type_set_varargs_type() -
55 gtk_type_get_varargs_type() -
56 gtk_type_check_object_cast() g_type_check_instance_cast()
57 gtk_type_check_class_cast() g_type_check_class_cast()
58 gtk_type_describe_tree() -
59 gtk_type_describe_heritage() -
61 gtk_type_children_types() g_type_children()
62 gtk_type_set_chunk_alloc() GTypeInfo.n_preallocs
63 gtk_type_register_enum() g_enum_register_static()
64 gtk_type_register_flags() g_flags_register_static()
65 gtk_type_parent_class() g_type_parent() / g_type_class_peek_parent()
66 Use of g_type_class_ref() / g_type_class_unref() and g_type_class_peek()
67 is recommended over usage of gtk_type_class().
68 Use of g_type_register_static() / g_type_register_dynamic() is recommended
69 over usage of gtk_type_unique().
71 * Object system changes:
72 GtkObject derives from GObject, so is not the basic object type anymore.
73 This imposes the following source incompatible changes:
74 - GtkObject has no klass field anymore, an object's class can be retrived
75 with the object's coresponding GTK_<OBJECT>_GET_CLASS (object) macro.
76 - GtkObjectClass has no type field anymore, a class's type can be retrived
77 with the GTK_CLASS_TYPE (class) macro.
78 - GtkObjectClass does not introduce the finalize() and shutdown() methods
79 anymore. While shutdown() is intended for GTK+ internal use only, finalize()
80 is required by a variety of object implementations. GObjectClass.finalize
81 should be overriden here, e.g.:
82 static void gtk_label_finalize (GObject *gobject)
84 GtkLabel *label = GTK_LABEL (gobject);
86 G_OBJECT_CLASS (parent_class)->finalize (object);
88 static void gtk_label_class_init (GtkLabelClass *class)
90 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
92 gobject_class->finalize = gtk_label_finalize;
95 - the GtkObject::destroy signal can now be emitted multiple times on an object.
96 ::destroy implementations should check that make sure that they take this
97 into account, by checking to make sure that resources are there before
98 freeing them. For example:
101 g_free (object->foo_data);
102 object->foo_data = NULL;
105 Also, ::destroy implementations have to release object references that
106 the object holds. Code in finalize implementations such as:
107 if (object->adjustment)
109 gtk_object_unref (object->adjustment);
110 object->adjustment = NULL;
112 have to be moved into the ::destroy implementations. The reason for doing
113 this is that all object reference cycles should be broken at destruction
116 * Signal system changes:
117 The Gtk 2.0 signal merly proxies the GSignal system now.
118 For future usage, direct use of the GSignal API is recommended,
119 this avoids significant performance hits where GtkArg structures
120 have to be converted into GValues. For language bindings,
121 GSignal+GClosure provide a much more flexible and convenient
122 mechanism to hook into signal emissions or install class default
123 handlers, so the old GtkSignal API for language bindings is not
125 Functions that got removed in the Gtk signal API:
126 gtk_signal_n_emissions(), gtk_signal_n_emissions_by_name(),
127 gtk_signal_set_funcs(), gtk_signal_handler_pending_by_id(),
128 gtk_signal_add_emission_hook(), gtk_signal_add_emission_hook_full(),
129 gtk_signal_remove_emission_hook(), gtk_signal_query().
130 gtk_signal_add_emission_hook(), gtk_signal_remove_emission_hook().
131 Also, the GtkCallbackMarshal argument to gtk_signal_connect_full() is
132 not supported anymore.
133 For many of the removed functions, similar variants are available
134 in the g_signal_* namespace.
136 - Inserting and deleting text in GtkEntry though functions such
137 as gtk_entry_insert_text() now leave the cursor at its original
138 position in the text instead of moving it to the location of
139 the insertion/deletion.
141 - The ->label field of GtkFrame widgets has been removed. (As part of
142 a change to allow the arbitrary widgets in the title position.) The
143 text can now be retrieved with the new function gtk_frame_get_text().
145 - The 'font' and 'font_set' declarations in RC files are now ignored. There
146 is a new 'font_name' field that holds the string form of a Pango font
148 - A number of types in GDK have become subclasses of GObject. For the
149 most part, this should not break anyone's code. However, it's now
150 possible/encouraged to use g_object_ref()/g_object_unref() and other
151 GObject features with these GDK types. The converted types are:
152 GdkWindow, GdkDrawable, GdkPixmap, GdkImage, GdkGC, GdkDragContext,
155 - All drawables including pixmaps used to have a type tag, the
156 GdkWindowType enumeration, which included GDK_WINDOW_PIXMAP.
157 GdkWindowType is now a property of GdkWindow _only_, and there is
158 no GDK_WINDOW_PIXMAP. You can use the GDK_IS_PIXMAP() macro to see
159 if you have a pixmap, if you need to know that.
161 - GtkStyle and GtkRcStyle are now subclasses of GObject as well. This
162 requires fairly extensive changes to theme engines quite badly, but
163 shouldn't affect most other code.
165 - xthickness/ythickness have moved from GtkStyleClass to GtkStyle
166 (from class to instance). This gives themes a bit more flexibility
167 and is generally more of the Right Thing. You can trivially fix
168 your code with s/style->klass->xthickness/style->xthickness/g and
171 - If you were using private GDK types, they have been rearranged
172 significantly. You shouldn't use private types. ;-)
174 - The visual for a widget, and also the default visual is now derived
175 from the colormap for the widget and the default colormap.
176 gtk_widget_set_visual(), gtk_widget_set_default_visual(), gtk_widget_push_visual()
177 and gtk_widget_pop_visual() now do nothing. Since the visual always
178 had to match that of the colormap, it is safe to simply delete
179 all references to these functions.
181 - A number of functions in GDK have been renamed for consistency and
182 clarity. #defines to provide backwards compatibility have been
183 included, but can be disabled by defineing GDK_DISABLE_COMPAT_H.
185 #define gdk_draw_pixmap gdk_draw_drawable
186 #define gdk_draw_bitmap gdk_draw_drawable
188 #define gdk_window_get_size gdk_drawable_get_size
189 #define gdk_window_get_type gdk_window_get_window_type
190 #define gdk_window_get_colormap gdk_drawable_get_colormap
191 #define gdk_window_set_colormap gdk_drawable_set_colormap
192 #define gdk_window_get_visual gdk_drawable_get_visual
194 #define gdk_window_ref gdk_drawable_ref
195 #define gdk_window_unref gdk_drawable_unref
196 #define gdk_bitmap_ref gdk_drawable_ref
197 #define gdk_bitmap_unref gdk_drawable_unref
198 #define gdk_pixmap_ref gdk_drawable_ref
199 #define gdk_pixmap_unref gdk_drawable_unref
201 #define gdk_gc_destroy gdk_gc_unref
202 #define gdk_image_destroy gdk_image_unref
203 #define gdk_cursor_destroy gdk_cursor_unref
205 (Note that g_object_ref() and g_object_unref() may be used for all of
208 #define gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height) \
209 gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)
211 #define gdk_rgb_get_cmap gdk_rgb_get_colormap
213 - gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the
214 pixmap when the GdkPixmap is finalized. This change corresponds
215 to the behavior of gdk_window_foreign_new(), and fixes a lot
216 of problems with code where the pixmap wasn't supposed to be
217 freed. If XFreePixmap() is needed, it can be done using the
218 destroy-notification facilities of g_object_set_data().
220 - GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
222 - Only 3 or 4 functions are really needed for 95% of progress
223 interfaces; GtkProgress[Bar] had about 25 functions, and
224 didn't even include these 3 or 4.
225 - In activity mode, the API involves setting the adjustment
226 to any random value, just to have the side effect of
227 calling the progress bar update function - the adjustment
228 is totally ignored in activity mode
229 - You set the activity step as a pixel value, which means to
230 set the activity step you basically need to connect to
232 - There are ctree_set_expander_style()-functions, to randomly
233 change look-and-feel for no good reason
234 - The split between GtkProgress and GtkProgressBar makes no sense
237 This was a big wart on GTK and made people waste lots of time,
238 both learning and using the interface.
240 So, we have added what we feel is the correct API, and marked all the
241 rest deprecated. However, the changes are 100% backward-compatible and
242 should break no existing code.
244 The following 5 functions are the new programming interface and you
245 should consider changing your code to use them:
247 void gtk_progress_bar_pulse (GtkProgressBar *pbar);
248 void gtk_progress_bar_set_text (GtkProgressBar *pbar,
250 void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
253 void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
255 void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
256 GtkProgressBarOrientation orientation);
258 * The GtkNotebookPage structure has been removed from the public header files;
259 this was never meant to be a public structure, and all functionality that
260 could be done by accessing the struct fields of this structure should be
263 - GtkMenuPositionFunc has a new parameter push_in which controls how
264 menus placed outside the screen is handled. If this is set to true and
265 part of the menu is outside the screen then Gtk+ pushes it into the visible
266 area. Otherwise the menu is cut of at the end of the visible screen area.
268 Regardles of what happens to the size of the menu, the result is always
269 that the items are placed in the same place as if the menu was placed
270 outside the screen, using menu scrolling if necessary.
272 - The "draw" signal and virtual method on GtkWidget has been removed.
273 All drawing should now occur by invalidating a region of the widget
274 (call gdk_window_invalidate_rect() or gtk_widget_queue_draw() for
275 example to invalidate a region). GTK+ merges all invalid regions,
276 and sends expose events to the widget in an idle handler for the
277 invalid regions. gtk_widget_draw() is deprecated but still works; it
278 adds the passed-in area to the invalid region and immediately sends
279 expose events for the current invalid region.
281 Most widgets will work fine if you just delete their "draw"
282 implementation, since they will already have working expose_event
283 implementations. The draw method was rarely called in practice