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

   1 Incompatible Changes from GTK+-1.2 to GTK+-1.4:
   2
   3 * The gdk_time* functions have been removed. This functionality
   4   has been unused since the main loop was moved into GLib
   5   prior to 1.2.
   6
   7 * The signature for GtkPrintFunc (used for gtk_item_factory_dump_items)
   8   has been changed to take a 'const gchar *' instead of 'gchar *', to
   9   match what we do for glib, and other similar cases.
  10
  11 * The detail arguments in the GtkStyleClass structure are now 'const gchar *'.
  12
  13 * gtk_paned_set_gutter_size() has been removed, since the small handle tab
  14   has been changed to include the entire area previously occupied by
  15   the gutter.
  16
  17 * GDK no longer selects OwnerGrabButtonMask for button presses. This means
  18   that the automatic grab that occurs when the user presses a button
  19   will have owner_events = FALSE, so all events are redirected to the
  20   grab window, even events that would normally go to  other windows of the
  21   window's owner.
  22
  23 * GtkColorSelectionDialog has now been moved into it's own set of files,
  24   gtkcolorseldialog.c and gtkcolorseldialog.h.
  25
  26 * gtk_widget_shape_combine_mask() now keeps a reference count on the
  27   mask pixmap that is passed in.
  28
  29 * Type system changes:
  30   - GTK_TYPE_OBJECT is not a fundamental type anymore. Type checks of the
  31     style (GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)
  32     will not work anymore. As a replacement, (GTK_TYPE_IS_OBJECT (some_type))
  33     can be used now.
  34   - The following types vanished: GTK_TYPE_ARGS, GTK_TYPE_CALLBACK,
  35     GTK_TYPE_C_CALLBACK, GTK_TYPE_FOREIGN. The corresponding GtkArg
  36     fields and field access macros are also gone.
  37   - The following type aliases vanished: GTK_TYPE_FLAT_FIRST,
  38     GTK_TYPE_FLAT_LAST, GTK_TYPE_STRUCTURED_FIRST, GTK_TYPE_STRUCTURED_LAST.
  39   - The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQNO() vanished, use of
  40     GTK_FUNDAMENTAL_TYPE() is discouraged. Instead, the corresponding GType
  41     API should be used: G_TYPE_FUNDAMENTAL(), G_TYPE_DERIVE_ID(),
  42     G_TYPE_BRANCH_SEQNO(). Note that the GLib type system doesn't build new
  43     type ids based on a global incremental sequential number anymore, but
  44     numbers new type ids sequentially per fundamental type branch.
  45   - The following type functions vanished/were replaced:
  46     Old Function                 Replacement
  47     gtk_type_query()             - being investigated -
  48     gtk_type_set_varargs_type()  -
  49     gtk_type_get_varargs_type()  -
  50     gtk_type_check_object_cast() g_type_check_instance_cast()
  51     gtk_type_check_class_cast()  g_type_check_class_cast()
  52     gtk_type_describe_tree()     -
  53     gtk_type_describe_heritage() -
  54     gtk_type_free()              -
  55     gtk_type_children_types()    g_type_children()
  56     gtk_type_set_chunk_alloc()   GTypeInfo.n_preallocs
  57     gtk_type_register_enum()     g_enum_register_static()
  58     gtk_type_register_flags()    g_flags_register_static()
  59     gtk_type_parent_class()      g_type_parent() / g_type_class_peek_parent()
  60     Use of g_type_class_ref() / g_type_class_unref() and g_type_class_peek()
  61     is recommended over usage of gtk_type_class().
  62     Use of g_type_register_static() / g_type_register_dynamic() is recommended
  63     over usage of gtk_type_unique().
  64
  65 * Object system changes:
  66   GtkObject derives from GObject, so is not the basic object type anymore.
  67   This imposes the following source incompatible changes:
  68   - GtkObject has no klass field anymore, an object's class can be retrived
  69     with the object's coresponding GTK_<OBJECT>_GET_CLASS (object) macro.
  70   - GtkObjectClass has no type field anymore, a class's type can be retrived
  71     with the GTK_CLASS_TYPE (class) macro.
  72   - GtkObjectClass does not introduce the finalize() and shutdown() methods
  73     anymore. While shutdown() is intended for GTK+ internal use only, finalize()
  74     is required by a variety of object implementations. GObjectClass.finalize
  75     should be overriden here, e.g.:
  76     static void gtk_label_finalize (GObject *gobject)
  77     {
  78       GtkLabel *label = GTK_LABEL (gobject);
  79
  80       G_OBJECT_CLASS (parent_class)->finalize (object);
  81     }
  82     static void gtk_label_class_init (GtkLabelClass *class)
  83     {
  84       GObjectClass *gobject_class = G_OBJECT_CLASS (class);
  85
  86       gobject_class->finalize = gtk_label_finalize;
  87     }
  88
  89   - the GtkObject::destroy signal can now be emitted multiple times on an object.
  90     ::destroy implementations should check that make sure that they take this
  91     into account, by checking to make sure that resources are there before
  92     freeing them. For example:
  93     if (object->foo_data)
  94       {
  95         g_free (object->foo_data);
  96         object->foo_data = NULL;
  97       }
  98
  99     Also, ::destroy implementations have to release object references that
 100     the object holds. Code in finalize implementations such as:
 101     if (object->adjustment)
 102       {
 103         gtk_object_unref (object->adjustment);
 104         object->adjustment = NULL;
 105       }
 106     have to be moved into the ::destroy implementations. The reason for doing
 107     this is that all object reference cycles should be broken at destruction
 108     time.
 109
 110 - Inserting and deleting text in GtkEntry though functions such
 111   as gtk_entry_insert_text() now leave the cursor at its original
 112   position in the text instead of moving it to the location of
 113   the insertion/deletion.
 114
 115 - The ->label field of GtkFrame widgets has been removed. (As part of
 116   a change to allow the arbitrary widgets in the title position.) The
 117   text can now be retrieved with the new function gtk_frame_get_text().
 118
 119 - The 'font' and 'font_set' declarations in RC files are now ignored. There
 120   is a new 'font_name' field that holds the string form of a Pango font
 121
 122 - A number of types in GDK have become subclasses of GObject. For the
 123   most part, this should not break anyone's code. However, it's now
 124   possible/encouraged to use g_object_ref()/g_object_unref() and other
 125   GObject features with these GDK types. The converted types are:
 126   GdkWindow, GdkDrawable, GdkPixmap, GdkImage, GdkGC, GdkDragContext,
 127   GdkColormap
 128
 129 - All drawables including pixmaps used to have a type tag, the
 130   GdkWindowType enumeration, which included GDK_WINDOW_PIXMAP.
 131   GdkWindowType is now a property of GdkWindow _only_, and there is
 132   no GDK_WINDOW_PIXMAP. You can use the GDK_IS_PIXMAP() macro to see
 133   if you have a pixmap, if you need to know that.
 134
 135 - GtkStyle and GtkRcStyle are now subclasses of GObject as well.  This
 136   requires fairly extensive changes to theme engines quite badly, but
 137   shouldn't affect most other code.
 138
 139 - xthickness/ythickness have moved from GtkStyleClass to GtkStyle
 140   (from class to instance). This gives themes a bit more flexibility
 141   and is generally more of the Right Thing. You can trivially fix
 142   your code with s/style->klass->xthickness/style->xthickness/g and
 143   same for ythickness.
 144
 145 - If you were using private GDK types, they have been rearranged
 146   significantly. You shouldn't use private types. ;-)
 147
 148 - The visual for a widget, and also the default visual is now derived
 149   from the colormap for the widget and the default colormap.
 150   gtk_widget_set_visual(), gtk_widget_set_defualt_visual(), gtk_widget_push_visual()
 151   and gtk_widget_pop_visual() now do nothing. Since the visual always
 152   had to match that of the colormap, it is safe to simply delete
 153   all references to these functions.
 154
 155 - A number of functions in GDK have been renamed for consistency and
 156   clarity. #defines to provide backwards compatibility have been
 157   included, but can be disabled by defineing GDK_DISABLE_COMPAT_H.
 158
 159   #define gdk_draw_pixmap                gdk_draw_drawable
 160   #define gdk_draw_bitmap                gdk_draw_drawable
 161
 162   #define gdk_window_get_size            gdk_drawable_get_size
 163   #define gdk_window_get_type            gdk_window_get_window_type
 164   #define gdk_window_get_colormap        gdk_drawable_get_colormap
 165   #define gdk_window_set_colormap        gdk_drawable_set_colormap
 166   #define gdk_window_get_visual          gdk_drawable_get_visual
 167
 168   #define gdk_window_ref                 gdk_drawable_ref
 169   #define gdk_window_unref               gdk_drawable_unref
 170   #define gdk_bitmap_ref                 gdk_drawable_ref
 171   #define gdk_bitmap_unref               gdk_drawable_unref
 172   #define gdk_pixmap_ref                 gdk_drawable_ref
 173   #define gdk_pixmap_unref               gdk_drawable_unref
 174
 175   #define gdk_gc_destroy                 gdk_gc_unref
 176   #define gdk_image_destroy              gdk_image_unref
 177   #define gdk_cursor_destroy             gdk_cursor_unref
 178
 179   (Note that g_object_ref() and g_object_unref() may be used for all of
 180   the above.)
 181
 182   #define gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height) \
 183      gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)
 184
 185   #define gdk_rgb_get_cmap               gdk_rgb_get_colormap
 186
 187 - gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the
 188   pixmap when the GdkPixmap is finalized. This change corresponds
 189   to the behavior of gdk_window_foreign_new(), and fixes a lot
 190   of problems with code where the pixmap wasn't supposed to be
 191   freed. If XFreePixmap() is needed, it can be done using the
 192   destroy-notification facilities of g_object_set_data().
 193
 194 -  GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
 195
 196   - Only 3 or 4 functions are really needed for 95% of progress
 197     interfaces; GtkProgress[Bar] had about 25 functions, and
 198     didn't even include these 3 or 4.
 199   - In activity mode, the API involves setting the adjustment
 200     to any random value, just to have the side effect of
 201     calling the progress bar update function - the adjustment
 202     is totally ignored in activity mode
 203   - You set the activity step as a pixel value, which means to
 204     set the activity step you basically need to connect to
 205     size_allocate
 206   - There are ctree_set_expander_style()-functions, to randomly
 207     change look-and-feel for no good reason
 208   - The split between GtkProgress and GtkProgressBar makes no sense
 209     to me whatsoever.
 210
 211  This was a big wart on GTK and made people waste lots of time,
 212  both learning and using the interface.
 213
 214  So, we have added what we feel is the correct API, and marked all the
 215  rest deprecated. However, the changes are 100% backward-compatible and
 216  should break no existing code.
 217
 218  The following 5 functions are the new programming interface and you
 219  should consider changing your code to use them:
 220
 221   void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
 222   void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
 223                                                     const gchar    *text);
 224   void       gtk_progress_bar_set_fraction         (GtkProgressBar *pbar,
 225                                                     gfloat          fraction);
 226
 227   void       gtk_progress_bar_set_pulse_step       (GtkProgressBar *pbar,
 228                                                     gfloat          fraction);
 229   void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
 230                                                     GtkProgressBarOrientation orientation);
 231
 232