--- porting.pod.orig 2004-04-04 01:33:35.000000000 +0200 +++ porting.pod 2004-04-04 02:43:16.000000000 +0200 @@ -26,7 +26,6 @@ to L for information on how to translate between C and Perl in your head. - The biggest stumbling block for most porting will be the fact that several important widgets have been omitted from Gtk2-Perl because they are deprecated in gtk+-2.0. @@ -48,10 +47,8 @@ ;-) I recommend it for putting off the porting from CList to TreeView as long as possible in your porting effort, so you can still see something as you work. - =head1 PORTING FROM Gtk-Perl TO Gtk2-Perl - =head2 Step 1: Just get it to run. The very first step: you need to C, not C. The -init @@ -189,13 +186,17 @@ owner_events = FALSE, so all events are redirected to the grab window, even events that would normally go to other windows of the window's owner. -=item Type system changes: +=item o + +Type system changes: The GTK+ type system was moved to GLib in 2.0, and the base object is now GObject rather than GtkObject. GLib is wrapped separately by the Glib module (see L), and thus GObject is Glib::Object in Perl. -=item Object system changes: +=item o + +Object system changes: GtkObject derives from GObject, so is not the basic object type anymore. This imposes the following source incompatible changes: @@ -208,49 +209,25 @@ Glib::Objects is a mess in Gtk2-Perl, but a completely different mess. See L and L for more information. +=item - + In particular, code that uses GTK_SET_ARG, GTK_GET_ARG, GTK_CLASS_INIT, GTK_OBJECT_INIT, etc, will have to be rewritten to use the corresponding Glib::Object stuff, which is not terribly complicated, but too involved to document here. -GtkObject has no klass field anymore, an object's class can be retrieved with -the object's coresponding GTK__GET_CLASS (object) macro. - - -GtkObjectClass has no type field anymore, a class's type can be retrived with -the GTK_CLASS_TYPE (class) macro. - +=item - The GtkObject::destroy signal can now be emitted multiple times on an object. -::destroy implementations should check that make sure that they take this into -account, by checking to make sure that resources are there before freeing them. +::destroy implementations should make sure that they take this into account, by +checking that resources are there before freeing them. =back -=item Signal system changes: - -The GTK+ 2.0 signal system merely proxies the GSignal system now. For future -usage, direct use of the GSignal API is recommended, this avoids significant -performance hits where GtkArg structures have to be converted into GValues. For -language bindings, GSignal+GClosure provide a much more flexible and convenient -mechanism to hook into signal emissions or install class default handlers, so -the old GtkSignal API for language bindings is not supported anymore. - -Functions that got removed in the GTK+ signal API: gtk_signal_n_emissions(), -gtk_signal_n_emissions_by_name(), gtk_signal_set_funcs(), -gtk_signal_handler_pending_by_id(), gtk_signal_add_emission_hook(), -gtk_signal_add_emission_hook_full(), gtk_signal_remove_emission_hook(), -gtk_signal_query(). Also, the GtkCallbackMarshal argument to -gtk_signal_connect_full() is not supported anymore. For many of the removed -functions, similar variants are available in the g_signal_* namespace. The -GSignal system performs emissions in a slightly different manner than the old -GtkSignal code. Signal handlers that are connected to signal "foo" on object -"bar" while "foo" is being emitted, will not be called anymore during the -emission they were connected within. - - =item o +Signal system changes: + Inserting and deleting text in Gtk2::Entry though functions such as Gtk2::Entry::insert_text() now leave the cursor at its original position in the text instead of moving it to the location of the insertion/deletion. @@ -277,9 +254,9 @@ =item o -Some GtkStyle draw_* methods have been removed (cross, oval, ramp) and others -have been added (expander, layout). This will require changes to theme -engines. +Some Gtk2::Style draw_* methods have been removed (cross, oval, ramp) and +others have been added (expander, layout). This will require changes to theme +engines. =item o @@ -309,27 +286,19 @@ Note that the automatic memory management of Glib::Object removes the need for the ->destroy functions that were bound for many of the old GDK objects; in fact, they weren't really necessary in Gtk-Perl, either. gtk_widget_popup() -was removed, it was only usable for GtkWindows, and there the same effect can -be achieved by gtk_window_move() and gtk_widget_show(). - - -=item o - -gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the pixmap when the -GdkPixmap is finalized. This change corresponds to the behavior of -gdk_window_foreign_new(), and fixes a lot of problems with code where the -pixmap wasn't supposed to be freed. If XFreePixmap() is needed, it can be -done using the destroy-notification facilities of g_object_set_data(). +was removed, it was only usable for Gtk2::Windows, and there the same effect +can be achieved by Gtk2::Window::move() and Gtk2::Widget::show(). +=item o -=item GtkProgress/GtkProgressBar had serious problems in GTK+ 1.2. +Gtk::Progress/Gtk::ProgressBar had serious problems in GTK+ 1.2. =over =item - Only 3 or 4 functions are really needed for 95% of progress interfaces; -GtkProgress/GtkProgressBar had about 25 functions, and didn't even include +Gtk::Progress/Gtk::ProgressBar had about 25 functions, and didn't even include these 3 or 4. =item - @@ -350,7 +319,7 @@ =item - -The split between GtkProgress and GtkProgressBar makes no sense whatsoever. +The split between Gtk::Progress and Gtk::ProgressBar makes no sense whatsoever. =back @@ -395,23 +364,23 @@ =item o -The "draw" signal and virtual method on GtkWidget have been removed. All +The "draw" signal and virtual method on Gtk::Widget have been removed. All drawing should now occur by invalidating a region of the widget (call Gtk2::Gdk::Window::invalidate_rect() or Gtk2::Widget::queue_draw() for example -to invalidate a region). GTK+ merges all invalid regions, and sends expose +to invalidate a region). GTK+ merges all invalid regions, and sends expose events to the widget in an idle handler for the invalid regions. Gtk::Widget::draw() is deprecated and thus not part of Gtk2. (but still works; -it adds the passed-in area to the invalid region and immediately sends expose -events for the current invalid region.) Most widgets will work fine if you +it adds the passed-in area to the invalid region and immediately sends expose +events for the current invalid region.) Most widgets will work fine if you just delete their "draw" implementation, since they will already have working -expose_event implementations. The draw method was rarely called in practice -anyway. +expose_event implementations. The draw method was rarely called in practice +anyway. =item o The Gtk2::Gdk::Event::Expose has a new "region" field. This can be used instead of the "area" field if you want a more exact representation of the area -to update. +to update. =item o @@ -421,24 +390,24 @@ instead. For the case of container widgets that need to propagate expose events to NO_WINDOW children you can either use Gtk2::Container::propagate_expose(), or chain to the default container expose -handler. +handler. =item o -The "draw_default" and "draw_focus" methods/signals on GtkWidget are gone; +The "draw_default" and "draw_focus" methods/signals on Gtk::Widget are gone; simply draw things in your expose handler. Gtk::Widget::draw_focus() and Gtk::Widget::draw_default() wrapper functions are also gone; just queue a draw -on the widget, or the part affected by the focus/default anyway. Also, -GtkWidget now has default implementations for focus_in_event and +on the widget, or the part affected by the focus/default anyway. Also, +Gtk2::Widget now has default implementations for focus_in_event and focus_out_event. These set/unset the 'has-focus' flag, and queue a draw. So -if your focus in/out handler just does that, you can delete it. +if your focus in/out handler just does that, you can delete it. =item o -GtkText and GtkTree are buggy and broken. GTK+ doesn't recommend using them, -and in fact they plan to remove them from future versions, so we didn't bind -them in Gtk2-Perl. The recommended alternatives are Gtk2::TextView and -Gtk2::TreeView. +Gtk::Text and Gtk::Tree are buggy and broken. GTK+ doesn't recommend using +them, and in fact they plan to remove them from future versions, so we didn't +bind them in Gtk2-Perl. The recommended alternatives are Gtk2::TextView and +Gtk2::TreeView. =item o @@ -475,10 +444,11 @@ =item o -GtkRange/GtkScrollbar/GtkScale were rewritten; this means that most theme -engines won't draw them properly, and any custom subclasses of these widgets -will need a rewrite (though if you could figure out how to subclass the old -version of GtkRange, you have our respect). Also, GtkTroughType is gone. +Gtk2:.Range/Gtk2::Scrollbar/Gtk2::Scale were rewritten; this means that most +theme engines won't draw them properly, and any custom subclasses of these +widgets will need a rewrite (though if you could figure out how to subclass the +old version of GtkRange, you have our respect). Also, Gtk::TroughType is +gone. Here are some notable changes: @@ -496,32 +466,27 @@ =item - -Added min_slider_length, fixed_slider_length properties to GtkScrollbar. - -=item - - -Cleaned some private (or at least useless) functions out of gtkscale.h, e.g. -gtk_scale_value_width. +Added min_slider_length, fixed_slider_length properties to Gtk2::Scrollbar. =item - -Moved key bindings from subclasses to GtkScale, even arrow keys, since blind +Moved key bindings from subclasses to Gtk2::Scale, even arrow keys, since blind users don't know scale orientation. =item - -Changed move_slider action signal to use new GtkScrollType, remove -GtkTroughType argument. +Changed move_slider action signal to use new Gtk2::ScrollType, remove +Gtk::TroughType argument. =item - Digits rounds the values a range will input to the given number of decimals, but will not try to force adjustment values set by other controllers. That is, -we no longer modify adjustment->value inside a value_changed handler. +we no longer modify $adjustment->value inside a value_changed handler. =item - -Added getters for GtkScale setters. +Added getters for Gtk2::Scale setters. =item - @@ -553,27 +518,23 @@ the offscreen areas. In most cases, code using Gtk::Gdk::Image::get() should really be ported to Gtk2::Gdk::Pixbuf::get_from_drawable(). - =item o -gtk_widget_set_usize() has been renamed to gtk_widget_set_size_request(), -however the old name still exists unless you define GTK_DISABLE_DEPRECATED. - +Gtk::Widget::set_usize() has been renamed to Gtk2::Widget::set_size_request(). =item o -gtk_widget_set_uposition() is deprecated; use gtk_window_move(), -gtk_fixed_put(), or gtk_layout_put() instead. - +Gtk::Widget::set_uposition() has been deprecated and is not bound anymore; use +Gtk2::Window::move(), Gtk2::Fixed::put(), or Gtk2::Layout::put() instead. =item o -gtk_window_set_policy() is deprecated. To get the effect of "allow_shrink", +Gtk::Window::set_policy() is deprecated. To get the effect of "allow_shrink", call C<< $window->set_size_request (0, 0) >>. To get the effect of "allow_grow", call C<< $window->set_resizable (TRUE) >>. You didn't want the effect of "auto_shrink", it made no sense. But maybe if you were using it you want to use C<< $window->resize (1, 1) >> to snap a window back to its minimum -size (the 1, 1 will be rounded up to the minimum window size). +size (the 1, 1 will be rounded up to the minimum window size). =item o @@ -583,19 +544,21 @@ methods to map and realize children. However, there are a couple of things to watch out for here: -=item o +=over + +=item - If the parent is realized before the add() happens, Gtk2::Widget::set_parent_window() must be called before Gtk2::Widget::set_parent(), since Gtk2::Widget::set_parent() will realize the child. -=item o +=item - If a container depended on its children not being mapped unless it did so -itself (for example, GtkNotebook only mapped the current page), then the -new function gtk_widget_set_child_visible() must be called to keep -widgets that should not be mapped not mapped. +itself (for example, Gtk::Notebook only mapped the current page), then the new +function Gtk2::Widget::set_child_visible() must be called to keep widgets that +should not be mapped not mapped. As part of this change, most containers also will no longer need custom implementations of the map() and unmap() virtual functions. The only cases @@ -603,19 +566,21 @@ =over -=item - +=item o For !NO_WINDOW widgets, if you create children of $widget->window and don't map them in realize() then you must map them in map(). [ In almost all cases, you can simply map the windows in realize(). ] -=item - +=item o For NO_WINDOW widgets, if you create windows in your realize() method, you must map then in map() and unmap them in unmap(). =back +=back + =item o Gtk::Widget::set_default_style(), Gtk::Widget::push_style(), and @@ -629,22 +594,19 @@ widget. To create a Gtk2::Image widget from a Gtk2::Gdk::Image (the least common usage of Gtk2::Gdk::Image), use Gtk2::Image::new_from_image(). - =item o -GTK_SELECTION_EXTENDED is now deprecated, and neither the GtkList/GtkTree nor -the GtkCList/GtkCTree support GTK_SELECTION_EXTENDED anymore. However, the old -extended behavior replaces MULTIPLE behavior. +GTK_SELECTION_EXTENDED is now deprecated. However, the old extended behavior +is replaced by MULTIPLE behavior. =item o The handling of colormaps and widgets has been changed: -The default colormap for widgets is now the GdkRGB colormap, not the system -default colormap. If you try to use resources created for a widget (e.g., -$widget->style) with a window using the system colormap, errors will result on -some machines. - +The default colormap for widgets is now the Gtk2::Gdk::Rgb colormap, not the +system default colormap. If you try to use resources created for a widget +(e.g., $widget->style) with a window using the system colormap, errors will +result on some machines. Gtk2::Widget::push_colormap()/Gtk2::Widget::pop_colormap() only cause the colormap to be explicitly set on toplevel widgets, not on all widgets. The @@ -652,7 +614,6 @@ is determined by finding the nearest ancestor with a colormap set on it explicitly, or if that fails, the default colormap. - =item o The default selected day for Gtk2::Calendar is now the current day in the @@ -672,11 +633,7 @@ =item o The Gtk::Preview is deprecated; just use a Gtk2::Image to display a -Gtk2::Gdk::Pixbuf, instead. -- The GtkPreviewInfo struct has had its visual -and colormap fields removed. Also, gtk_preview_get_cmap() and -gtk_preview_get_visual() are deprecated, as GdkRGB works on any colormap and -visual. You no longer need to gtk_widget_push_cmap (gtk_preview_get_cmap ()) -in your code. +Gtk2::Gdk::Pixbuf, instead. =item o @@ -696,7 +653,7 @@ If you are deriving from one of these widgets, you need to adapt your code appropriately -- for instance, drawing coordinates start from -widget->allocation.x, widget->allocation.y. +$widget->allocation->x, $widget->allocation->y. =item - @@ -704,33 +661,26 @@ sure you call Gtk2::Container::propagate_expose() correctly, as you must for any NO_WINDOW widgets. -=back +=item - -GtkFixed is a little special; it is now created by default as a NO_WINDOW -widget, but if you do +Gtk2::Fixed is a little special; it is now created by default as a NO_WINDOW +widget, but if you do $fixed->set_has_window (TRUE); after creating a fixed widget, it will create a window and handle it properly. +=back =item o -Gtk2::Layout no longer has the xoffset, yoffset fields, which used to store the -difference between world and window coordinates for layout->bin_window. These -coordinate systems are now always the same. - - -=item o - -Gtk2::paint_focus(), Gtk2::draw_focus() and Gtk2::Style's draw_focus virtual -function have been changed a bit: +Gtk2::Style::paint_focus(), has been changed a bit: =over =item - -A Gtk2::StateType argument has been added to Gtk2::paint_focus(). +A Gtk2::StateType argument has been added. =item - @@ -741,8 +691,8 @@ =item - The rectangle passed in is the bounding box, instead of the rectangle used in -the Gtk2::Gdk::draw_rectangle() call, so it is no longer necessary to subtract -1 from the width and height. +the Gtk2::Gdk::Drawable::draw_rectangle() call, so it is no longer necessary to +subtract 1 from the width and height. =back