forked from AuroraMiddleware/gtk
824e8e2d9d
2002-01-06 Havoc Pennington <hp@pobox.com> * gtk/gtk-docs.sgml: remove gtk- prefix from TreeView and a few other entities, more consistent anyway (I thought this would make links to "GtkTreeView" etc. go to the ref page, not the struct, but it wasn't the problem, the issue is the way gtkdoc-mkdb decides what's an object, see CheckIsObject() routine) * gtk/changes-1.2.sgml: sgml fixes to get rid of warnings * gtk/changes-2.0.sgml: ditto * gtk/question_index.sgml: add some questions
461 lines
16 KiB
Plaintext
461 lines
16 KiB
Plaintext
<refentry id="gtk-changes-1-2" revision="1 Jan 2002">
|
|
<refmeta>
|
|
<refentrytitle>Changes from 1.0 to 1.2</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>Changes from 1.0 to 1.2</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>Changes from 1.0 to 1.2</refname>
|
|
<refpurpose>
|
|
Incompatible changes made between version 1.0 and version 1.2
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
|
|
<refsect1>
|
|
<title>Incompatible changes from 1.0 to 1.2</title>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
<para>
|
|
<structname>GtkAcceleratorTable</structname> has been replaced with
|
|
<structname>GtkAccelGroup</structname>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<structname>GtkMenuFactory</structname> has been replaced with
|
|
<structname>GtkItemFactory</structname>, although
|
|
a version of <structname>GtkMenuFactory</structname> is currently still
|
|
provided to ease the migration phase.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The <structname>GtkTypeInfo</structname> structures used in the
|
|
<function>gtk_*_type_init()</function> functions have
|
|
changed a bit, the old format:
|
|
<programlisting>
|
|
GtkTypeInfo bin_info =
|
|
{
|
|
"GtkBin",
|
|
sizeof (GtkBin),
|
|
sizeof (GtkBinClass),
|
|
(GtkClassInitFunc) gtk_bin_class_init,
|
|
(GtkObjectInitFunc) gtk_bin_init,
|
|
(GtkArgSetFunc) NULL,
|
|
(GtkArgGetFunc) NULL,
|
|
};
|
|
</programlisting>
|
|
|
|
needs to be converted to:
|
|
|
|
<programlisting>
|
|
static const GtkTypeInfo bin_info =
|
|
{
|
|
"GtkBin",
|
|
sizeof (GtkBin),
|
|
sizeof (GtkBinClass),
|
|
(GtkClassInitFunc) gtk_bin_class_init,
|
|
(GtkObjectInitFunc) gtk_bin_init,
|
|
/* reserved_1 */ NULL,
|
|
/* reserved_2 */ NULL,
|
|
(GtkClassInitFunc) NULL,
|
|
};
|
|
</programlisting>
|
|
|
|
the <function>GtkArgSetFunc</function> and <function>GtkArgGetFunc</function>
|
|
functions are not supported from the type system anymore, and you should make
|
|
sure that your code only fills in these fields with <literal>NULL</literal>
|
|
and doesn't use the deprecated function typedefs
|
|
<literal>(GtkArgSetFunc)</literal> and <literal>(GtkArgGetFunc)</literal>
|
|
anymore.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
A number of GTK+ functions were renamed. For compatibility,
|
|
<filename>gtkcompat.h</filename> #define's the old 1.0.x function names in
|
|
terms of the new names. To assure your GTK+ program doesn't rely on outdated
|
|
function variants, compile your program with
|
|
<option>-DGTK_DISABLE_COMPAT_H</option> to disable
|
|
the compatibility aliases.
|
|
|
|
Here is the list of the old names and replacements:
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row><entry>Old</entry><entry>Replacement</entry></row>
|
|
</thead>
|
|
<tbody>
|
|
<row><entry><function>gtk_accel_label_accelerator_width</function></entry><entry><function>gtk_accel_label_get_accel_width</function></entry></row>
|
|
<row><entry><function>gtk_check_menu_item_set_state</function></entry><entry><function>gtk_check_menu_item_set_active</function></entry></row>
|
|
<row><entry><function>gtk_container_border_width</function></entry><entry><function>gtk_container_set_border_width</function></entry></row>
|
|
<row><entry><function>gtk_label_set</function></entry><entry><function>gtk_label_set_text</function></entry></row>
|
|
<row><entry><function>gtk_notebook_current_page</function></entry><entry><function>gtk_notebook_get_current_page</function></entry></row>
|
|
<row><entry><function>gtk_packer_configure</function></entry><entry><function>gtk_packer_set_child_packing</function></entry></row>
|
|
<row><entry><function>gtk_paned_gutter_size</function></entry><entry><function>gtk_paned_set_gutter_size</function></entry></row>
|
|
<row><entry><function>gtk_paned_handle_size</function></entry><entry><function>gtk_paned_set_handle_size</function></entry></row>
|
|
<row><entry><function>gtk_scale_value_width</function></entry><entry><function>gtk_scale_get_value_width</function></entry></row>
|
|
<row><entry><function>gtk_style_apply_default_pixmap</function></entry><entry><function>gtk_style_apply_default_background</function></entry></row>
|
|
<row><entry><function>gtk_toggle_button_set_state</function></entry><entry><function>gtk_toggle_button_set_active</function></entry></row>
|
|
<row><entry><function>gtk_window_position</function></entry><entry><function>gtk_window_set_position</function></entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
Note that <function>gtk_style_apply_default_background()</function> has an
|
|
additional argument, <literal>set_bg</literal>. This parameter should be
|
|
<literal>FALSE</literal> if the background is being set for a
|
|
<literal>NO_WINDOW</literal> widget, otherwise <literal>TRUE</literal>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
During the development phase of the 1.1.x line of GTK+ certain functions
|
|
were deprecated and later removed. Functions affected are:
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row><entry>Removed</entry><entry>Replacement</entry></row>
|
|
</thead>
|
|
<tbody>
|
|
<row><entry><function>gtk_clist_set_border</function></entry><entry><function>gtk_clist_set_shadow_type</function></entry></row>
|
|
<row><entry><function>gtk_container_block_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
|
|
<row><entry><function>gtk_container_unblock_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
|
|
<row><entry><function>gtk_container_need_resize</function></entry><entry><function>gtk_container_check_resize</function></entry></row>
|
|
<row><entry><function>gtk_ctree_show_stub</function></entry><entry><function>gtk_ctree_set_show_stub</function></entry></row>
|
|
<row><entry><function>gtk_ctree_set_reorderable</function></entry><entry><function>gtk_clist_set_reorderable</function></entry></row>
|
|
<row><entry><function>gtk_ctree_set_use_drag_icons</function></entry><entry><function>gtk_clist_set_use_drag_icons</function></entry></row>
|
|
<row><entry><function>gtk_entry_adjust_scroll</function></entry><entry><function>-</function></entry></row>
|
|
<row><entry><function>gtk_object_class_add_user_signal</function></entry><entry><function>gtk_object_class_user_signal_new</function></entry></row>
|
|
<row><entry><function>gtk_preview_put_row</function></entry><entry><function>gtk_preview_put</function></entry></row>
|
|
<row><entry><function>gtk_progress_bar_construct</function></entry><entry><function>gtk_progress_set_adjustment</function></entry></row>
|
|
<row><entry><function>gtk_scrolled_window_construct</function></entry><entry><function>gtk_scrolled_window_set_{h|v}adjustment</function></entry></row>
|
|
<row><entry><function>gtk_spin_button_construct</function></entry><entry><function>gtk_spin_button_configure</function></entry></row>
|
|
<row><entry><function>gtk_widget_thaw_accelerators</function></entry><entry><function>gtk_widget_unlock_accelerators</function></entry></row>
|
|
<row><entry><function>gtk_widget_freeze_accelerators</function></entry><entry><function>gtk_widget_lock_accelerators</function></entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
Note that <function>gtk_entry_adjust_scroll()</function> is no longer needed
|
|
as <structname>GtkEntry</structname> should automatically keep the scroll
|
|
adjusted properly.
|
|
</para>
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
<para>
|
|
Additionally, all <function>gtk_*_interp()</function> functions were removed.
|
|
<function>gtk_*_full()</function> versions were provided as of GTK+ 1.0 and
|
|
should be used instead.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<structname>GtkButton</structname> has been changed to derive from
|
|
<structname>GtkBin</structname>.
|
|
To access a button's child, use <literal>GTK_BIN (button)->child</literal>,
|
|
instead of the old <literal>GTK_BUTTON (button)->child</literal>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The selection API has been slightly modified:
|
|
|
|
<function>gtk_selection_add_handler()</function> and
|
|
<function>gtk_selection_add_handler_full()</function>
|
|
have been removed. To supply the selection, one now registers
|
|
the targets one is interested in with:
|
|
|
|
<programlisting>
|
|
void gtk_selection_add_target (GtkWidget *widget,
|
|
GdkAtom selection,
|
|
GdkAtom target,
|
|
guint info);
|
|
</programlisting>
|
|
|
|
or:
|
|
|
|
<programlisting>
|
|
void gtk_selection_add_targets (GtkWidget *widget,
|
|
GdkAtom selection,
|
|
GtkTargetEntry *targets,
|
|
guint ntargets);
|
|
</programlisting>
|
|
|
|
When a request for a selection is received, the new "selection_get"
|
|
signal will be called:
|
|
|
|
<programlisting>
|
|
void "selection_get" (GtkWidget *widget,
|
|
GtkSelectionData *selection_data,
|
|
guint info,
|
|
guint time);
|
|
</programlisting>
|
|
|
|
A "time" parameter has also been added to the "selection_received"
|
|
signal.
|
|
|
|
<programlisting>
|
|
void "selection_received" (GtkWidget *widget,
|
|
GtkSelectionData *selection_data,
|
|
guint time);
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The old drag and drop API has been completely removed and replaced.
|
|
See the reference documentation for details on the new API.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Support for Themes has been added. In general, this does
|
|
not affect application code, however, a few new rules should
|
|
be observed:
|
|
|
|
<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, &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>
|
|
|