From d93b99a273ed580eadacd08930db8e08703992c2 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 3 Jun 2010 01:09:53 -0400 Subject: [PATCH] Remove old migration docs This information will still be available in the 2.22 docs. For 3.0, we'll do sortof a clean start. --- docs/reference/gtk/Makefile.am | 16 - docs/reference/gtk/building.sgml | 502 ++++---- docs/reference/gtk/changes-1.2.sgml | 464 -------- docs/reference/gtk/changes-2.0.sgml | 1180 ------------------- docs/reference/gtk/compiling.sgml | 37 +- docs/reference/gtk/gtk-docs.sgml | 90 +- docs/reference/gtk/migrating-2to3.xml | 53 +- docs/reference/gtk/migrating-checklist.sgml | 135 ++- docs/reference/gtk/question_index.sgml | 11 +- 9 files changed, 397 insertions(+), 2091 deletions(-) delete mode 100644 docs/reference/gtk/changes-1.2.sgml delete mode 100644 docs/reference/gtk/changes-2.0.sgml diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 3e3df0d2b6..bab6e4c5e6 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -120,28 +120,12 @@ content_files = \ version.xml \ running.sgml \ building.sgml \ - changes-1.2.sgml \ - changes-2.0.sgml \ compiling.sgml \ directfb.sgml \ drawing-model.xml \ glossary.xml \ migrating-2to3.xml \ migrating-checklist.sgml \ - migrating-ClientSideWindows.sgml \ - migrating-GtkAboutDialog.sgml \ - migrating-GtkAction.sgml \ - migrating-GtkAssistant.sgml \ - migrating-GtkBuilder.sgml \ - migrating-GtkColorButton.sgml \ - migrating-GtkComboBox.sgml \ - migrating-GtkEntry-icons.sgml \ - migrating-GtkFileChooser.sgml \ - migrating-GtkIconView.sgml \ - migrating-GtkLabel-links.sgml \ - migrating-GtkLinkButton.sgml \ - migrating-GtkRecentChooser.sgml \ - migrating-GtkTooltip.sgml \ objects_grouped.sgml \ osx.sgml \ question_index.sgml \ diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml index 3d3da46a67..87a182492f 100644 --- a/docs/reference/gtk/building.sgml +++ b/docs/reference/gtk/building.sgml @@ -49,12 +49,12 @@ How to compile GTK+ itself of the tools are already included in the source packages. But it's useful to know a bit about how packages that use these tools work. A source package is distributed as a - tar.gz or tar.bz2 file + tar.gz or tar.bz2 file which you unpack into a directory full of the source files as follows: - tar xvfz gtk+-2.0.0.tar.gz - tar xvfj gtk+-2.0.0.tar.bz2 + tar xvfz gtk+-3.0.0.tar.gz + tar xvfj gtk+-3.0.0.tar.bz2 In the toplevel of the directory that is created, there will be @@ -103,7 +103,7 @@ How to compile GTK+ itself a search path that pkg-config (see below) uses when looking for for file describing how to compile programs using different libraries. If you were installing GTK+ - and it's dependencies into /opt/gtk, you + and it's dependencies into /opt/gtk, you might want to set these variables as: @@ -137,30 +137,26 @@ How to compile GTK+ itself - - pkg-config - is a tool for tracking the compilation flags needed for - libraries that are used by the GTK+ libraries. (For each - library, a small .pc text file is installed - in a standard location that contains the compilation flags - needed for that library along with version number information.) - The version of pkg-config needed to build - GTK+ is mirrored in the dependencies directory - on the GTK+ FTP - site. - + + pkg-config + is a tool for tracking the compilation flags needed for + libraries that are used by the GTK+ libraries. (For each + library, a small .pc text file is installed + in a standard location that contains the compilation flags + needed for that library along with version number information.) + - - The GTK+ makefiles will mostly work with different versions - of make, however, there tends to be - a few incompatibilities, so the GTK+ team recommends - installing GNU - make if you don't already have it on your system - and using it. (It may be called gmake - rather than make.) - + + The GTK+ makefiles will mostly work with different versions + of make, however, there tends to be + a few incompatibilities, so the GTK+ team recommends + installing GNU + make if you don't already have it on your system + and using it. (It may be called gmake + rather than make.) + @@ -170,106 +166,105 @@ How to compile GTK+ itself - - The GLib library provides core non-graphical functionality - such as high level data types, Unicode manipulation, and - an object and type system to C programs. It is available - from the GTK+ - FTP site. - + + The GLib library provides core non-graphical functionality + such as high level data types, Unicode manipulation, and + an object and type system to C programs. It is available + from the GTK+ + FTP site. + - - Pango is a library - for internationalized text handling. It is available from - the GTK+ FTP - site.. - + + Pango is a library + for internationalized text handling. It is available from + the GTK+ FTP + site.. + - - ATK is the Accessibility Toolkit. It provides a set of generic - interfaces allowing accessibility technologies such as - screen readers to interact with a graphical user interface. - It is available from the GTK+ FTP site. - + + ATK is the Accessibility Toolkit. It provides a set of generic + interfaces allowing accessibility technologies such as + screen readers to interact with a graphical user interface. + It is available from the GTK+ FTP site. + - - The GNU - libiconv library is needed to build GLib if your - system doesn't have the iconv() - function for doing conversion between character - encodings. Most modern systems should have - iconv(). - + + The GNU + libiconv library is needed to build GLib if your + system doesn't have the iconv() + function for doing conversion between character + encodings. Most modern systems should have + iconv(). + - - The libintl library from the GNU gettext - package is needed if your system doesn't have the - gettext() functionality for handling - message translation databases. - + + The libintl library from the GNU gettext + package is needed if your system doesn't have the + gettext() functionality for handling + message translation databases. + - - The JPEG, - PNG, and - TIFF image - loading libraries are needed to compile GTK+. You probably - already have these libraries installed, but if not, the - versions you need are available in the + + The JPEG, + PNG, and + TIFF image + loading libraries are needed to compile GTK+. You probably + already have these libraries installed, but if not, the + versions you need are available in the dependencies directory on the the - GTK+ - FTP site.. (Before installing these libraries - from source, you should check if your operating system - vendor has prebuilt packages of these libraries that you - don't have installed.) - + GTK+ + FTP site.. (Before installing these libraries + from source, you should check if your operating system + vendor has prebuilt packages of these libraries that you + don't have installed.) + - - The libraries from the X window system are needed to build - Pango and GTK+. You should already have these installed on - your system, but it's possible that you'll need to install - the development environment for these libraries that your - operating system vendor provides. - + + The libraries from the X window system are needed to build + Pango and GTK+. You should already have these installed on + your system, but it's possible that you'll need to install + the development environment for these libraries that your + operating system vendor provides. + - - The fontconfig - library provides Pango with a standard way of locating - fonts and matching them against font names. - + + The fontconfig + library provides Pango with a standard way of locating + fonts and matching them against font names. + - - Cairo + + Cairo is a graphics library that supports vector graphics and image compositing. Both Pango and GTK+ use cairo for much of their drawing. - - gobject-introspection + + gobject-introspection is a framework for making introspection data available to language bindings. - The shared-mime-info - package is not a hard dependency of GTK+, but it contains definitions - for mime types that are used by GIO and, indirectly, by GTK+. - gdk-pixbuf will use GIO for mime type detection if possible. For this - to work, shared-mime-info needs to be installed and - XDG_DATA_DIRS set accordingly at configure time. + The shared-mime-info + package is not a hard dependency of GTK+, but it contains definitions + for mime types that are used by GIO and, indirectly, by GTK+. + gdk-pixbuf will use GIO for mime type detection if possible. For this + to work, shared-mime-info needs to be installed and + XDG_DATA_DIRS set accordingly at configure time. Otherwise, gdk-pixbuf falls back to its built-in mime type detection. @@ -281,7 +276,7 @@ How to compile GTK+ itself First make sure that you have the necessary external dependencies installed: pkg-config, GNU make, the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary, - libiconv and libintl. To get detailed information about building + libiconv and libintl. To get detailed information about building these packages, see the documentation provided with the individual packages. On a Linux system, it's quite likely you'll have all of these @@ -294,7 +289,7 @@ How to compile GTK+ itself make install mentioned above. If you're lucky, this will all go smoothly, and you'll be ready to start compiling your own GTK+ - applications. You can test your GTK+ installation + applications. You can test your GTK+ installation by running the gtk-demo program that GTK+ installs. @@ -315,123 +310,127 @@ How to compile GTK+ itself Extra Configuration Options - In addition to the normal options, the - configure script for the GTK+ library - supports a number of additional arguments. (Command line - arguments for the other GTK+ libraries are described in - the documentation distributed with the those libraries.) + In addition to the normal options, the + configure script for the GTK+ library + supports a number of additional arguments. (Command line + arguments for the other GTK+ libraries are described in + the documentation distributed with the those libraries.) - - configure + + configure - - --disable-modules - --enable-modules - - - --with-included-loaders==LOADER1,LOADER2,... - - - --with-included-immodules=MODULE1,MODULE2,... - - - --enable-debug=[no|minimum|yes] - - --disable-visibility - --enable-visibility - + --disable-modules + --enable-modules + - --disable-shm - --enable-shm - + --with-included-loaders==LOADER1,LOADER2,... + - --disable-xim - --enable-xim - + --with-included-immodules=MODULE1,MODULE2,... + - --disable-xim-inst - --enable-xim-inst - + --enable-debug=[no|minimum|yes] + - --disable-xkb - --enable-xkb - + --disable-visibility + --enable-visibility + - --disable-xinerama - --enable-xinerama - - - --disable-gtk-doc - --enable-gtk-doc - - - --disable-cups - --enable-cups - + --disable-shm + --enable-shm + + + --disable-xim + --enable-xim + + + --disable-xim-inst + --enable-xim-inst + + + --disable-xkb + --enable-xkb + + + --disable-xinerama + --enable-xinerama + + + --disable-gtk-doc + --enable-gtk-doc + + + --disable-cups + --enable-cups + + + --disable-papi + --enable-papi + --with-xinput=[no|yes] - - --with-gdktarget=[x11|win32|quartz|directfb] - - --disable-introspection + --with-gdktarget=[x11|win32|quartz|directfb] - + + --disable-introspection + + - <systemitem>--disable-modules</systemitem> and - <systemitem>--enable-modules</systemitem> + <systemitem>--disable-modules</systemitem> and + <systemitem>--enable-modules</systemitem> - - Normally GTK+ will try to build the GdkPixbuf image file - format loaders as little shared libraries that are loaded on - demand. The --disable-modules - argument indicates that they should all be built statically - into the GTK+ library instead. This is useful for - people who need to produce statically-linked binaries. If - neither --disable-modules nor - --enable-modules is specified, then - the configure script will try to - auto-detect whether shared modules work on your system. - + + Normally GTK+ will try to build the GdkPixbuf image file + format loaders as little shared libraries that are loaded on + demand. The --disable-modules + argument indicates that they should all be built statically + into the GTK+ library instead. This is useful for + people who need to produce statically-linked binaries. If + neither --disable-modules nor + --enable-modules is specified, then + the configure script will try to + auto-detect whether shared modules work on your system. + - <systemitem>--with-included-loaders</systemitem> + <systemitem>--with-included-loaders</systemitem> - + This option allows you to specify which image loaders you want to include; for example, you might include only the PNG loader to create a smaller GdkPixbuf binary. - + - <systemitem>--with-included-immodules</systemitem> + <systemitem>--with-included-immodules</systemitem> - + This option allows you to specify which input method modules you - want to include. - + want to include. + <systemitem>--enable-debug</systemitem> - + - Turns on various amounts of debugging support. Setting this to 'no' - disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and + Turns on various amounts of debugging support. Setting this to 'no' + disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and all cast checks between different object types. Setting it to 'minimum' - disables only cast checks. Setting it to 'yes' enables - runtime debugging. + disables only cast checks. Setting it to 'yes' enables + runtime debugging. The default is 'minimum'. - Note that 'no' is fast, but dangerous as it tends to destabilize - even mostly bug-free software by changing the effect of many bugs - from simple warnings into fatal crashes. Thus - should not + Note that 'no' is fast, but dangerous as it tends to destabilize + even mostly bug-free software by changing the effect of many bugs + from simple warnings into fatal crashes. Thus + should not be used for stable releases of GTK+. @@ -443,7 +442,7 @@ How to compile GTK+ itself The option --disable-visibility turns off the use of ELF visibility attributes for linking optimizations. This makes sense while changing GTK+ itself, - since the way in which GTK+ uses visibility attributes + since the way in which GTK+ uses visibility attributes forces a full rebuild of all source files for any header modification. @@ -453,33 +452,33 @@ How to compile GTK+ itself <systemitem>--enable-explicit-deps</systemitem> and <systemitem>--disable-explicit-deps</systemitem> - If --enable-explicit-deps is - specified then GTK+ will write the full set of libraries - that GTK+ depends upon into its .pc files to be used when - programs depending on GTK+ are linked. Otherwise, GTK+ - only will include the GTK+ libraries themselves, and - will depend on system library dependency facilities to - bring in the other libraries. - By default GTK+ will disable explicit dependencies unless - it detects that they are needed on the system. (If you - specify --enable-static to force - building of static libraries, then explicit dependencies - will be written since library dependencies don't work - for static libraries.) Specifying - --enable-explicit-deps or - --enable-static can cause - compatibility - problems when libraries that GTK+ depends upon change - their versions, and should be avoided if possible. + If --enable-explicit-deps is + specified then GTK+ will write the full set of libraries + that GTK+ depends upon into its .pc files to be used when + programs depending on GTK+ are linked. Otherwise, GTK+ + only will include the GTK+ libraries themselves, and + will depend on system library dependency facilities to + bring in the other libraries. + By default GTK+ will disable explicit dependencies unless + it detects that they are needed on the system. (If you + specify --enable-static to force + building of static libraries, then explicit dependencies + will be written since library dependencies don't work + for static libraries.) Specifying + --enable-explicit-deps or + --enable-static can cause + compatibility + problems when libraries that GTK+ depends upon change + their versions, and should be avoided if possible. <systemitem>--disable-shm</systemitem> and <systemitem>--enable-shm</systemitem> - + - These options can be used to control whether GTK+ will use shared + These options can be used to control whether GTK+ will use shared memory to communicate with the X server when possible. The default is 'yes'. @@ -488,44 +487,44 @@ How to compile GTK+ itself <systemitem>--disable-xim</systemitem> and <systemitem>--enable-xim</systemitem> - + - These options can be used to control whether GTK+ will + These options can be used to control whether GTK+ will be compiled with support for XIM. (The X Input Method - extension, used for Japanese input.) The default is yes. + extension, used for Japanese input.) The default is yes. <systemitem>--disable-xim-inst</systemitem> and <systemitem>--enable-xim-inst</systemitem> - + - These options determine whether GTK+ will use the - XIM instantiate callback. + These options determine whether GTK+ will use the + XIM instantiate callback. The default is 'yes', unless the host system is Solaris, - where XRegisterIMInstantiateCallback() - seems to cause a segfault. + where XRegisterIMInstantiateCallback() + seems to cause a segfault. <systemitem>--disable-xkb</systemitem> and <systemitem>--enable-xkb</systemitem> - + - By default the configure script will try - to auto-detect whether the XKB extension is supported by + By default the configure script will try + to auto-detect whether the XKB extension is supported by the X libraries GTK+ is linked with. These options can be used to explicitly control whether - GTK+ will support the XKB extension. + GTK+ will support the XKB extension. <systemitem>--disable-xinerama</systemitem> and <systemitem>--enable-xinerama</systemitem> - + By default the configure script will try to link against the Xinerama libraries if they are found. @@ -535,29 +534,29 @@ How to compile GTK+ itself - <systemitem>--disable-gtk-doc</systemitem> and - <systemitem>--enable-gtk-doc</systemitem> + <systemitem>--disable-gtk-doc</systemitem> and + <systemitem>--enable-gtk-doc</systemitem> - - The gtk-doc package is - used to generate the reference documentation included - with GTK+. By default support for gtk-doc - is disabled because it requires various extra dependencies - to be installed. If you have - gtk-doc installed and - are modifying GTK+, you may want to enable - gtk-doc support by passing - in --enable-gtk-doc. If not - enabled, pre-generated HTML files distributed with GTK+ - will be installed. - + + The gtk-doc package is + used to generate the reference documentation included + with GTK+. By default support for gtk-doc + is disabled because it requires various extra dependencies + to be installed. If you have + gtk-doc installed and + are modifying GTK+, you may want to enable + gtk-doc support by passing + in --enable-gtk-doc. If not + enabled, pre-generated HTML files distributed with GTK+ + will be installed. + - <systemitem>--disable-cups</systemitem> and - <systemitem>--enable-cups</systemitem> + <systemitem>--disable-cups</systemitem> and + <systemitem>--enable-cups</systemitem> - + By default the configure script will try to build the cups print backend if the cups libraries are found. These options can be used to explicitly control whether @@ -565,30 +564,41 @@ How to compile GTK+ itself + + <systemitem>--disable-papi</systemitem> and + <systemitem>--enable-papi</systemitem> + + + By default the configure script will try + to build the papi print backend if the papi libraries are found. + These options can be used to explicitly control whether + the papi print backend should be built. + + + <systemitem>--with-xinput</systemitem> - Controls whether GTK+ is built with support for the XInput - extension. The XInput extension provides an interface - to extended input devices such as graphics tablets. - When this support is compiled in, specially written - GTK+ programs can get access to subpixel positions, - multiple simultaneous input devices, and extra "axes" - provided by the device such as pressure and tilt - information. This is only known to work well on XFree86 - systems, though other systems do have this extension. + Controls whether GTK+ is built with support for the XInput + or XInput2 extension. These extensions provide an extended + interface to input devices such as graphics tablets. + When this support is compiled in, specially written + GTK+ programs can get access to subpixel positions, + multiple simultaneous input devices, and extra "axes" + provided by the device such as pressure and tilt + information. - <systemitem>--with-gdktarget</systemitem> + <systemitem>--with-gdktarget</systemitem> - - Toggles between the supported backends for GDK. + + Toggles between the supported backends for GDK. The default is x11, unless the platform is Windows, in which - case the default is win32. Other supported backends are + case the default is win32. Other supported backends are the quartz backend for OS X, and the DirectFB backend for the Linux framebuffer. - + <systemitem>--disable-introspection</systemitem> diff --git a/docs/reference/gtk/changes-1.2.sgml b/docs/reference/gtk/changes-1.2.sgml deleted file mode 100644 index 1cd9470495..0000000000 --- a/docs/reference/gtk/changes-1.2.sgml +++ /dev/null @@ -1,464 +0,0 @@ - - - - -Changes from 1.0 to 1.2 -3 -Changes from 1.0 to 1.2 - - - -Changes from 1.0 to 1.2 - -Incompatible changes made between version 1.0 and version 1.2 - - - - - -Incompatible changes from 1.0 to 1.2 - - - - - -GtkAcceleratorTable has been replaced with -GtkAccelGroup. - - - - - -GtkMenuFactory has been replaced with -GtkItemFactory, although -a version of GtkMenuFactory is currently still -provided to ease the migration phase. - - - - - -The GtkTypeInfo structures used in the -gtk_*_type_init() functions have -changed a bit, the old format: - - GtkTypeInfo bin_info = - { - "GtkBin", - sizeof (GtkBin), - sizeof (GtkBinClass), - (GtkClassInitFunc) gtk_bin_class_init, - (GtkObjectInitFunc) gtk_bin_init, - (GtkArgSetFunc) NULL, - (GtkArgGetFunc) NULL, - }; - - - needs to be converted to: - - - 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, - }; - - - the GtkArgSetFunc and GtkArgGetFunc - functions are not supported from the type system anymore, and you should make - sure that your code only fills in these fields with NULL - and doesn't use the deprecated function typedefs - (GtkArgSetFunc) and (GtkArgGetFunc) - anymore. - - - - - -A number of GTK+ functions were renamed. For compatibility, - gtkcompat.h #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 - to disable - the compatibility aliases. - - Here is the list of the old names and replacements: - - - - -OldReplacement - - -gtk_accel_label_accelerator_widthgtk_accel_label_get_accel_width -gtk_check_menu_item_set_stategtk_check_menu_item_set_active -gtk_container_border_widthgtk_container_set_border_width -gtk_label_setgtk_label_set_text -gtk_notebook_current_pagegtk_notebook_get_current_page -gtk_packer_configuregtk_packer_set_child_packing -gtk_paned_gutter_sizegtk_paned_set_gutter_size -gtk_paned_handle_sizegtk_paned_set_handle_size -gtk_scale_value_widthgtk_scale_get_value_width -gtk_style_apply_default_pixmapgtk_style_apply_default_background -gtk_toggle_button_set_stategtk_toggle_button_set_active -gtk_window_positiongtk_window_set_position - - - -Note that gtk_style_apply_default_background() has an - additional argument, set_bg. This parameter should be - FALSE if the background is being set for a - NO_WINDOW widget, otherwise TRUE. - - - - - -During the development phase of the 1.1.x line of GTK+ certain functions - were deprecated and later removed. Functions affected are: - - - - -RemovedReplacement - - -gtk_clist_set_bordergtk_clist_set_shadow_type -gtk_container_block_resizegtk_container_set_resize_mode -gtk_container_unblock_resizegtk_container_set_resize_mode -gtk_container_need_resizegtk_container_check_resize -gtk_ctree_show_stubgtk_ctree_set_show_stub -gtk_ctree_set_reorderablegtk_clist_set_reorderable -gtk_ctree_set_use_drag_iconsgtk_clist_set_use_drag_icons -gtk_entry_adjust_scroll- -gtk_object_class_add_user_signalgtk_object_class_user_signal_new -gtk_preview_put_rowgtk_preview_put -gtk_progress_bar_constructgtk_progress_set_adjustment -gtk_scrolled_window_constructgtk_scrolled_window_set_{h|v}adjustment -gtk_spin_button_constructgtk_spin_button_configure -gtk_widget_thaw_acceleratorsgtk_widget_unlock_accelerators -gtk_widget_freeze_acceleratorsgtk_widget_lock_accelerators - - - - -Note that gtk_entry_adjust_scroll() is no longer needed - as GtkEntry should automatically keep the scroll - adjusted properly. - - - - - - -Additionally, all gtk_*_interp() functions were removed. - gtk_*_full() versions were provided as of GTK+ 1.0 and - should be used instead. - - - - - -GtkButton has been changed to derive from -GtkBin. - To access a button's child, use GTK_BIN (button)->child, - instead of the old GTK_BUTTON (button)->child. - - - - - -The selection API has been slightly modified: - - gtk_selection_add_handler() and - gtk_selection_add_handler_full() - have been removed. To supply the selection, one now registers - the targets one is interested in with: - - - void gtk_selection_add_target (GtkWidget *widget, - GdkAtom selection, - GdkAtom target, - guint info); - - - or: - - - void gtk_selection_add_targets (GtkWidget *widget, - GdkAtom selection, - GtkTargetEntry *targets, - guint ntargets); - - - When a request for a selection is received, the new "selection_get" - signal will be called: - - - void "selection_get" (GtkWidget *widget, - GtkSelectionData *selection_data, - guint info, - guint time); - - - A "time" parameter has also been added to the "selection_received" - signal. - - - void "selection_received" (GtkWidget *widget, - GtkSelectionData *selection_data, - guint time); - - - - - - -The old drag and drop API has been completely removed and replaced. - See the reference documentation for details on the new API. - - - - - -Support for Themes has been added. In general, this does - not affect application code, however, a few new rules should - be observed: - - - - To set a shape for a window, you must use - gtk_widget_shape_combine_mask() instead of - gdk_window_shape_combine_mask(), or the shape will be - reset when switching themes. - - - - - 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 GtkDrawingArea or - (for a toplevel) a GtkWindow where - gtk_widget_set_app_paintable() - has been called. - - - - - - - - -The GtkScrolledWindow widget no longer creates a - GtkViewport automatically. Instead, it has been - generalized to accept any "self-scrolling" widget. - - - - The self-scrolling widgets in the GTK+ core are - GtkViewport, - GtkCList, GtkCTree, - GtkText, and GtkLayout. - All of these widgets can be added to a scrolled window as normal children with - gtk_container_add() and scrollbars will be set up - automatically. - - - - To add scrollbars to a non self-scrolling widget, (such as a - GtkList), - 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: - - - void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin, - GtkWidget *child); - - - This does exactly what it says - it creates a viewport, adds the child - widget to it, then adds the viewport to the scrolled window. - - - - The scrollbars have been removed from the GtkCList - and GtkCTree, because they are now scrolled by simply - adding them to a scrolled window. The scrollbar policy is set on the scrolled - window with gtk_scrolled_window_set_policy() and not on - the child widgets (e.g. GtkCList's - gtk_clist_set_policy() was removed). - - - - - -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. - - - - - -the GTK_BASIC flag was removed, and with it the corresponding - macro and function GTK_WIDGET_BASIC() and - gtk_widget_basic(). - - - - - -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: - - - gboolean frozen; - frozen = GTK_CLIST_FROZEN (clist); - gtk_clist_freeze (clist); - [...] - if (!frozen) - gtk_clist_thaw (clist); - - - it will not work anymore. It must be, simply: - - - gtk_clist_freeze (clist); - [...] - gtk_clist_thaw (clist); - - - - - - -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. - - - - This means: - - - - You must call g_thread_init() before - executing any other GTK+ or GDK functions in a threaded GTK+ program. - - - - - 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 gdk_threads_enter()/gdk_threads_leave() - pair. - - - However, signals are still executed within the main - GTK+ lock. - - - In particular, this means, if you are writing widgets - that might be used in threaded programs, you must - surround timeouts and idle functions in this matter. - - - As always, you must also surround any calls to GTK+ - not made within a signal handler with a - gdk_threads_enter()/gdk_threads_leave() - pair. - - - - - There is no longer a special - configure option for GTK+. To use threads in a GTK+ - program, you must: - - - - 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 - g_thread_init(). - - - - Link with the libraries returned by - gtk-config --libs gthread - and use the cflags from - gtk-config --cflags gthread. - You can get these CFLAGS and LIBS by - passing gthread as the fourth parameter to the - AM_PATH_GTK automake - macro. - - - - - - - - - - - -Prior to GTK+ 1.2, there were two conflicting interpretations - of widget->requisition. It was either taken to be - the size that the widget requested, or that size modified by calls to - gtk_widget_set_usize(). In GTK+ 1.2, - it is always interpreted the first way. - - - - Container widgets are affected in two ways by this: - - - - Container widgets should not pass - widget->requisition as the second parameter to - gtk_widget_size_request(). - Instead they should call it like: - - GtkRequisition child_requisition; - gtk_widget_size_request (widget, &child_requisition); - - - - - Container widgets should not access - child->requisition directly. Either they should use - the values returned by gtk_widget_size_request(), - or they should call the new function: - - void gtk_widget_get_child_requisition (GtkWidget *widget, - GtkRequisition *requisition); - - which returns the requisition of the given widget, modified - by calls to gtk_widget_set_usize(). - - - - - - - - - - - - - diff --git a/docs/reference/gtk/changes-2.0.sgml b/docs/reference/gtk/changes-2.0.sgml deleted file mode 100644 index 6fa82c3935..0000000000 --- a/docs/reference/gtk/changes-2.0.sgml +++ /dev/null @@ -1,1180 +0,0 @@ - - - - -Changes from 1.2 to 2.0 -3 -Changes from 1.2 to 2.0 - - - -Changes from 1.2 to 2.0 - -Incompatible changes made between version 1.2 and version 2.0 - - - - - -Incompatible changes from 1.2 to 2.0 - - -The GNOME 2.0 -porting guide on http://developer.gnome.org -has some more detailed discussion of porting from 1.2 to 2.0. -See the sections on GLib and GTK+. - - - -GTK+ changed fairly substantially from version 1.2 to 2.0, much more -so than from 1.0 to 1.2. Subsequent updates (possibilities are 2.0 to -2.2, 2.2 to 2.4, then to 3.0) will almost certainly be much, much -smaller. Nonetheless, most programs written for 1.2 compile against -2.0 with few changes. The bulk of changes listed below are to obscure -features or very specialized features, and compatibility interfaces -exist whenever possible. - - - - - - -gtk_container_get_toplevels() was removed and replaced - with gtk_window_list_toplevels(), which has different - memory management on the return value - (gtk_window_list_toplevels() copies the - GList and also references each widget in the list, - so you have to g_list_free() the list after first - unref'ing each list member). - - - - - -The gdk_time* functions have been removed. This - functionality has been unused since the main loop was moved into GLib - prior to 1.2. - - - - - -The signature for GtkPrintFunc (used for - gtk_item_factory_dump_items()) - has been changed to take a const gchar * instead of - gchar *, to match what we do for GLib, and other similar cases. - - - - - -The detail arguments in the GtkStyleClass structure -are now const gchar *. - - - - - -gtk_paned_set_gutter_size() has been removed, since the - small handle tab has been changed to include the entire area previously - occupied by the gutter. - - - - - -gtk_paned_set_handle_size() has been removed, in favor of - a style property, since this is an option that only makes sense for themes - to adjust. - - - - - -GDK no longer selects OwnerGrabButtonMask for button presses. This means - that the automatic grab that occurs when the user presses a button - will have owner_events = FALSE, so all events are - redirected to the grab window, even events that would normally go to - other windows of the window's owner. - - - - - -GtkColorSelectionDialog has now been moved into it's - own set of files, gtkcolorseldialog.c and - gtkcolorseldialog.h. - - - - - -gtk_widget_shape_combine_mask() now keeps a reference - count on the mask pixmap that is passed in. - - - - - -The GtkPatternSpec has been moved to GLib as - GPatternSpec, the pattern - arguments to gtk_item_factory_dump_items() and - gtk_item_factory_dump_rc() - have thusly been changed to take a GPatternSpec - instead of a GtkPatternSpec. - - - - - -Type system changes: - - - - GTK_TYPE_OBJECT is not a fundamental type anymore. Type checks of the - style (GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT) - will not work anymore. As a replacement, (GTK_TYPE_IS_OBJECT (some_type)) - can be used now. - - - - -The following types vanished: GTK_TYPE_ARGS, GTK_TYPE_CALLBACK, - GTK_TYPE_C_CALLBACK, GTK_TYPE_FOREIGN. The corresponding GtkArg - fields and field access macros are also gone. - - - - -The following type aliases vanished: GTK_TYPE_FLAT_FIRST, - GTK_TYPE_FLAT_LAST, GTK_TYPE_STRUCTURED_FIRST, - GTK_TYPE_STRUCTURED_LAST. - - - - -The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQNO() vanished, use of - GTK_FUNDAMENTAL_TYPE() is discouraged. Instead, the corresponding GType - API should be used: G_TYPE_FUNDAMENTAL(), G_TYPE_DERIVE_ID(), - G_TYPE_BRANCH_SEQNO(). Note that the GLib type system doesn't build new - type ids based on a global incremental sequential number anymore, but - numbers new type ids sequentially per fundamental type branch. - - - - -The following type functions vanished/were replaced: - - - -Old FunctionReplacement - - -gtk_type_query()being investigated -gtk_type_set_varargs_type()- -gtk_type_get_varargs_type()- -gtk_type_check_object_cast()g_type_check_instance_cast() -gtk_type_check_class_cast()g_type_check_class_cast() -gtk_type_describe_tree()- -gtk_type_describe_heritage()- -gtk_type_free()- -gtk_type_children_types()g_type_children() -gtk_type_set_chunk_alloc()GTypeInfo.n_preallocs -gtk_type_register_enum()g_enum_register_static() -gtk_type_register_flags()g_flags_register_static() -gtk_type_parent_class()g_type_parent()/g_type_class_peek_parent() - - - - Use of g_type_class_ref()/g_type_class_unref() and g_type_class_peek() - is recommended over usage of gtk_type_class(). - Use of g_type_register_static()/g_type_register_dynamic() is recommended - over usage of gtk_type_unique(). - - - - - - - - -Object system changes: - GtkObject derives from GObject, so is not the basic object type anymore. - This imposes the following source incompatible changes: - - - - -GtkObject has no klass field anymore, an object's class can be retrieved - with the object's coresponding GTK_<OBJECT>_GET_CLASS (object) - macro. - - - - -GtkObjectClass has no type field anymore, a class's type can be retrived - with the GTK_CLASS_TYPE (class) macro. - - - - -GtkObjectClass does not introduce the finalize() and shutdown() methods - anymore. While shutdown() is intended for GTK+ internal use only, finalize() - is required by a variety of object implementations. GObjectClass.finalize - should be overriden here, e.g.: - - static void gtk_label_finalize (GObject *gobject) - { - GtkLabel *label = GTK_LABEL (gobject); - - G_OBJECT_CLASS (parent_class)->finalize (object); - } - static void gtk_label_class_init (GtkLabelClass *class) - { - GObjectClass *gobject_class = G_OBJECT_CLASS (class); - - gobject_class->finalize = gtk_label_finalize; - } - - - - - - - - - - -The GtkObject::destroy signal can now be emitted multiple times on an object. - ::destroy implementations should check that make sure that they take this - into account, by checking to make sure that resources are there before - freeing them. For example: - - if (object->foo_data) - { - g_free (object->foo_data); - object->foo_data = NULL; - } - - - Also, ::destroy implementations have to release object references that - the object holds. Code in finalize implementations such as: - - if (object->adjustment) - { - gtk_object_unref (object->adjustment); - object->adjustment = NULL; - } - - have to be moved into the ::destroy implementations. The reason for doing - this is that all object reference cycles should be broken at destruction - time. - - Because the ::destroy signal can be emitted multiple times, it no longer - makes sense to check if a widget has been destroyed using the - GTK_OBJECT_DESTROYED() macro, and this macro has been - removed. If catching destruction is still needed, it can be done with a - signal connection to ::destroy. - - - - - -Signal system changes: - The GTK+ 2.0 signal system merely proxies the GSignal - system now. For future usage, direct use of the - GSignal API is recommended, - this avoids significant performance hits where GtkArg - structures have to be converted into GValues. For - language bindings, GSignal+GClosure - provide a much more flexible and convenient mechanism to hook into signal - emissions or install class default handlers, so the old - GtkSignal API for language bindings is not - supported anymore. - - - Functions that got removed in the GTK+ signal API: - gtk_signal_n_emissions(), - gtk_signal_n_emissions_by_name(), - gtk_signal_set_funcs(), - gtk_signal_handler_pending_by_id(), - gtk_signal_add_emission_hook(), - gtk_signal_add_emission_hook_full(), - gtk_signal_remove_emission_hook(), - gtk_signal_query(). - Also, the GtkCallbackMarshal argument to - gtk_signal_connect_full() is - not supported anymore. - For many of the removed functions, similar variants are available - in the g_signal_* namespace. - The GSignal system performs emissions in a - slightly different manner than the old GtkSignal - code. Signal handlers that are connected to signal "foo" - on object "bar" while "foo" is being emitted, will not be called anymore - during the emission they were connected within. - - - - - -Inserting and deleting text in GtkEntry though - functions such as gtk_entry_insert_text() now leave - the cursor at its original position in the text instead of moving it to - the location of the insertion/deletion. - - - - - -The label field of GtkFrame - widgets has been removed (as part of a change to allow arbitrary widgets - in the title position). The text can now be retrieved with the new function - gtk_frame_get_text(). - - - - - -The 'font' and 'font_set' declarations in RC files are now ignored. There - is a new 'font_name' field that holds the string form of a Pango font. - - - - - -A number of types in GDK have become subclasses of - GObject. For the most part, this should not break - anyone's code. However, it's now possible/encouraged to use - g_object_ref()/g_object_unref() and - other GObject features with these GDK types. The - converted types are: - GdkWindow, GdkDrawable, - GdkPixmap, GdkImage, - GdkGC, GdkDragContext, - GdkColormap. - - - - - -All drawables including pixmaps used to have a type tag, the - GdkWindowType enumeration, which included - GDK_WINDOW_PIXMAP. - GdkWindowType is now a property of - GdkWindow only, and there is - no GDK_WINDOW_PIXMAP. You can use the - GDK_IS_PIXMAP() macro to see if you have a pixmap, if - you need to know that. - - - - - -GtkStyle and GtkRcStyle are - now subclasses of GObject as well. This - requires fairly extensive changes to theme engines, but - shouldn't affect most other code. - - - - - -xthickness and ythickness have moved from - GtkStyleClass to GtkStyle - (from class to instance). This gives themes a bit more flexibility - and is generally more of the Right Thing. You can trivially fix - your code with s/style->klass->xthickness/style->xthickness/g and - same for ythickness. - - - - - -Some GtkStyle draw_* methods - have been removed (cross, oval, ramp) - and others have been added (expander, layout). This will require - changes to theme engines. - - - - - -If you were using private GDK types, they have been rearranged - significantly. You shouldn't use private types. ;-) - - - - - -The visual for a widget, and also the default visual is now derived - from the colormap for the widget and the default colormap. - gtk_widget_set_visual(), - gtk_widget_set_default_visual(), - gtk_widget_push_visual() and - gtk_widget_pop_visual() 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. - - - - - - -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 GDK_DISABLE_DEPRECATED. - - - - -Old functionDefined As - - -gdk_draw_pixmapgdk_draw_drawable - gdk_draw_bitmapgdk_draw_drawable -gdk_window_get_sizegdk_drawable_get_size -gdk_window_get_typegdk_window_get_window_type -gdk_window_get_colormapgdk_drawable_get_colormap -gdk_window_set_colormapgdk_drawable_set_colormap -gdk_window_get_visualgdk_drawable_get_visual -gdk_window_refgdk_drawable_ref -gdk_window_unrefgdk_drawable_unref -gdk_bitmap_refgdk_drawable_ref -gdk_bitmap_unrefgdk_drawable_unref -gdk_pixmap_refgdk_drawable_ref -gdk_pixmap_unrefgdk_drawable_unref -gdk_gc_destroygdk_gc_unref -gdk_image_destroygdk_image_unref -gdk_cursor_destroygdk_cursor_unref -gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height)gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height) -gdk_rgb_get_cmapgdk_rgb_get_colormap - - - - (Note that g_object_ref() and - g_object_unref() may be used for all of the above ref - and unref functions.) - - gtk_widget_popup() was removed, it was only usable - for GtkWindows, and there the same effect can be - achieved by gtk_window_move() and - gtk_widget_show(). - - - - - -gdk_pixmap_foreign_new() no longer calls - XFreePixmap() on the pixmap when the - GdkPixmap is finalized. This change corresponds - to the behavior of gdk_window_foreign_new(), and fixes - a lot of problems with code where the pixmap wasn't supposed to be freed. - If XFreePixmap() is needed, it can be done using the - destroy-notification facilities of g_object_set_data(). - - - - - -GtkProgress/GtkProgressBar - had serious problems in GTK+ 1.2. - - - -Only 3 or 4 functions are really needed for 95% of progress interfaces; - GtkProgress/GtkProgressBar - had about 25 functions, and didn't even include these 3 or 4. - - - - - -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. - - - - - -You set the activity step as a pixel value, which means to - set the activity step you basically need to connect to - size_allocate. - - - - - -There are ctree_set_expander_style()-functions, to - randomly change look-and-feel for no good reason. - - - - - -The split between GtkProgress and -GtkProgressBar makes no sense to me whatsoever. - - - - - - 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: - - 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); - - - - - - -The GtkNotebookPage 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. - - - - - -Negative values of the position parameter to - gtk_notebook_reorder_child() now cause the page to be appended, not - inserted at the beginning. (This gives consistency with - gtk_box_reorder_child(), gtk_menu_reorder_child().) - - - - - -GtkMenuPositionFunc has a new parameter - push_in which controls how menus placed outside the - screen is handled. If this is set to TRUE 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. - - - 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. - - - - - -The "draw" signal and virtual method on GtkWidget - has been removed. - All drawing should now occur by invalidating a region of the widget - (call gdk_window_invalidate_rect() or - gtk_widget_queue_draw() 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. - gtk_widget_draw() 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. - - - - - -The GdkExposeEvent has a new region - field. This can be used instead of the area field if you - want a more exact representation of the area to update. - - - - - -Sending synthetic exposes using gtk_widget_event() is no - longer allowed. If you just need an expose call you should use - gdk_window_invalidate_rect() or - gdk_window_invalidate_region() instead. For the case - of container widgets that need to propagate expose events to - NO_WINDOW children you can either use - gtk_container_propagate_expose(), or chain to the - default container expose handler. - - - - - -The draw_default and draw_focus methods/signals on - GtkWidget are gone; simply draw things in your - expose handler. gtk_widget_draw_focus() and - gtk_widget_draw_default() wrapper - functions are also gone; just queue a draw on the widget, - or the part affected by the focus/default anyway. - Also, GtkWidget now has default implementations for - focus_in_event and focus_out_event. These set/unset - GTK_HAS_FOCUS, and queue a draw. So if your focus in/out - handler just does that, you can delete it. - - - - - -GtkText and GtkTree 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 - GtkTextView and GtkTreeView. - The broken widgets are not declared in the headers by default; to use - them, define the symbol GTK_ENABLE_BROKEN during - compilation. In some future release, these widgets will be removed from GTK+. - - - - - -GdkColorContext is gone; you probably weren't using - it anyway. Use GdkColormap and the - gdk_rgb_* functions instead. - - - - - -GtkMenuBar now draws the GtkContainer::border_width - space outside the frame, not inside the frame. - - - - - - -In GTK+ 1.2, if an event handler returned TRUE 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 TRUE, the current - signal emission on the current widget is immediately stopped. That is, - other callbacks connected to the signal will not be invoked. - - - - - -gtk_toolbar_new() no longer has arguments. This function - was broken because the default GtkToolbarStyle (icons, - text, both) is now a user preference, which is overridden when you call - gtk_toolbar_set_style(). 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 gtk_toolbar_set_style(). - - - - The orientation arg was removed from gtk_toolbar_new() - as well, just because it wasn't very useful and we were breaking the function - anyway so had an opportunity to lose it. Call - gtk_toolbar_set_orientation() to set toolbar orientation. - - - - - - -GtkRange/GtkScrollbar/GtkScale 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 GtkRange, you - have our respect). Also, GtkTroughType is gone. - - - Here are some notable changes: - - - - stepper_size style property is the height for - vertical ranges, width for horizontal; the other dimension matches - the trough size. - - - - - Added the ability to do NeXT-style steppers (and several other styles - that don't make any sense). - - - - - Added min_slider_length, - fixed_slider_length properties to - GtkScrollbar. - - - - - Cleaned some private (or at least useless) functions out of - gtkscale.h, e.g. - gtk_scale_value_width. - - - - - Moved bindings from subclasses to GtkScale, - even arrow keys, since blind users don't know scale orientation. - - - - - Changed move_slider action signal to use new - GtkScrollType, remove - GtkTroughType argument. - - - - - 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 adjustment->value inside a - value_changed handler. - - - - - Added getters for GtkScale setters. - - - - - Middle-click begins a slider drag. - - - - - - - - -The GtkContainer::focus signal/virtual function and - gtk_container_focus() call were replaced by - GtkWidget::focus and gtk_widget_child_focus(). - The semantics are the same, so you should be able to just - replace container_class->focus = mywidget_focus with - widget_class->focus = mywidget_focus and replace - gtk_container_focus() calls with - gtk_widget_child_focus() calls. - - - The purpose of this change was to allow non-containers to have - focusable elements. - - - - - -gtk_rc_set_image_loader() and -gtk_rc_load_image() have been removed, now - that GTK+ includes decent image loading capabilities itself. - - - - - -An extra GtkSettings argument has been added to - gtk_rc_find_pixmap_in_path(). This function is only - actually useful from a theme engine during parsing, at which point the - GtkSettings is provided. - - - - - -The child argument facility in gtkcontainer.c has been - converted to a child property facility using - GParamSpec and other facilities - for GObject. - - - - - -The set_child_arg() and get_child_arg() - virtual methods have been replaced with set_child_property()/get_child_property(), which - work similar to GObject->set_property/get_property. - - - - - - -Other removed GtkContainer functions with the replacements: - - - - -Old functionReplacement - - -gtk_container_add_child_arg_typegtk_container_class_install_child_property -gtk_container_query_child_argsgtk_container_class_list_child_properties -gtk_container_child_getvgtk_container_child_set_property -gtk_container_child_setvgtk_container_child_get_property -gtk_container_add_with_argsgtk_container_add_with_properties -gtk_container_addvgtk_container_add/gtk_container_child_set_property - - - - - - - - - -gdk_image_get() (or rather its replacement, - gdk_drawable_get_image()) now handles errors properly - by returning NULL, previously it would crash. Also, a - window being offscreen is no longer considered an error; instead, the area - contains undefined contents for the offscreen areas. In most cases, code - using gdk_image_get() should really be ported to - gdk_pixbuf_get_from_drawable(). - - - - - -gtk_widget_set_usize() has been renamed to - gtk_widget_set_size_request(), however the old name - still exists unless you define GTK_DISABLE_DEPRECATED. - - - - - -gtk_widget_set_uposition() is deprecated; use - gtk_window_move(), - gtk_fixed_put(), or gtk_layout_put() - instead. - - - - - -gtk_window_set_policy() is deprecated. To get the effect of - "allow_shrink", call - gtk_widget_set_size_request (window, 0, 0). To get the - effect of "allow_grow", call - gtk_window_set_resizable (window, TRUE). You didn't want - the effect of "auto_shrink", it made no sense. But maybe if you were using - it you want to use gtk_window_resize (window, 1, 1) to - snap a window back to its minimum size (the 1, 1 will be rounded up to the - minimum window size). - - - - - -The core GTK+ now takes care of handling mapping, unmapping and - realizing the child widgets of containers in - gtk_widget_set_parent(). In most cases, this allows - container implementations to be simplified by removing the code in - add() methods to map and realize children. However, - there are a couple of things to watch out for here: - - - - - - -If the parent is realized before the add() happens, - gtk_widget_set_parent_window() must be called before - gtk_widget_set_parent(), since - gtk_widget_set_parent() will realize the child. - - - - - -If a container depended on its children not being mapped - unless it did so itself (for example, GtkNotebook - only mapped the current page), then the new function - gtk_widget_set_child_visible() must be called to keep - widgets that should not be mapped not mapped. - - - - As part of this change, most containers also will no longer need custom - implementations of the map() and - unmap() virtual functions. The only cases where this - is necessary are: - - - - -For !NO_WINDOW widgets, if you create children of - widget->window - and don't map them in realize() then you must map them - in map(). [ In almost all cases, you can simply map the - windows in realize(). ] - - - - - -For NO_WINDOW widgets, if you create windows in your - realize() method, you must map then in - map() and unmap them in unmap(). - - - - - - - - -gtk_widget_set_default_style(), - gtk_widget_push_style(), - and gtk_widget_pop_style() have been removed, since they - did not work properly with themes and there were better - alternatives for modifying the appearance of widgets. - - You should generally use gtk_widget_modify_*() - instead. - - - - - - -gtk_image_new() now takes no arguments and creates an - empty GtkImage widget. To create a - GtkImage widget from a - GdkImage (the least - common usage of GdkImage), use - gtk_image_new_from_image(). - - - - - -GTK_SELECTION_EXTENDED is now deprecated, and neither the - GtkList/GtkTree nor the - GtkCList/GtkCTree support - GTK_SELECTION_EXTENDED anymore. However, the old extended - behavior replaces MULTIPLE behavior. - - - - - -The following variables are no longer exported from GDK. (Other variables - are also no longer exported; the following are the ones found used - externally in a large sample of GTK+ code.) - - - - -VariableReplacement - - -gdk_null_window_warningsNone - did nothing in GTK+ 1.2 -gdk_leader_windowNone - private variable -gdk_screengdk_x11_get_default_screen () -gdk_root_windowgdk_x11_get_default_root_xwindow () -gdk_root_parentgdk_get_default_root_window () -gdk_error_codegdk_error_trap_push ()/pop () -gdk_error_warningsgdk_error_trap_push ()/pop () -gdk_display_namegdk_get_display () -gdk_wm_delete_windowgdk_atom_intern ("WM_DELETE_WINDOW", FALSE) -gdk_wm_take_focusgdk_atom_intern ("WM_TAKE_FOCUS", FALSE) -gdk_wm_protocolsgdk_atom_intern ("WM_PROTOCOLS", FALSE) - - - - - - - - - -The handling of colormaps and widgets has been changed: - - - - -The default colormap for widgets is now the GdkRGB - colormap, not the system default colormap. If you try to use resources - created for a widget (e.g., widget->style) with - a window using the system colormap, errors will result on some machines. - - - - - - -gtk_widget_push()/gtk_widget_pop_colormap() - only cause the colormap to be explicitly set on toplevel widgets, not on - all widgets. The colormap for other widgets (when not set using - gtk_widget_set_colormap()), is determined by finding - the nearest ancestor with a colormap set on it explicitly, or if that - fails, the default colormap. - - - - - - - - - - - -The default selected day for GtkCalendar is now the - current day in the month, not the first day in the month. The current month - and year were already used. - - - - - - -GDK is no longer put into threaded mode automatically when - g_thread_init() has been called. In order to use the - global GDK thread mutex with gdk_threads_enter() and - gdk_threads_leave(), you must call - gdk_threads_init() explicitly. - - If you aren't using GDK and GTK+ functions from multiple threads, - there is no reason to call gdk_threads_init(). - - - - - -The GtkPreviewInfo struct has had its visual and - colormap fields removed. Also, gtk_preview_get_cmap() - and gtk_preview_get_visual() are deprecated, as - GdkRGB works on any colormap and visual. You no - longer need to - gtk_widget_push_cmap (gtk_preview_get_cmap ()) in - your code. - - - - - - -The GtkBox, GtkTable, and - GtkAlignment widgets now call - gtk_widget_set_redraw_on_allocate (widget, FALSE); on - themselves. If you want to actually draw contents in a widget derived from - one of these widgets, you'll probably want to change this - in your init() function. - - - - - - -A number of widgets are now NO_WINDOW widgets (most - importantly GtkButton, but also - GtkRange and GtkNotebook) - - This has a couple of effects: - - - - -If you are deriving from one of these widgets, you need to - adapt your code appropriately -- for instance, drawing coordinates - start from widget->allocation.x, widget->allocation.y. - - - - - - -If you are embedding one of these widgets in a custom widget, - you must make sure you call gtk_container_propagate_expose() - correctly, as you must for any NO_WINDOW widgets. - - - - - - - GtkFixed is a little special; it is now created by - default as a NO_WINDOW widget, but if you do - - - gtk_fixed_set_has_window (fixed, TRUE); - - - after creating a fixed widget, it will create a window and - handle it properly. - - - - - -GtkLayout no longer has the xoffset, - yoffset fields, which used to store the difference between - world and window coordinates for layout->bin_window. - These coordinate systems are now always the same. - - - - - -gtk_paint_focus(), gtk_draw_focus() - and GtkStyle::draw_focus() - have been changed a bit: - - - - -A GtkStateType argument has been added to gtk_paint_focus(). - - - - - -The default implementation of the GtkStyle::draw_focus() - virtual function now draws a focus rectangle whose width is - determined by the GtkWidget::focus-width style property. - - - - - -The rectangle passed in is the bounding box, instead of - the rectangle used in the gdk_draw_rectangle() call, - so it is no longer necessary to subtract 1 from the width and height. - - - - - - - - - - - - - - diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml index d126bd491f..f40267fb1b 100644 --- a/docs/reference/gtk/compiling.sgml +++ b/docs/reference/gtk/compiling.sgml @@ -20,45 +20,45 @@ How to compile your GTK+ application Compiling GTK+ Applications on UNIX -To compile a GTK+ application, you need to tell the compiler where to +To compile a GTK+ application, you need to tell the compiler where to find the GTK+ header files and libraries. This is done with the pkg-config utility. The following interactive shell session demonstrates how -pkg-config is used (the actual output on +pkg-config is used (the actual output on your system may be different): -$ pkg-config --cflags gtk+-2.0 - -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/pango-1.0 -I/usr/X11R6/include -I/usr/include/freetype2 -I/usr/include/atk-1.0 -$ pkg-config --libs gtk+-2.0 - -L/usr/lib -L/usr/X11R6/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -lXi -lgdk_pixbuf-2.0 -lm -lpangox -lpangoxft -lXft -lXrender -lXext -lX11 -lfreetype -lpango -latk -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0 +$ pkg-config --cflags gtk+-3.0 + -pthread -I/usr/include/gtk-3.0 -I/usr/lib64/gtk-3.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12 +$ pkg-config --libs gtk+-3.0 + -pthread -lgtk-x11-3.0 -lgdk-x11-3.0 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-3.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0 The simplest way to compile a program is to use the "backticks" feature of the shell. If you enclose a command in backticks (not single quotes), then its output will be -substituted into the command line before execution. So to compile +substituted into the command line before execution. So to compile a GTK+ Hello, World, you would type the following: -$ cc `pkg-config --cflags --libs gtk+-2.0` hello.c -o hello +$ cc `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello -If you want to make sure that your program doesn't use any deprecated +If you want to make sure that your program doesn't use any deprecated functions, you can define the preprocessor symbol GTK_DISABLE_DEPRECATED by using the command line option -DGTK_DISABLE_DEPRECATED=1. -There are similar symbols GDK_DISABLE_DEPRECATED, +There are similar symbols GDK_DISABLE_DEPRECATED, GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and -GLib. +GLib. -If you want to make sure that your program doesn't use any functions which +If you want to make sure that your program doesn't use any functions which may be problematic in a multihead setting, you can define the preprocessor -symbol GDK_MULTIHEAD_SAFE by using the command line option +symbol GDK_MULTIHEAD_SAFE by using the command line option -DGTK_MULTIHEAD_SAFE=1. @@ -71,7 +71,7 @@ line option -DGTK_MULTIDEVICE_SAFE=1. The recommended way of using GTK+ has always been to only include the -toplevel headers gtk.h, gdk.h, +toplevel headers gtk.h, gdk.h, gdk-pixbuf.h. If you want to make sure that your program follows this recommended practise, you can define the preprocessor symbols GTK_DISABLE_SINGLE_INCLUDES @@ -88,14 +88,5 @@ The same for gtkunixprint.h if you use the non-portable GtkPrintUnixDialog API. - -The next major version, GTK+ 3, will remove many implementation details and -struct members from its public headers. To ensure that your application will -not have problems with this, you can define the preprocessor symbol -GSEAL_ENABLE. This will make the compiler catch all uses of direct access to -struct fields so that you can go through them one by one and replace them with -a call to an accessor function instead. - - diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index bb2b630dc2..7f5b99ceb0 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -41,11 +41,33 @@ string utilities, file utilities, a main loop abstraction, and so on. + +GObject +A library that provides a type system, a collection of +fundamental types including an object type, a signal system. + + + + +GIO +A modern, easy-to-use VFS API including abstractions for +files, drives, volumes, stream IO, as well as network programming and +DBus communication. + + + + +cairo +Cairo is a 2D graphics library with support for multiple +output devices. + + + Pango Pango is a library for internationalized text handling. It centers -around the #PangoLayout object, representing a paragraph of text. +around the #PangoLayout object, representing a paragraph of text. Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and other widgets that display text. @@ -67,7 +89,7 @@ framework. GdkPixbuf This is a small library which allows you to create #GdkPixbuf -("pixel buffer") objects from image data or image files. +("pixel buffer") objects from image data or image files. Use a #GdkPixbuf in combination with #GtkImage to display images. @@ -84,7 +106,7 @@ on X11, Windows, and the Linux framebuffer device. GTK+ -The GTK+ library itself contains widgets, +The GTK+ library itself contains widgets, that is, GUI components such as #GtkButton or #GtkTextView. @@ -400,24 +422,8 @@ that is, GUI components such as #GtkButton or #GtkTextView. - - - - - - - - - - - - - - - - - + @@ -437,50 +443,6 @@ that is, GUI components such as #GtkButton or #GtkTextView. Index of deprecated symbols - - Index of new symbols in 2.2 - - - - Index of new symbols in 2.4 - - - - Index of new symbols in 2.6 - - - - Index of new symbols in 2.8 - - - - Index of new symbols in 2.10 - - - - Index of new symbols in 2.12 - - - - Index of new symbols in 2.14 - - - - Index of new symbols in 2.16 - - - - Index of new symbols in 2.18 - - - - Index of new symbols in 2.20 - - - - Index of new symbols in 2.22 - - Index of new symbols in 3.0 diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml index 7ef2b3c277..99736eaf97 100644 --- a/docs/reference/gtk/migrating-2to3.xml +++ b/docs/reference/gtk/migrating-2to3.xml @@ -3,9 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]> - Migrating from 2.x to 3.x + Migrating from GTK+ 2.x to GTK+ 3 - + + There are a number of steps that you can take to prepare your GTK+ 2.x + application for the switch to GTK+ 3. + + +
Only single includes Make sure your program only include the toplevel headers: @@ -13,24 +18,25 @@ make CFLAGS+="-DG_DISABLE_SINGLE_INCLUDES -DGDK_PIXBUF_DISABLE_SINGLE_INCLUDES -DGTK_DISABLE_SINGLE_INCLUDES" - +
- +
Do not use deprecated symbols - Make sure your program doesn't use any deprecated functions: + Make sure your program doesn't use any functions that have been + deprecated in GTK+ 2.x: make CFLAGS+="-DG_DISABLE_DEPRECATED -DGDK_PIXBUF_DISABLE_DEPRECATED -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED" - +
- - Use accessor funcions instead direc access +
+ Use accessor functions instead direct access - GTK+ 3 removed many implementation details and struct members from - its public headers. To ensure that your application will not have problems - with this, you can define the preprocessor symbol GSEAL_ENABLE. This will + GTK+ 3 removes many implementation details and struct members from + its public headers. To ensure that your application does not have problems + with this, you define the preprocessor symbol GSEAL_ENABLE. This will make the compiler catch all uses of direct access to struct fields so that you can go through them one by one and replace them with a call to an accessor function instead. @@ -38,22 +44,27 @@ make CFLAGS+="-DGSEAL_ENABLE" - +
- +
GTK+ Modules - Some GNOME modules install GTK+ modules. Since GTK+ 3 will be - parallel-installable with GTK+ 2.x, the two have separate locations for - their loadable modules. The location for GTK+ 2.x is $libdir/gtk-2.0 - (and its subdirectories), for GTK+ 3, the location is $libdir/gtk-3.0 + Some software packages install loadable GTK+ modules such as theme engines, + gdk-pixbuf loaders or input methods. Since GTK+ 3 is parallel-installable + with GTK+ 2.x, the two GTK+ versions have separate locations for their + loadable modules. The location for GTK+ 2.x is + libdir/gtk-2.0 + (and its subdirectories), for GTK+ 3 the location is + libdir/gtk-3.0 (and its subdirectories). - For some kinds of modules, namely im modules and pixbuf loaders, + For some kinds of modules, namely input methods and pixbuf loaders, GTK+ keeps a cache file with extra information about the modules. - These cache files are located in $sysconfdir/gtk-2.0 for GTK+ 2.x. - For GTK+ 3, they have been moved to $libdir/gtk-3.0/3.0.0/. + For GTK+ 2.x, these cache files are located in + sysconfdir/gtk-2.0. + For GTK+ 3, they have been moved to + libdir/gtk-3.0/3.0.0/. The commands that create these cache files have been renamed with a -3 suffix to make them parallel-installable. @@ -65,5 +76,5 @@ against libgtk 2.x into an application using GTK+ 3 will lead to unhappiness and must be avoided. - +
diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml index 1c2a3c88d0..8b5a58a6c9 100644 --- a/docs/reference/gtk/migrating-checklist.sgml +++ b/docs/reference/gtk/migrating-checklist.sgml @@ -19,15 +19,15 @@ Why - By handling this signal, you let widgets have - context-sensitive menus that can be invoked with the standard - key bindings. + By handling this signal, you let widgets have + context-sensitive menus that can be invoked with the standard + key bindings. - The #GtkWidget::popup-menu signal instructs the widget for which - it is emitted to create a context-sensitive popup menu. By default, + The #GtkWidget::popup-menu signal instructs the widget for which + it is emitted to create a context-sensitive popup menu. By default, the key binding mechanism is set to emit this signal when the ShiftF10 @@ -39,14 +39,14 @@ - - Write a function to create and show a popup menu. This - function needs to know the button number and the event's - time to pass them to gtk_menu_popup(). You can implement - such a function like this: - + + Write a function to create and show a popup menu. This + function needs to know the button number and the event's + time to pass them to gtk_menu_popup(). You can implement + such a function like this: + - + static void do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) { @@ -54,7 +54,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) int button, event_time; menu = gtk_menu_new (); - g_signal_connect (menu, "deactivate", + g_signal_connect (menu, "deactivate", G_CALLBACK (gtk_widget_destroy), NULL); /* ... add menu items ... */ @@ -71,19 +71,19 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) } gtk_menu_attach_to_widget (GTK_MENU (menu), my_widget, NULL); - gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL, + gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL, button, event_time); } - + - - In your #GtkWidget::button-press-event handler, call this function + + In your #GtkWidget::button-press-event handler, call this function when you need to pop up a menu: - + - + static gboolean my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event) { @@ -96,52 +96,52 @@ my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event) return FALSE; } - + - - Implement a handler for the #GtkWidget::popup-menu signal: - + + Implement a handler for the #GtkWidget::popup-menu signal: + - + static gboolean my_widget_popup_menu_handler (GtkWidget *widget) { do_popup_menu (widget, NULL); return TRUE; } - + - If you do not pass a positioning function to gtk_menu_popup(), - it will show the menu at the mouse position by default. This - is what you usually want when the menu is shown as a result of - pressing a mouse button. However, if you press the - ShiftF10 - or Menu keys while the widget is focused, the - mouse cursor may not be near the widget at all. In the example above, you may want to - provide your own menu-positioning function - in the case where the event is - %NULL. This function should compute the desired position for - a menu when it is invoked through the keyboard. For example, - #GtkEntry aligns the top edge of its popup menu with the bottom + If you do not pass a positioning function to gtk_menu_popup(), + it will show the menu at the mouse position by default. This + is what you usually want when the menu is shown as a result of + pressing a mouse button. However, if you press the + ShiftF10 + or Menu keys while the widget is focused, the + mouse cursor may not be near the widget at all. In the example above, you may want to + provide your own menu-positioning function + in the case where the event is + %NULL. This function should compute the desired position for + a menu when it is invoked through the keyboard. For example, + #GtkEntry aligns the top edge of its popup menu with the bottom edge of the entry. - For the standard key bindings to work, your widget must be - able to take the keyboard focus. In general, widgets should - be fully usable through the keyboard and not just the mouse. - The very first step of this is to ensure that your widget - turns on the %GTK_CAN_FOCUS flag. + For the standard key bindings to work, your widget must be + able to take the keyboard focus. In general, widgets should + be fully usable through the keyboard and not just the mouse. + The very first step of this is to ensure that your widget + turns on the %GTK_CAN_FOCUS flag. @@ -152,23 +152,21 @@ my_widget_popup_menu_handler (GtkWidget *widget) Why - The region field of - GdkEventExpose allows you to redraw - less than the traditional - GdkEventRegion.area. + The region field of + GdkEventExpose allows you to redraw + less than the traditional GdkEventRegion.area. - In GTK+ 1.x, the GdkEventExpose + In early GTK+ versions, the GdkEventExpose structure only had an area field to - let you determine the region that you needed to redraw. In GTK+ - 2.x, this field exists for compatibility and as a simple - interface. However, there is also a - region field which contains a - fine-grained region. The area field - is simply the bounding rectangle of the - region. + let you determine the region that you needed to redraw. In current + GTK+, this field still exists for compatibility and as a simple + interface. However, there is also a region + field which contains a fine-grained region. The + area field is simply the bounding rectangle + of the region. @@ -183,7 +181,7 @@ my_widget_popup_menu_handler (GtkWidget *widget) Regions have an internal representation that is accessible as a - list of rectangles. To turn the + list of rectangles. To turn the GdkEventExpose.region field into such a list, use gdk_region_get_rectangles(): @@ -200,7 +198,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) for (i = 0; i < n_rects; i++) { - /* Repaint rectangle: (rects[i].x, rects[i].y), + /* Repaint rectangle: (rects[i].x, rects[i].y), * (rects[i].width, rects[i].height) */ } @@ -218,9 +216,9 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) Why - With gtk_accelerator_get_default_mod_mask() you can test for - modifier keys reliably; this way your key event handlers will - work correctly even if NumLock or + With gtk_accelerator_get_default_mod_mask() you can test for + modifier keys reliably; this way your key event handlers will + work correctly even if NumLock or CapsLock are activated. @@ -230,8 +228,8 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) state field is a bit mask which indicates the modifier state at the time the key was pressed. Modifiers are keys like Control and - NumLock. When implementing a - #GtkWidget::key-press-event handler, you should use + NumLock. When implementing a + #GtkWidget::key-press-event handler, you should use gtk_accelerator_get_default_mod_mask() to test against modifier keys. This function returns a bit mask which encompasses all the modifiers which the user may be @@ -289,17 +287,16 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event) Why - Named icons automatically adapt to theme changes, giving your + Named icons automatically adapt to theme changes, giving your application a much more integrated appearance. - Since GTK+ 2.6, named icons can be used for window icons (see - gtk_window_set_icon_name()) and images (see gtk_image_set_icon_name()). - In GTK+ 2.8, you can also use named icons for drag-and-drop (see - gtk_drag_source_set_icon_name()) and in treeview cells (see the - #GtkCellRendererPixbuf:icon-name property). + Named icons can be used for window icons (see gtk_window_set_icon_name()) + and images (see gtk_image_set_icon_name()). You can also use named icons + for drag-and-drop (see gtk_drag_source_set_icon_name()) and in treeview + cells (see the #GtkCellRendererPixbuf:icon-name property). diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index 225d564479..c8c26dafaa 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -63,19 +63,14 @@ See the documentation on this topic. -How do I port from one GTK+ +How do I port from one GTK+ version to another? -See the list of incompatible changes -from 1.2 to 2.0. Also, the GNOME 2.0 porting -guide on http://developer.gnome.org -has some more detailed discussion of porting from 1.2 to 2.0. -You may also find useful information in the documentation for +See . +You may also find useful information in the documentation for specific widgets and functions.