changes-2.0.sgml

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

  and others have been added (expander, layout). This will require
  changes to theme engines.
</para>
</listitem>

<listitem>
<para>
If you were using private GDK types, they have been rearranged
  significantly. You shouldn't use private types. ;-) 
</para>
</listitem>

<listitem>
<para>
The visual for a widget, and also the default visual is now derived
  from the colormap for the widget and the default colormap.
  <function>gtk_widget_set_visual()</function>, 
  <function>gtk_widget_set_default_visual()</function>,
  <function>gtk_widget_push_visual()</function> and 
  <function>gtk_widget_pop_visual()</function> now do
  nothing. Since the visual always had to match that of the colormap,
  it is safe to simply delete all references to these functions.
</para>
</listitem>


<listitem>
<para>
A number of functions in GDK have been renamed for consistency and
  clarity. #defines to provide backwards compatibility have been
  included, but can be disabled by defining <literal>GDK_DISABLE_DEPRECATED</literal>.

<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Old function</entry><entry>Defined As</entry></row>
</thead>
<tbody>
<row><entry><function>gdk_draw_pixmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>
 <row><entry><function>gdk_draw_bitmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>               
<row><entry><function>gdk_window_get_size</function></entry><entry><function>gdk_drawable_get_size</function></entry></row>               
<row><entry><function>gdk_window_get_type</function></entry><entry><function>gdk_window_get_window_type</function></entry></row>               
<row><entry><function>gdk_window_get_colormap</function></entry><entry><function>gdk_drawable_get_colormap</function></entry></row>
<row><entry><function>gdk_window_set_colormap</function></entry><entry><function>gdk_drawable_set_colormap</function></entry></row>
<row><entry><function>gdk_window_get_visual</function></entry><entry><function>gdk_drawable_get_visual</function></entry></row>
<row><entry><function>gdk_window_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
<row><entry><function>gdk_window_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
<row><entry><function>gdk_bitmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
<row><entry><function>gdk_bitmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
<row><entry><function>gdk_pixmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
<row><entry><function>gdk_pixmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
<row><entry><function>gdk_gc_destroy</function></entry><entry><function>gdk_gc_unref</function></entry></row>
<row><entry><function>gdk_image_destroy</function></entry><entry><function>gdk_image_unref</function></entry></row>
<row><entry><function>gdk_cursor_destroy</function></entry><entry><function>gdk_cursor_unref</function></entry></row>
<row><entry><function>gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height)</function></entry><entry><function>gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)</function></entry></row>
<row><entry><function>gdk_rgb_get_cmap</function></entry><entry><function>gdk_rgb_get_colormap</function></entry></row>
</tbody>
</tgroup>
</informaltable>
  (Note that <function>g_object_ref()</function> and 
  <function>g_object_unref()</function> may be used for all of the above ref 
  and unref functions.)

  <function>gtk_widget_popup()</function> was removed, it was only usable 
  for <structname>GtkWindow</structname>s, and there the same effect can be 
  achieved by <function>gtk_window_move()</function> and
  <function>gtk_widget_show()</function>.
</para>
</listitem>

<listitem>
<para>
<function>gdk_pixmap_foreign_new()</function> no longer calls 
  <function>XFreePixmap()</function> on the pixmap when the 
  <structname>GdkPixmap</structname> is finalized. This change corresponds
  to the behavior of <function>gdk_window_foreign_new()</function>, and fixes 
  a lot of problems with code where the pixmap wasn't supposed to be freed. 
  If <function>XFreePixmap()</function> is needed, it can be done using the
  destroy-notification facilities of <function>g_object_set_data()</function>.
</para>
</listitem>

<listitem>
<para>
<structname>GtkProgress</structname>/<structname>GtkProgressBar</structname> 
  had serious problems in GTK+ 1.2.
<itemizedlist>
<listitem>
<para>
Only 3 or 4 functions are really needed for 95% of progress interfaces; 
  <structname>GtkProgress</structname>/<structname>GtkProgressBar</structname> 
  had about 25 functions, and didn't even include these 3 or 4.
</para>
</listitem>

<listitem>
<para>
In activity mode, the API involves setting the adjustment 
    to any random value, just to have the side effect of 
    calling the progress bar update function - the adjustment
    is totally ignored in activity mode.
</para>
</listitem>

<listitem>
<para>
You set the activity step as a pixel value, which means to 
    set the activity step you basically need to connect to 
    size_allocate.
</para>
</listitem>

<listitem>
<para>
There are <function>ctree_set_expander_style()</function>-functions, to 
    randomly change look-and-feel for no good reason.
</para>
</listitem>

<listitem>
<para>
The split between <structname>GtkProgress</structname> and 
<structname>GtkProgressBar</structname> makes no sense to me whatsoever.
</para>
</listitem>

</itemizedlist>

  This was a big wart on GTK+ and made people waste lots of time,
  both learning and using the interface.
  So, we have added what we feel is the correct API, and marked all the
  rest deprecated. However, the changes are 100% backward-compatible and
  should break no existing code.
  The following 5 functions are the new programming interface and you 
  should consider changing your code to use them:
<programlisting>
  void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
  void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
                                                    const gchar    *text);
  void       gtk_progress_bar_set_fraction         (GtkProgressBar *pbar,
                                                    gfloat          fraction);

  void       gtk_progress_bar_set_pulse_step       (GtkProgressBar *pbar,
                                                    gfloat          fraction);
  void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
						    GtkProgressBarOrientation orientation);
</programlisting>
</para>
</listitem>

<listitem>
<para>
The <structname>GtkNotebookPage</structname> structure has been removed from 
  the public header files;
  this was never meant to be a public structure, and all functionality that
  could be done by accessing the struct fields of this structure should be 
  accessible otherwise.
</para>
</listitem>

<listitem>
<para>
Negative values of the <parameter>position</parameter> parameter to
  <function>gtk_notebook_reorder_child()</function> now cause the page to be appended, not
  inserted at the beginning. (This gives consistency with
  <function>gtk_box_reorder_child()</function>, <function>gtk_menu_reorder_child()</function>.)
</para>
</listitem>

<listitem>
<para>
<function>GtkMenuPositionFunc</function> has a new parameter 
  <literal>push_in</literal> which controls how menus placed outside the 
  screen is handled. If this is set to <literal>TRUE</literal> and
  part of the menu is outside the screen then GTK+ pushes it into the visible
  area. Otherwise the menu is cut of at the end of the visible screen area.
</para>
<para>
  Regardless of what happens to the size of the menu, the result is always
  that the items are placed in the same place as if the menu was placed
  outside the screen, using menu scrolling if necessary.
</para>
</listitem>
  
<listitem>
<para>
The "draw" signal and virtual method on <structname>GtkWidget</structname> 
  has been removed.
  All drawing should now occur by invalidating a region of the widget
  (call <function>gdk_window_invalidate_rect()</function> or 
  <function>gtk_widget_queue_draw()</function> for example to invalidate 
  a region). GTK+ merges all invalid regions, and sends expose events to 
  the widget in an idle handler for the invalid regions. 
  <function>gtk_widget_draw()</function> is deprecated 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 just delete their "draw"
  implementation, since they will already have working expose_event
  implementations. The draw method was rarely called in practice
  anyway.
</para>
</listitem>

<listitem>
<para>
The <structname>GdkExposeEvent</structname> has a new <structfield>region</structfield>
  field. This can be used instead of the <structfield>area</structfield> field if you 
  want a more exact representation of the area to update.
</para>
</listitem>

<listitem>
<para>
Sending synthetic exposes using <function>gtk_widget_event()</function> is no 
  longer allowed. If you just need an expose call you should use 
  <function>gdk_window_invalidate_rect()</function> or 
  <function>gdk_window_invalidate_region()</function> instead. For the case 
  of container widgets that need to propagate expose events to 
  <literal>NO_WINDOW</literal> children you can either use 
  <function>gtk_container_propagate_expose()</function>, or chain to the
  default container expose handler.
</para>
</listitem> 

<listitem>
<para>
The draw_default and draw_focus methods/signals on 
  <structname>GtkWidget</structname> are gone; simply draw things in your 
  expose handler. <function>gtk_widget_draw_focus()</function> and 
  <function>gtk_widget_draw_default()</function> wrapper
  functions are also gone; just queue a draw on the widget,  
  or the part affected by the focus/default anyway.
  Also, <structname>GtkWidget</structname> now has default implementations for 
  focus_in_event and focus_out_event. These set/unset 
  <literal>GTK_HAS_FOCUS</literal>, and queue a draw. So if your focus in/out 
  handler just does that, you can delete it.
</para>
</listitem>

<listitem>
<para>
<structname>GtkText</structname> and <structname>GtkTree</structname> are 
  buggy and broken. We don't recommend using them, and changing old code to 
  avoid them is a good idea. The recommended alternatives are 
  <structname>GtkTextView</structname> and <structname>GtkTreeView</structname>.
  The broken widgets are not declared in the headers by default; to use
  them, define the symbol <literal>GTK_ENABLE_BROKEN</literal> during 
  compilation. In some future release, these widgets will be removed from GTK+.
</para>
</listitem>

<listitem>
<para>
<structname>GdkColorContext</structname> is gone; you probably weren't using 
  it anyway.  Use <structname>GdkColormap</structname> and the 
  <function>gdk_rgb_*</function> functions instead.
</para>
</listitem>

<listitem>
<para>
<structname>GtkMenuBar</structname> now draws the <structfield>GtkContainer::border_width</structfield> 
  space outside the frame, not inside the frame.
</para>
</listitem>


<listitem>
<para>
In GTK+ 1.2, if an event handler returned <literal>TRUE</literal> it prevented
  propagation of that event to parent widgets. That is, the 
  event signal would not be emitted on parent widgets. In 
  GTK+ 2.0, if an event handler returns <literal>TRUE</literal>, the current 
  signal emission on the current widget is immediately stopped. That is,
  other callbacks connected to the signal will not be invoked.
</para>
</listitem>

<listitem>
<para>
<function>gtk_toolbar_new()</function> no longer has arguments. This function 
  was broken because the default <literal>GtkToolbarStyle</literal> (icons, 
  text, both) is now a user preference, which is overridden when you call
  <function>gtk_toolbar_set_style()</function>. The constructor forced everyone
  to override the preference, which was undesirable. So to port
  your app, decide if you want to force the toolbar style 
  or conform to the user's global defaults; if you want to force
  it, call <function>gtk_toolbar_set_style()</function>.
</para>

<para>
  The orientation arg was removed from <function>gtk_toolbar_new()</function> 
  as well, just because it wasn't very useful and we were breaking the function
  anyway so had an opportunity to lose it. Call
  <function>gtk_toolbar_set_orientation()</function> to set toolbar orientation.
</para>
</listitem>


<listitem>
<para>
<structname>GtkRange</structname>/<structname>GtkScrollbar</structname>/<structname>GtkScale</structname> 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 <structname>GtkRange</structname>, you 
  have our respect). Also, <literal>GtkTroughType</literal> is gone.
</para>
<para>
 Here are some notable changes:
 <itemizedlist>
   <listitem>
     <para>
       <literal>stepper_size</literal> style property is the height for 
       vertical ranges, width for horizontal; the other dimension matches 
       the trough size.
     </para>
   </listitem>
   <listitem>
     <para>
       Added the ability to do NeXT-style steppers (and several other styles
       that don't make any sense).
     </para>
   </listitem>
   <listitem>
     <para>
       Added <literal>min_slider_length</literal>, 
       <literal>fixed_slider_length</literal> properties to
       <structname>GtkScrollbar</structname>.
     </para>
   </listitem>
   <listitem>
     <para>
       Cleaned some private (or at least useless) functions out of
       <filename>gtkscale.h</filename>, e.g. 
       <function>gtk_scale_value_width</function>.
     </para>
   </listitem>
   <listitem>
     <para>
       Moved bindings from subclasses to <structname>GtkScale</structname>, 
       even arrow keys, since blind users don't know scale orientation.
     </para>
   </listitem>
   <listitem>
     <para>
       Changed <literal>move_slider</literal> action signal to use new 
       <structname>GtkScrollType</structname>, remove  
       <structname>GtkTroughType</structname> argument.
     </para>
   </listitem>
   <listitem>
     <para>
       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 <literal>adjustment->value</literal> inside a 
       <literal>value_changed</literal> handler.
     </para>
   </listitem>
   <listitem>
     <para>
       Added getters for <structname>GtkScale</structname> setters.
     </para>
   </listitem>
   <listitem>
     <para>
       Middle-click begins a slider drag.
     </para>
   </listitem>
 </itemizedlist>
</para>
</listitem>

<listitem>
<para>
The GtkContainer::focus signal/virtual function and
  <function>gtk_container_focus()</function> call were replaced by 
  GtkWidget::focus and <function>gtk_widget_child_focus()</function>. 
  The semantics are the same, so you should be able to just 
  replace <literal>container_class-&gt;focus = mywidget_focus</literal> with 
  <literal>widget_class-&gt;focus = mywidget_focus</literal> and replace 
  <function>gtk_container_focus()</function> calls with 
  <function>gtk_widget_child_focus()</function> calls.
</para>
<para>
  The purpose of this change was to allow non-containers to have 
  focusable elements.
</para>
</listitem>
 
<listitem>
<para>
<function>gtk_rc_set_image_loader()</function> and