changes-1.2.sgml

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

  <itemizedlist>
  <listitem>
  <para>To set a shape for a window, you must use 
     <function>gtk_widget_shape_combine_mask()</function> instead of 
     <function>gdk_window_shape_combine_mask()</function>, or the shape will be
     reset when switching themes.
  </para>
  </listitem>

  <listitem>
  <para>It is no longer permissable to draw directly on an arbitrary
     widget, or to set an arbitrary widget's background pixmap.
     If you need to do that, use a <structname>GtkDrawingArea</structname> or 
     (for a toplevel) a <structname>GtkWindow</structname> where 
     <function>gtk_widget_set_app_paintable()</function>
     has been called.
  </para>
  </listitem>
  </itemizedlist>
</para>
</listitem>

<listitem>
<para>
The <structname>GtkScrolledWindow</structname> widget no longer creates a 
  <structname>GtkViewport</structname> automatically. Instead, it has been 
  generalized to accept any "self-scrolling" widget.
</para>

<para>
  The self-scrolling widgets in the GTK+ core are 
  <structname>GtkViewport</structname>,
  <structname>GtkCList</structname>, <structname>GtkCTree</structname>, 
  <structname>GtkText</structname>, and <structname>GtkLayout</structname>. 
  All of these widgets can be added to a scrolled window as normal children with
  <function>gtk_container_add()</function> and scrollbars will be set up 
  automatically.
</para>

<para>
  To add scrollbars to a non self-scrolling widget, (such as a 
  <structname>GtkList</structname>),
  first add it to a viewport, then add the viewport to a scrolled window.
  The scrolled window code provides a convenience function to do this:

<programlisting>
  void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
					      GtkWidget         *child);
</programlisting>

  This does exactly what it says - it creates a viewport, adds the child
  widget to it, then adds the viewport to the scrolled window.
</para>

<para>
  The scrollbars have been removed from the <structname>GtkCList</structname>
  and <structname>GtkCTree</structname>, because they are now scrolled by simply
  adding them to a scrolled window. The scrollbar policy is set on the scrolled
  window with <function>gtk_scrolled_window_set_policy()</function> and not on 
  the child widgets (e.g. <structname>GtkCList</structname>'s 
  <function>gtk_clist_set_policy()</function> was removed).
</para>
</listitem>  

<listitem>
<para>
The "main loop" of GTK+ has been moved to GLib. This should not
  affect existing programs, since compatibility functions have
  been provided. However, you may want to consider migrating
  your code to use the GLib main loop directly.
</para>
</listitem>

<listitem>
<para>
the <literal>GTK_BASIC</literal> flag was removed, and with it the corresponding
  macro and function <function>GTK_WIDGET_BASIC()</function> and 
  <function>gtk_widget_basic()</function>.
</para>
</listitem>
  
<listitem>
<para>
All freeze/thaw methods are now recursive - that is, if you
  freeze a widget n times, you must also thaw it n times.

  Therefore, if you have code like:

<informalexample><programlisting>
  gboolean frozen;
  frozen = GTK_CLIST_FROZEN (clist);
  gtk_clist_freeze (clist);
  [...]
  if (!frozen)
    gtk_clist_thaw (clist);
</programlisting></informalexample>

  it will not work anymore. It must be, simply:

<informalexample><programlisting>
  gtk_clist_freeze (clist);
  [...]
  gtk_clist_thaw (clist);
</programlisting></informalexample>
</para>
</listitem>

<listitem>
<para>
The thread safety in GTK+ 1.2 is slightly different than
  that which appeared in early versions in the 1.1
  development track. The main difference is that it relies on 
  the thread primitives in GLib, and on the thread-safe 
  GLib main loop.
</para>

<para>
  This means:

<itemizedlist>
   <listitem>
     <para>You must call <function>g_thread_init()</function> before 
       executing any other GTK+ or GDK functions in a threaded GTK+ program.
     </para>
   </listitem>

   <listitem>
     <para>Idles, timeouts, and input functions are executed outside 
       of the main GTK+ lock. So, if you need to call GTK+ 
       inside of such a callback, you must surround the callback
       with a <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function> 
       pair.
     </para>

     <para>However, signals are still executed within the main
       GTK+ lock.
     </para>

     <para>In particular, this means, if you are writing widgets
       that might be used in threaded programs, you <emphasis>must</emphasis>
       surround timeouts and idle functions in this matter.
     </para>
     
     <para>As always, you must also surround any calls to GTK+
       not made within a signal handler with a 
       <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function> 
       pair.
     </para>
   </listitem>

   <listitem>
     <para>There is no longer a special <option>--with-threads</option> 
       <command>configure</command> option for GTK+. To use threads in a GTK+ 
       program, you must:

       <orderedlist>
         <listitem>
           <para>If you want to use the native thread implementation,
              make sure GLib found this in configuration, otherwise,
              call you must provide a thread implementation to
	      <function>g_thread_init()</function>.
           </para>
         </listitem>
         <listitem>
           <para>Link with the libraries returned by
             <command>gtk-config --libs gthread</command>
             and use the cflags from
             <command>gtk-config --cflags gthread</command>.
             You can get these <envar>CFLAGS</envar> and <envar>LIBS</envar> by 
             passing <literal>gthread</literal> as the fourth parameter to the 
             <literal>AM_PATH_GTK</literal> <application>automake</application>
             macro.
           </para>
         </listitem>
       </orderedlist>
     </para>
   </listitem>
  </itemizedlist>
</para>
</listitem>

<listitem>
<para>
Prior to GTK+ 1.2, there were two conflicting interpretations
  of <literal>widget->requisition</literal>. It was either taken to be
  the size that the widget requested, or that size modified by calls to 
  <function>gtk_widget_set_usize()</function>. In GTK+ 1.2,
  it is always interpreted the first way.
</para>

<para>
  Container widgets are affected in two ways by this:

  <orderedlist>
    <listitem>
      <para>Container widgets should not pass 
        <literal>widget->requisition</literal> as the second parameter to 
        <function>gtk_widget_size_request()</function>.
        Instead they should call it like:
        <programlisting>
          GtkRequisition child_requisition;
          gtk_widget_size_request (widget, &amp;child_requisition);
        </programlisting>
      </para>
    </listitem>
    <listitem>
      <para>Container widgets should not access 
        <literal>child->requisition</literal> directly. Either they should use 
        the values returned by <function>gtk_widget_size_request()</function>, 
        or they should call the new function:
        <programlisting>
    void gtk_widget_get_child_requisition (GtkWidget      *widget,
					   GtkRequisition *requisition);
        </programlisting>
        which returns the requisition of the given widget, modified
        by calls to <function>gtk_widget_set_usize()</function>.
      </para>
    </listitem>
  </orderedlist>
</para>
</listitem>


</itemizedlist>

</refsect1>

</refentry>