Pileus Git - ~andy/gtk/blob - docs/Changes-1.2.txt

   1 Incompatible Changes from GTK+-1.0 to GTK+-1.2:
   2
   3 * GtkAcceleratorTable has been replaced with GtkAccelGroup
   4
   5 * GtkMenuFactory has been replaced with GtkItemFactory, although
   6   a version of GtkMenuFactory is currently still provided to ease
   7   the migration phase.
   8
   9 * The GtkTypeInfo structures used in the gtk_*_type_init() functions have
  10   changed a bit, the old format:
  11       GtkTypeInfo bin_info =
  12       {
  13         "GtkBin",
  14         sizeof (GtkBin),
  15         sizeof (GtkBinClass),
  16         (GtkClassInitFunc) gtk_bin_class_init,
  17         (GtkObjectInitFunc) gtk_bin_init,
  18         (GtkArgSetFunc) NULL,
  19         (GtkArgGetFunc) NULL,
  20       };
  21
  22   needs to be converted to:
  23
  24       static const GtkTypeInfo bin_info =
  25       {
  26         "GtkBin",
  27         sizeof (GtkBin),
  28         sizeof (GtkBinClass),
  29         (GtkClassInitFunc) gtk_bin_class_init,
  30         (GtkObjectInitFunc) gtk_bin_init,
  31         /* reserved_1 */ NULL,
  32         /* reserved_2 */ NULL,
  33         (GtkClassInitFunc) NULL,
  34       };
  35
  36   the GtkArgSetFunc and GtkArgGetFunc functions are not supported from the
  37   type system anymore, and you should make sure that your code only fills
  38   in these fields with NULL and doesn't use the deprecated function typedefs
  39   (GtkArgSetFunc) and (GtkArgGetFunc) anymore.
  40
  41 * A number of Gtk functions were renamed. For compatibility, gtkcompat.h
  42   #define's the old 1.0.x function names in terms of the new names.
  43   To assure your Gtk program doesn't rely on outdated function
  44   variants, compile your program with -DGTK_DISABLE_COMPAT_H to disable
  45   the compatibility aliases.
  46
  47   Here is the list of the old names and replacements:
  48
  49   Old:                                Replacement:
  50
  51   gtk_accel_label_accelerator_width   gtk_accel_label_get_accel_width
  52   gtk_check_menu_item_set_state       gtk_check_menu_item_set_active
  53   gtk_container_border_width          gtk_container_set_border_width
  54   gtk_label_set                       gtk_label_set_text
  55   gtk_notebook_current_page           gtk_notebook_get_current_page
  56   gtk_packer_configure                gtk_packer_set_child_packing
  57   gtk_paned_gutter_size               gtk_paned_set_gutter_size
  58   gtk_paned_handle_size               gtk_paned_set_handle_size
  59   gtk_scale_value_width               gtk_scale_get_value_width
  60   gtk_style_apply_default_pixmap      gtk_style_apply_default_background (1)
  61   gtk_toggle_button_set_state         gtk_toggle_button_set_active
  62   gtk_window_position                 gtk_window_set_position
  63
  64   (1) gtk_style_apply_default_background() has an additional
  65       argument, gboolean set_bg. This parameter should be FALSE if
  66       the background is being set for a NO_WINDOW widget, otherwise
  67       true.
  68
  69 * During the development phase of the 1.1.x line of Gtk certain functions
  70   were deprecated and later removed. Functions affected are:
  71
  72   Removed:                          Replacement:
  73   gtk_clist_set_border              gtk_clist_set_shadow_type
  74   gtk_container_block_resize        gtk_container_set_resize_mode
  75   gtk_container_unblock_resize      gtk_container_set_resize_mode
  76   gtk_container_need_resize         gtk_container_check_resize
  77   gtk_ctree_show_stub               gtk_ctree_set_show_stub
  78   gtk_ctree_set_reorderable         gtk_clist_set_reorderable
  79   gtk_ctree_set_use_drag_icons      gtk_clist_set_use_drag_icons
  80   gtk_entry_adjust_scroll           (1)
  81   gtk_object_class_add_user_signal  gtk_object_class_user_signal_new
  82   gtk_preview_put_row               gtk_preview_put
  83   gtk_progress_bar_construct        gtk_progress_set_adjustment
  84   gtk_scrolled_window_construct     gtk_scrolled_window_set_{h|v}adjustment
  85   gtk_spin_button_construct         gtk_spin_button_configure
  86   gtk_widget_thaw_accelerators      gtk_widget_unlock_accelerators
  87   gtk_widget_freeze_accelerators    gtk_widget_lock_accelerators
  88
  89 (1) This function is no longer needed as GtkEntry should automatically
  90     keep the scroll adjusted properly.
  91
  92 * Additionally, all gtk_*_interp functions were removed.
  93   gtk_*_full versions were provided as of GTK+-1.0 and should
  94   be used instead.
  95
  96 * GtkButton has been changed to derive from GtkBin.
  97   To access a button's child, use GTK_BIN (button)->child, instead
  98   of the old GTK_BUTTON (button)->child.
  99
 100 * The selection API has been slightly modified:
 101
 102  gtk_selection_add_handler() and gtk_selection_add_handler_full()
 103  have been removed. To supply the selection, one now register
 104  the targets one is interested in with:
 105
 106   void gtk_selection_add_target (GtkWidget           *widget,
 107                                  GdkAtom              selection,
 108                                  GdkAtom              target,
 109                                  guint                info);
 110
 111  or:
 112
 113   void gtk_selection_add_targets (GtkWidget           *widget,
 114                                   GdkAtom              selection,
 115                                   GtkTargetEntry      *targets,
 116                                   guint                ntargets);
 117
 118  When a request for a selection is received, the new "selection_get"
 119  signal will be called:
 120
 121    void  "selection_get"           (GtkWidget          *widget,
 122                                     GtkSelectionData   *selection_data,
 123                                     guint               info,
 124                                     guint               time);
 125
 126  A "time" parameter has also been added to the "selection_received"
 127  signal.
 128
 129   void  "selection_received"       (GtkWidget          *widget,
 130                                     GtkSelectionData   *selection_data,
 131                                     guint               time);
 132
 133 * The old drag and drop API has been completely removed and replaced.
 134   See the reference documentation for details on the new API.
 135
 136 * Support for Themes has been added. In general, this does
 137   not affect application code, however, a few new rules should
 138   be observed:
 139
 140    - To set a shape for a window, you must use
 141      gtk_widget_shape_combine_mask() instead of
 142      gdk_window_shape_combine_mask(), or the shape will be
 143      reset when switching themes.
 144
 145    - It is no longer permissable to draw directly on an arbitrary
 146      widget, or to set an arbitrary widget's background pixmap.
 147      If you need to do that, use a GtkDrawingArea or (for a
 148      toplevel) the new GtkDrawWindow widget.
 149
 150 * The ScrolledWindow widget no longer creates a Viewport
 151   automatically. Instead, it has been generalized to accept
 152   any "self-scrolling" widget.
 153
 154   The self-scrolling widgets in the Gtk+ core are GtkViewport,
 155   GtkCList, GtkCTree, GtkText, and GtkLayout. All of these widgets can
 156   be added to a scrolled window as normal children with
 157   gtk_container_add() and scrollbars will be set up automatically.
 158
 159   To add scrollbars to a non self-scrolling widget, (such as a GtkList),
 160   first add it to a viewport, then add the viewport to a scrolled window.
 161   The scrolled window code provides a convenience function to do this:
 162
 163   void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
 164                                               GtkWidget         *child);
 165
 166   This does exactly what it says - it creates a Viewport, adds the child
 167   widget to it, then adds the Viewport to the scrolled window.
 168
 169   The scrollbars have been removed from the GtkCList and GtkCTree,
 170   because they are now scrolled by simply adding them to a Scrolled
 171   Window. The scrollbar policy is set on the scrolled window with
 172   gtk_scrolled_window_set_policy() and not on the child widgets
 173   (e.g. GtkCList's gtk_clist_set_policy() was removed).
 174
 175 * The "main loop" of GTK+ has been moved to GLib. This should not
 176   affect existing programs, since compatibility functions have
 177   been provided. However, you may want to consider migrating
 178   your code to use the GLib main loop directly.
 179
 180 * the GTK_BASIC flag was removed, and with it the corresponding
 181   macro and function GTK_WIDGET_BASIC() and gtk_widget_basic().
 182
 183 * All freeze/thaw methods are now recursive - that is, if you
 184   freeze a widget n times, you must also thaw it n times.
 185
 186   Therefore, if you have code like:
 187
 188   gboolean frozen;
 189   frozen = GTK_CLIST_FROZEN (clist);
 190   gtk_clist_freeze (clist);
 191   [...]
 192   if (!frozen)
 193     gtk_clist_thaw (clist);
 194
 195   it will not work anymore. It must be, simply:
 196
 197   gtk_clist_freeze (clist);
 198   [...]
 199   gtk_clist_thaw (clist);
 200
 201 * The thread safety in GTK+ 1.2 is slightly different than
 202   that which appeared in early versions in the 1.1
 203   development track. The main difference is that it relies on
 204   the thread primitives in GLib, and on the thread-safe
 205   GLib main loop.
 206
 207   This means:
 208
 209    - You must call g_thread_init() before executing any
 210      other GTK+ or GDK functions in a threaded GTK+ program.
 211
 212    - Idles, timeouts, and input functions are executed outside
 213      of the main GTK+ lock. So, if you need to call GTK+
 214      inside of such a callback, you must surround the callback
 215      with a gdk_threads_enter()/gdk_threads_leave() pair.
 216
 217      [ However, signals are still executed within the main
 218        GTK+ lock ]
 219
 220      In particular, this means, if you are writing widgets
 221      that might be used in threaded programs, you _must_
 222      surround timeouts and idle functions in this matter.
 223
 224      As always, you must also surround any calls to GTK+
 225      not made within a signal handler with a
 226      gdk_threads_enter()/gdk_threads_leave() pair.
 227
 228    - There is no longer a special --with-threads configure
 229      option for GTK+. To use threads in a GTK+ program, you
 230      must:
 231
 232       a) If you want to use the native thread implementation,
 233          make sure GLib found this in configuration, otherwise,
 234          call you must provide a thread implementation to
 235          g_thread_init().
 236
 237       b) Link with the libraries returned by:
 238
 239            gtk-config --libs gthread
 240
 241          and use the cflags from:
 242
 243             gtk-config --cflags gthread
 244
 245      You can get these CFLAGS and LIBS by passing gthread
 246      as the fourth parameter to the AM_PATH_GTK automake
 247      macro.
 248
 249 * Prior to GTK+-1.2, there were two conflicting interpretations
 250   of widget->requistion. It was either taken to be
 251   the size that the widget requested, or that size
 252   modified by calls to gtk_widget_set_usize(). In GTK+-1.2,
 253   it is always interpreted the first way.
 254
 255   Container widgets are affected in two ways by this:
 256
 257    1) Container widgets should not pass widget->requisition
 258       as the second parameter to gtk_widget_size_request().
 259       Instead they should call it like:
 260
 261       GtkRequisition child_requisition;
 262       gtk_widget_size_request (widget, &child_requisition);
 263
 264    2) Container widgets should not access child->requisition
 265       directly. Either they should use the values returned
 266       by gtk_widget_size_request(), or they should call
 267       the new function:
 268
 269     void gtk_widget_get_child_requisition (GtkWidget      *widget,
 270                                            GtkRequisition *requisition);
 271
 272       which returns the requisition of the given widget, modified
 273       by calls to gtk_widget_set_usize().
 274