changes-2.0.sgml

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

<function>gtk_rc_load_image()</function> have been removed, now 
  that GTK+ includes decent image loading capabilities itself.
</para>
</listitem>

<listitem>
<para>
An extra <structname>GtkSettings</structname> argument has been added to
  <function>gtk_rc_find_pixmap_in_path()</function>. This function is only 
  actually useful from a theme engine during parsing, at which point the 
  <structname>GtkSettings</structname> is provided.
</para>
</listitem>

<listitem>
<para>
The child argument facility in <filename>gtkcontainer.c</filename> has been 
  converted to a child property facility using 
  <structname>GParamSpec</structname> and other facilities
  for <structname>GObject</structname>.   
</para>
</listitem>

 <listitem>
<para>
The <function>set_child_arg()</function> and <function>get_child_arg()</function> 
     virtual methods have been replaced with <function>set_child_property()</function>/<function>get_child_property()</function>, which
     work similar to GObject-&gt;set_property/get_property.
</para>
</listitem>


 <listitem>
<para>
Other removed <structname>GtkContainer</structname> functions with the replacements:

<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Old function</entry><entry>Replacement</entry></row>
</thead>
<tbody>
<row><entry><function>gtk_container_add_child_arg_type</function></entry><entry><function>gtk_container_class_install_child_property</function></entry></row>
<row><entry><function>gtk_container_query_child_args</function></entry><entry><function>gtk_container_class_list_child_properties</function></entry></row>
<row><entry><function>gtk_container_child_getv</function></entry><entry><function>gtk_container_child_set_property</function></entry></row>
<row><entry><function>gtk_container_child_setv</function></entry><entry><function>gtk_container_child_get_property</function></entry></row>
<row><entry><function>gtk_container_add_with_args</function></entry><entry><function>gtk_container_add_with_properties</function></entry></row>
<row><entry><function>gtk_container_addv</function></entry><entry><function>gtk_container_add</function>/<function>gtk_container_child_set_property</function></entry></row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>


<listitem>
<para>
<function>gdk_image_get()</function> (or rather its replacement,
  <function>gdk_drawable_get_image()</function>) now handles errors properly 
  by returning <literal>NULL</literal>, previously it would crash. Also, a 
  window being offscreen is no longer considered an error; instead, the area 
  contains undefined contents for the offscreen areas. In most cases, code
  using <function>gdk_image_get()</function> should really be ported to
  <function>gdk_pixbuf_get_from_drawable()</function>.
</para>
</listitem>

<listitem>
<para>
<function>gtk_widget_set_usize()</function> has been renamed to
  <function>gtk_widget_set_size_request()</function>, however the old name 
  still exists unless you define <literal>GTK_DISABLE_DEPRECATED</literal>.
</para>
</listitem>

<listitem>
<para>
<function>gtk_widget_set_uposition()</function> is deprecated; use
  <function>gtk_window_move()</function>, 
  <function>gtk_fixed_put()</function>, or <function>gtk_layout_put()</function>
  instead.
</para>
</listitem>

<listitem>
<para>
<function>gtk_window_set_policy()</function> is deprecated. To get the effect of
  "allow_shrink", call 
  <literal>gtk_widget_set_size_request (window, 0, 0)</literal>. To get the 
  effect of "allow_grow", call 
  <literal>gtk_window_set_resizable (window, TRUE)</literal>. You didn't want 
  the effect of "auto_shrink", it made no sense. But maybe if you were using 
  it you want to use <literal>gtk_window_resize (window, 1, 1)</literal> to 
  snap a window back to its minimum size (the 1, 1 will be rounded up to the 
  minimum window size).
</para>
</listitem>

<listitem>
<para>
The core GTK+ now takes care of handling mapping, unmapping and
  realizing the child widgets of containers in
  <function>gtk_widget_set_parent()</function>. In most cases, this allows 
  container implementations to be simplified by removing the code in 
  <function>add()</function> methods to map and realize children. However, 
  there are a couple of things to watch out for here:
</para>
</listitem>


 <listitem>
<para>
If the parent is realized before the <function>add()</function> happens, 
     <function>gtk_widget_set_parent_window()</function> must be called before
     <function>gtk_widget_set_parent()</function>, since 
     <function>gtk_widget_set_parent()</function> will realize the child.
</para>
</listitem>

 <listitem>
<para>
If a container depended on its children not being mapped
     unless it did so itself (for example, <structname>GtkNotebook</structname>
     only mapped the current page), then the new function
     <function>gtk_widget_set_child_visible()</function> must be called to keep
     widgets that should not be mapped not mapped.
</para>

<para>
  As part of this change, most containers also will no longer need custom 
  implementations of the <function>map()</function> and 
  <function>unmap()</function> virtual functions. The only cases where this 
  is necessary are:

<itemizedlist>
 <listitem>
<para>
For <literal>!NO_WINDOW</literal> widgets, if you create children of 
     <literal>widget-&gt;window</literal>
     and don't map them in <function>realize()</function> then you must map them
     in <function>map()</function>. [ In almost all cases, you can simply map the
     windows in <function>realize()</function>. ]
</para>
</listitem>

 <listitem>
<para>
For <literal>NO_WINDOW</literal> widgets, if you create windows in your 
     <function>realize()</function> method, you must map then in 
     <function>map()</function> and unmap them in <function>unmap()</function>.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>

<listitem>
<para>
<function>gtk_widget_set_default_style()</function>, 
   <function>gtk_widget_push_style()</function>,
  and <function>gtk_widget_pop_style()</function> have been removed, since they
  did not work properly with themes and there were better
  alternatives for modifying the appearance of widgets.

  You should generally use <function>gtk_widget_modify_*()</function>
  instead.
</para>
</listitem>

  
<listitem>
<para>
<function>gtk_image_new()</function> now takes no arguments and creates an 
  empty <structname>GtkImage</structname> widget. To create a 
  <structname>GtkImage</structname> widget from a 
  <structname>GdkImage</structname> (the least
  common usage of <structname>GdkImage</structname>), use 
  <function>gtk_image_new_from_image()</function>.
</para>
</listitem>

<listitem>
<para>
<literal>GTK_SELECTION_EXTENDED</literal> is now deprecated, and neither the
  <structname>GtkList</structname>/<structname>GtkTree</structname> nor the 
  <structname>GtkCList</structname>/<structname>GtkCTree</structname> support
  <literal>GTK_SELECTION_EXTENDED</literal> anymore.  However, the old extended
  behavior replaces <literal>MULTIPLE</literal> behavior.
</para>
</listitem>

<listitem>
<para>
The following variables are no longer exported from GDK. (Other variables
  are also no longer exported; the following are the ones found used
  externally in a large sample of GTK+ code.)

<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Variable</entry><entry>Replacement</entry></row>
</thead>
<tbody>
<row><entry><literal>gdk_null_window_warnings</literal></entry><entry>None - did nothing in GTK+ 1.2</entry></row>
<row><entry><literal>gdk_leader_window</literal></entry><entry>None - private variable</entry></row>
<row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
<row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
<row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
<row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
<row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
<row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
<row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
<row><entry><literal>gdk_wm_take_focus</literal></entry><entry><literal>gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)</literal></entry></row>
<row><entry><literal>gdk_wm_protocols</literal></entry><entry><literal>gdk_atom_intern ("WM_PROTOCOLS", FALSE)</literal></entry></row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
   

<listitem>
<para>
The handling of colormaps and widgets has been changed:

<itemizedlist>
  <listitem>
<para>
The default colormap for widgets is now the <structname>GdkRGB</structname> 
      colormap, not the system default colormap. If you try to use resources 
      created for  a widget (e.g., <literal>widget-&gt;style</literal>) with 
      a window using the system colormap, errors will result on some machines.
</para>
</listitem>


  <listitem>
<para>
<function>gtk_widget_push()</function>/<function>gtk_widget_pop_colormap()</function> 
      only cause the colormap to be explicitly set on toplevel widgets, not on 
      all widgets. The colormap for other widgets (when not set using 
      <function>gtk_widget_set_colormap()</function>), is determined by finding
      the nearest ancestor with a colormap set on it explicitly, or if that
      fails, the default colormap.
</para>
</listitem>

</itemizedlist>

</para>
</listitem>


<listitem>
<para>
The default selected day for <structname>GtkCalendar</structname> is now the 
  current day in the month, not the first day in the month. The current month 
  and year were already used.
</para>
</listitem>


<listitem>
<para>
GDK is no longer put into threaded mode automatically when 
  <function>g_thread_init()</function> has been called. In order to use the 
  global GDK thread mutex with <function>gdk_threads_enter()</function> and 
  <function>gdk_threads_leave()</function>, you must call 
  <function>gdk_threads_init()</function> explicitly.

  If you aren't using GDK and GTK+ functions from multiple threads,
  there is no reason to call <function>gdk_threads_init()</function>.
</para>
</listitem>

<listitem>
<para>
The <structname>GtkPreviewInfo</structname> struct has had its visual and 
  colormap fields removed.  Also, <function>gtk_preview_get_cmap()</function> 
  and <function>gtk_preview_get_visual()</function> are deprecated, as 
  <structname>GdkRGB</structname> works on any colormap and visual.  You no
  longer need to 
  <literal>gtk_widget_push_cmap (gtk_preview_get_cmap ())</literal> in
  your code.
</para>
</listitem>


<listitem>
<para>
The <structname>GtkBox</structname>, <structname>GtkTable</structname>, and 
  <structname>GtkAlignment</structname> widgets now call
  <literal>gtk_widget_set_redraw_on_allocate (widget, FALSE);</literal> on 
  themselves. If you want to actually draw contents in a widget derived from
  one of these widgets, you'll probably want to change this
  in your <function>init()</function> function.
</para>
</listitem>


<listitem>
<para>
A number of widgets are now <literal>NO_WINDOW</literal> widgets (most 
  importantly <structname>GtkButton</structname>, but also 
  <structname>GtkRange</structname> and <structname>GtkNotebook</structname>)

  This has a couple of effects:

<itemizedlist>
 <listitem>
<para>
If you are deriving from one of these widgets, you need to
     adapt your code appropriately -- for instance, drawing coordinates
     start from <literal>widget-&gt;allocation.x, widget-&gt;allocation.y</literal>.
</para>
</listitem>


 <listitem>
<para>
If you are embedding one of these widgets in a custom widget,
     you must make sure you call <function>gtk_container_propagate_expose()</function>
     correctly, as you must for any <literal>NO_WINDOW</literal> widgets.
</para>
</listitem>
</itemizedlist>
</para>

<para>
  <structname>GtkFixed</structname> is a little special; it is now created by 
  default as a <literal>NO_WINDOW</literal> widget, but if you do 

<programlisting>
    gtk_fixed_set_has_window (fixed, TRUE);
</programlisting>

  after creating a fixed widget, it will create a window and
  handle it properly.
</para>
</listitem>

<listitem>
<para>
<structname>GtkLayout</structname> no longer has the <structfield>xoffset</structfield>,
  <structfield>yoffset</structfield> fields, which used to store the difference between
  world and window coordinates for <literal>layout-&gt;bin_window</literal>. 
  These coordinate systems are now always the same.
</para>
</listitem>

<listitem>
<para>
<function>gtk_paint_focus()</function>, <function>gtk_draw_focus()</function> 
  and <function>GtkStyle::draw_focus()</function>
  have been changed a bit:

<itemizedlist>
 <listitem>
<para>
A <literal>GtkStateType</literal> argument has been added to <function>gtk_paint_focus()</function>.
</para>
</listitem>

 <listitem>
<para>
The default implementation of the <function>GtkStyle::draw_focus()</function> 
     virtual function now draws a focus rectangle whose width is 
     determined by the GtkWidget::focus-width style property.
</para>
</listitem>

 <listitem>
<para>
The rectangle passed in is the bounding box, instead of
     the rectangle used in the <function>gdk_draw_rectangle()</function> call, 
     so it is no longer necessary to subtract 1 from the width and height.
</para>
</listitem>

</itemizedlist>

</para>
</listitem>


</itemizedlist>

</refsect1>

</refentry>