changes-2.0.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<refentry id="gtk-changes-2-0" revision="1 Jan 2002">
<refmeta>
<refentrytitle>Changes from 1.2 to 2.0</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Changes from 1.2 to 2.0</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Changes from 1.2 to 2.0</refname>
<refpurpose>
Incompatible changes made between version 1.2 and version 2.0
</refpurpose>
</refnamediv>


<refsect1>
<title>Incompatible changes from 1.2 to 2.0</title>

<para>
The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
porting guide</ulink> on <ulink
url="http://developer.gnome.org">http://developer.gnome.org</ulink>
has some more detailed discussion of porting from 1.2 to 2.0.
See the sections on GLib and GTK+.
</para>

<para>
GTK+ changed fairly substantially from version 1.2 to 2.0, much more
so than from 1.0 to 1.2. Subsequent updates (possibilities are 2.0 to
2.2, 2.2 to 2.4, then to 3.0) will almost certainly be much, much
smaller. Nonetheless, most programs written for 1.2 compile against
2.0 with few changes. The bulk of changes listed below are to obscure
features or very specialized features, and compatibility interfaces
exist whenever possible.
</para>

<itemizedlist>

<listitem>
<para>
<function>gtk_container_get_toplevels()</function> was removed and replaced 
  with <function>gtk_window_list_toplevels()</function>, which has different 
  memory management on the return value 
  (<function>gtk_window_list_toplevels()</function> copies the 
  <structname>GList</structname> and also references each widget in the list, 
  so you have to <function>g_list_free()</function> the list after first 
  unref'ing each list member).
</para>
</listitem>

<listitem>
<para>
The <function>gdk_time*</function> functions have been removed. This 
  functionality has been unused since the main loop was moved into GLib
  prior to 1.2. 
</para>
</listitem>

<listitem>
<para>
The signature for <function>GtkPrintFunc</function> (used for 
  <function>gtk_item_factory_dump_items()</function>)
  has been changed to take a <type>const gchar *</type> instead of 
  <type>gchar *</type>, to match what we do for GLib, and other similar cases.
</para>
</listitem>

<listitem>
<para>
The detail arguments in the <structname>GtkStyleClass</structname> structure 
are now <type>const gchar *</type>.
</para>
</listitem>

<listitem>
<para>
<function>gtk_paned_set_gutter_size()</function> has been removed, since the 
  small handle tab has been changed to include the entire area previously 
  occupied by the gutter.
</para>
</listitem>

<listitem>
<para>
<function>gtk_paned_set_handle_size()</function> has been removed, in favor of 
  a style property, since this is an option that only makes sense for themes 
  to adjust.
</para>
</listitem>

<listitem>
<para>
GDK no longer selects OwnerGrabButtonMask for button presses. This means  
  that the automatic grab that occurs when the user presses a button
  will have <literal>owner_events = FALSE</literal>, so all events are 
  redirected to the grab window, even events that would normally go to
  other windows of the window's owner.
</para>
</listitem>

<listitem>
<para>
<structname>GtkColorSelectionDialog</structname> has now been moved into it's 
  own set of files, <filename>gtkcolorseldialog.c</filename> and 
  <filename>gtkcolorseldialog.h</filename>.
</para>
</listitem>

<listitem>
<para>
<function>gtk_widget_shape_combine_mask()</function> now keeps a reference 
  count on the mask pixmap that is passed in.
</para>
</listitem>

<listitem>
<para>
The <structname>GtkPatternSpec</structname> has been moved to GLib as 
  <structname>GPatternSpec</structname>, the pattern
  arguments to <function>gtk_item_factory_dump_items()</function> and 
  <function>gtk_item_factory_dump_rc()</function>
  have thusly been changed to take a <structname>GPatternSpec</structname> 
  instead of a <structname>GtkPatternSpec</structname>.
</para>
</listitem> 

<listitem>
<para>
Type system changes:
<itemizedlist>
<listitem>
<para>
   <literal>GTK_TYPE_OBJECT</literal> is not a fundamental type anymore. Type checks of the
    style <literal>(GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)</literal>
    will not work anymore. As a replacement, <literal>(GTK_TYPE_IS_OBJECT (some_type))</literal>
    can be used now.
</para>
</listitem>
<listitem>
<para>
The following types vanished: <literal>GTK_TYPE_ARGS</literal>, <literal>GTK_TYPE_CALLBACK</literal>,
    <literal>GTK_TYPE_C_CALLBACK</literal>, <literal>GTK_TYPE_FOREIGN</literal>. The corresponding <structname>GtkArg</structname>
    fields and field access macros are also gone.
</para>
</listitem>
<listitem>
<para>
The following type aliases vanished: <literal>GTK_TYPE_FLAT_FIRST</literal>,
    <literal>GTK_TYPE_FLAT_LAST</literal>, <literal>GTK_TYPE_STRUCTURED_FIRST</literal>,
    <literal>GTK_TYPE_STRUCTURED_LAST</literal>.
</para>
</listitem>
<listitem>
<para>
The type macros <function>GTK_TYPE_MAKE()</function> and <function>GTK_TYPE_SEQNO()</function> vanished, use of
    <function>GTK_FUNDAMENTAL_TYPE()</function> is discouraged. Instead, the corresponding <structname>GType</structname>
    API should be used: <function>G_TYPE_FUNDAMENTAL()</function>, <function>G_TYPE_DERIVE_ID()</function>,
    <function>G_TYPE_BRANCH_SEQNO()</function>. Note that the GLib type system doesn't build new
    type ids based on a global incremental sequential number anymore, but
    numbers new type ids sequentially per fundamental type branch.
</para>
</listitem>
<listitem>
<para>
The following type functions vanished/were replaced:
<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Old Function</entry><entry>Replacement</entry></row>
</thead>
<tbody>
<row><entry><function>gtk_type_query()</function></entry><entry>being investigated</entry></row>
<row><entry><function>gtk_type_set_varargs_type()</function></entry><entry>-</entry></row>
<row><entry><function>gtk_type_get_varargs_type()</function></entry><entry>-</entry></row>
<row><entry><function>gtk_type_check_object_cast()</function></entry><entry><function>g_type_check_instance_cast()</function></entry></row>
<row><entry><function>gtk_type_check_class_cast()</function></entry><entry><function>g_type_check_class_cast()</function></entry></row>
<row><entry><function>gtk_type_describe_tree()</function></entry><entry>-</entry></row>
<row><entry><function>gtk_type_describe_heritage()</function></entry><entry>-</entry></row>
<row><entry><function>gtk_type_free()</function></entry><entry>-</entry></row>
<row><entry><function>gtk_type_children_types()</function></entry><entry><function>g_type_children()</function></entry></row>
<row><entry><function>gtk_type_set_chunk_alloc()</function></entry><entry><structfield>GTypeInfo.n_preallocs</structfield></entry></row>
<row><entry><function>gtk_type_register_enum()</function></entry><entry><function>g_enum_register_static()</function></entry></row>
<row><entry><function>gtk_type_register_flags()</function></entry><entry><function>g_flags_register_static()</function></entry></row>
<row><entry><function>gtk_type_parent_class()</function></entry><entry><function>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
</tbody>
</tgroup>
</informaltable>
    Use of <function>g_type_class_ref()</function>/<function>g_type_class_unref()</function> and <function>g_type_class_peek()</function>
    is recommended over usage of <function>gtk_type_class()</function>.
    Use of <function>g_type_register_static()</function>/<function>g_type_register_dynamic()</function> is recommended
    over usage of <function>gtk_type_unique()</function>.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>

<listitem>
<para>
Object system changes:
  <structname>GtkObject</structname> derives from <structname>GObject</structname>, so is not the basic object type anymore.
  This imposes the following source incompatible changes:
<itemizedlist>

<listitem>
<para>
<structname>GtkObject</structname> has no <structfield>klass</structfield> field anymore, an object's class can be retrieved
    with the object's coresponding <literal>GTK_&lt;OBJECT&gt;_GET_CLASS (object)</literal>
    macro.
</para>
</listitem>
<listitem>
<para>
<structname>GtkObjectClass</structname> has no <structfield>type</structfield> field anymore, a class's type can be retrived
    with the <literal>GTK_CLASS_TYPE (class)</literal> macro.
</para>
</listitem>
<listitem>
<para>
<structname>GtkObjectClass</structname> does not introduce the <function>finalize()</function> and <function>shutdown()</function> methods
    anymore. While <function>shutdown()</function> is intended for GTK+ internal use only, <function>finalize()</function>
    is required by a variety of object implementations. <function>GObjectClass.finalize</function>
    should be overriden here, e.g.:
<informalexample><programlisting>
    static void gtk_label_finalize (GObject *gobject)
    {
      GtkLabel *label = GTK_LABEL (gobject);
      
      G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
    }
    static void gtk_label_class_init (GtkLabelClass *class)
    {
      GObjectClass *gobject_class = G_OBJECT_CLASS (class);
      
      gobject_class-&gt;finalize = gtk_label_finalize;
    }
</programlisting></informalexample>
</para>
</listitem>

</itemizedlist>
</para>
</listitem>

<listitem>
<para>
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. For example:
<informalexample><programlisting>
    if (object-&gt;foo_data)
      { 
        g_free (object-&gt;foo_data);
        object-&gt;foo_data = NULL;
      }
</programlisting></informalexample>

    Also, ::destroy implementations have to release object references that
    the object holds. Code in finalize implementations such as:
<informalexample><programlisting>
    if (object-&gt;adjustment)
      {
        gtk_object_unref (object-&gt;adjustment);
        object-&gt;adjustment = NULL;
      }
</programlisting></informalexample>
    have to be moved into the ::destroy implementations. The reason for doing
    this is that all object reference cycles should be broken at destruction 
    time.

    Because the ::destroy signal can be emitted multiple times, it no longer
    makes sense to check if a widget has been destroyed using the 
    <function>GTK_OBJECT_DESTROYED()</function> macro, and this macro has been 
    removed. If catching destruction is still needed, it can be done with a 
    signal connection to ::destroy.
</para>
</listitem>
    
<listitem>
<para>
Signal system changes:
  The GTK+ 2.0 signal system merely proxies the <structname>GSignal</structname> 
  system now. For future usage, direct use of the 
  <structname>GSignal</structname> API is recommended,
  this avoids significant performance hits where <structname>GtkArg</structname>
  structures have to be converted into <structname>GValue</structname>s. For 
  language bindings, <structname>GSignal</structname>+<structname>GClosure</structname>
  provide a much more flexible and convenient mechanism to hook into signal 
  emissions or install class default handlers, so the old 
  <structname>GtkSignal</structname> API for language bindings is not
  supported anymore.
</para>
<para>
  Functions that got removed in the GTK+ signal API:
  <function>gtk_signal_n_emissions()</function>, 
  <function>gtk_signal_n_emissions_by_name()</function>,
  <function>gtk_signal_set_funcs()</function>, 
  <function>gtk_signal_handler_pending_by_id()</function>,
  <function>gtk_signal_add_emission_hook()</function>, 
  <function>gtk_signal_add_emission_hook_full()</function>,
  <function>gtk_signal_remove_emission_hook()</function>, 
  <function>gtk_signal_query()</function>.
  Also, the <structname>GtkCallbackMarshal</structname> argument to 
  <function>gtk_signal_connect_full()</function> is
  not supported anymore.
  For many of the removed functions, similar variants are available
  in the <function>g_signal_*</function> namespace.
  The <structname>GSignal</structname> system performs emissions in a 
  slightly different manner than the old <structname>GtkSignal</structname> 
  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.
</para>
</listitem>

<listitem>
<para>
Inserting and deleting text in <structname>GtkEntry</structname> though 
  functions such as <function>gtk_entry_insert_text()</function> now leave 
  the cursor at its original position in the text instead of moving it to 
  the location of the insertion/deletion.
</para>
</listitem>

<listitem>
<para>
The <structfield>label</structfield> field of <structname>GtkFrame</structname> 
  widgets has been removed (as part of a change to allow arbitrary widgets 
  in the title position). The text can now be retrieved with the new function 
  <function>gtk_frame_get_text()</function>.
</para>
</listitem>

<listitem>
<para>
The 'font' and 'font_set' declarations in RC files are now ignored. There
  is a new 'font_name' field that holds the string form of a Pango font.
</para>
</listitem>

<listitem>
<para>
A number of types in GDK have become subclasses of 
  <structname>GObject</structname>. For the most part, this should not break 
  anyone's code. However, it's now possible/encouraged to use 
  <function>g_object_ref()</function>/<function>g_object_unref()</function> and
  other <structname>GObject</structname> features with these GDK types. The 
  converted types are:
  <structname>GdkWindow</structname>, <structname>GdkDrawable</structname>, 
  <structname>GdkPixmap</structname>, <structname>GdkImage</structname>, 
  <structname>GdkGC</structname>, <structname>GdkDragContext</structname>,
  <structname>GdkColormap</structname>.
</para>
</listitem>

<listitem>
<para>
All drawables including pixmaps used to have a type tag, the
  <structname>GdkWindowType</structname> enumeration, which included 
  <literal>GDK_WINDOW_PIXMAP</literal>.
  <structname>GdkWindowType</structname> is now a property of 
  <structname>GdkWindow</structname> <emphasis>only</emphasis>, and there is 
  no <literal>GDK_WINDOW_PIXMAP</literal>. You can use the 
  <function>GDK_IS_PIXMAP()</function> macro to see if you have a pixmap, if
  you need to know that.
</para>
</listitem>

<listitem>
<para>
<structname>GtkStyle</structname> and <structname>GtkRcStyle</structname> are 
  now subclasses of <structname>GObject</structname> as well.  This
  requires fairly extensive changes to theme engines, but
  shouldn't affect most other code.
</para>
</listitem>

<listitem>
<para>
<structfield>xthickness</structfield> and <structfield>ythickness</structfield> have moved from 
  <structname>GtkStyleClass</structname> to <structname>GtkStyle</structname>
  (from class to instance). This gives themes a bit more flexibility
  and is generally more of the Right Thing. You can trivially fix
  your code with <literal>s/style-&gt;klass-&gt;xthickness/style-&gt;xthickness/g</literal> and 
  same for <literal>ythickness</literal>.
</para>
</listitem>

<listitem>
<para>
Some <structname>GtkStyle</structname> <function>draw_*</function> methods 
  have been removed (cross, oval, ramp)