The tree only sets the focus in response to a TVN_SELCHANGINGW event if the tree...

[wxWidgets.git] / docs / doxygen / overviews / backwardcompatibility.h

diff --git a/docs/doxygen/overviews/backwardcompatibility.h b/docs/doxygen/overviews/backwardcompatibility.h
index e9faddb2ea3292ee97cd1137e7fe0939df310f2e..41e2083eb5cdc3b12a1b5309920b131cdd79e996 100644 (file)
--- a/docs/doxygen/overviews/backwardcompatibility.h
+++ b/docs/doxygen/overviews/backwardcompatibility.h
@@ -1,159 +1,173 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        backwardcompatibility
+// Name:        backwardcompatibility.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/*!
-
- @page backwardcompatibility_overview Backward compatibility
-
- Many of the GUIs and platforms supported by wxWidgets are continuously
- evolving, and some of the new platforms wxWidgets now supports were quite
- unimaginable even a few years ago. In this environment wxWidgets must also
- evolve in order to support these new features and platforms.
- However the goal of wxWidgets is not only to provide a consistent
- programming interface across many platforms, but also to provide an
- interface that is reasonably stable over time, to help protect its users
- from some of the uncertainty of the future.
- @ref versionnumbering_overview
- @ref sourcecompatibility_overview
- @ref libbincompatibility_overview
- @ref appbincompatibility_overview
-
-
- @section versionnumbering The version numbering scheme
-
- wxWidgets version numbers can have up to four components, with trailing
- zeros sometimes omitted:
-
- @code
- major.minor.release.sub-release
- @endcode
-
- A stable release of wxWidgets will have an even number for @c minor, e.g. @c 2.6.0.
- Stable, in this context, means that the API is not changing. In truth, some
- changes are permitted, but only those that are backward compatible. For
- example, you can expect later @c 2.6.x.x releases, such as @c 2.6.1
- and @c 2.6.2 to be backward compatible with their predecessor.
- When it becomes necessary to make changes which are not wholly backward
- compatible, the stable branch is forked, creating a new development
- branch of wxWidgets. This development branch will have an odd number
- for @c minor, for example @c 2.7.x.x. Releases from this branch are
- known as development snapshots.
- The stable branch and the development branch will then be developed in
- parallel for some time. When it is no longer useful to continue developing
- the stable branch, the development branch is renamed and becomes a new
- stable branch, for example @c 2.8.0. And the process begins again.
- This is how the tension between keeping the interface stable, and allowing
- the library to evolve is managed.
- You can expect the versions with the same major and even minor
- version number to be compatible, but between minor versions there will be
- incompatibilities. Compatibility is not broken gratuitously however, so
- many applications will require no changes or only small changes to work
- with the new version.
-
- @section sourcecompatibility Source level compatibility
-
- Later releases from a stable branch are backward compatible with earlier
- releases from the same branch at the source level.
- This means that, for example, if you develop your application using
- wxWidgets @c 2.6.0 then it should also compile fine with all later @c 2.6.x versions. The converse is also @true providing you avoid any new
- features not present in the earlier version. For example if you develop
- using @c 2.6.1 your program will compile fine with wxWidgets @c 2.6.0
- providing you don't use any @c 2.6.1 specific features.
- For some platforms binary compatibility is also supported, see 'Library
- binary compatibility' below.
- Between minor versions, for example between @c 2.2.x, @c 2.4.x and @c 2.6.x, there will be some incompatibilities. Wherever possible the old way
- of doing something is kept alongside the new for a time wrapped inside:
-
- @code
- #if WXWIN_COMPATIBILITY_2_4
-         /* deprecated feature */
-...
+/**
+
+@page overview_backwardcompat Backwards Compatibility
+
+Many of the GUIs and platforms supported by wxWidgets are continuously
+evolving, and some of the new platforms wxWidgets now supports were quite
+unimaginable even a few years ago. In this environment wxWidgets must also
+evolve in order to support these new features and platforms.
+
+However the goal of wxWidgets is not only to provide a consistent programming
+interface across many platforms, but also to provide an interface that is
+reasonably stable over time, to help protect its users from some of the
+uncertainty of the future.
+
+@li @ref overview_backwardcompat_versionnumbering
+@li @ref overview_backwardcompat_sourcecompat
+@li @ref overview_backwardcompat_libbincompat
+@li @ref overview_backwardcompat_appbincompat
+
+
+<hr>
+
+
+@section overview_backwardcompat_versionnumbering The Version Numbering Scheme
+
+wxWidgets version numbers can have up to four components, with trailing zeros
+sometimes omitted:
+
+@verbatim
+major.minor.release.sub-release
+@endverbatim
+
+A stable release of wxWidgets will have an even number for @e minor, e.g.
+2.6.0. Stable, in this context, means that the API is not changing. In truth,
+some changes are permitted, but only those that are backward compatible. For
+example, you can expect later 2.6.x releases, such as 2.6.1 and 2.6.2 to be
+backward compatible with their predecessor.
+
+When it becomes necessary to make changes which are not wholly backward
+compatible, the stable branch is forked, creating a new development branch of
+wxWidgets. This development branch will have an odd number for @e minor, for
+example 2.7.x. Releases from this branch are known as development snapshots.
+
+The stable branch and the development branch will then be developed in parallel
+for some time. When it is no longer useful to continue developing the stable
+branch, the development branch is renamed and becomes a new stable branch, for
+example: 2.8.0. And the process begins again. This is how the tension between
+keeping the interface stable, and allowing the library to evolve is managed.
+
+You can expect the versions with the same major and even minor version number
+to be compatible, but between minor versions there will be incompatibilities.
+Compatibility is not broken gratuitously however, so many applications will
+require no changes or only small changes to work with the new version.
+
+
+@section overview_backwardcompat_sourcecompat Source Level Compatibility
+
+Later releases from a stable branch are backward compatible with earlier
+releases from the same branch at the source level. This means that, for
+example, if you develop your application using wxWidgets 2.8.0 then it should
+also compile fine with all later 2.8.x versions.
+
+The converse is also true providing you avoid any new features not present in
+the earlier version. For example if you develop using 2.6.1 your program will
+compile fine with wxWidgets 2.8.0 providing you don't use any 2.8.1 specific
+features.
+
+For some platforms binary compatibility is also supported, see
+@ref overview_backwardcompat_libbincompat below.
+
+Between minor versions, for example between 2.4.x, 2.6.x and 2.8.x, there will
+be some incompatibilities. Wherever possible the old way of doing something is
+kept alongside the new for a time wrapped inside:
+
+@code
+#if WXWIN_COMPATIBILITY_2_6
+    // deprecated feature
+    ...

 #endif
 @endcode
 
 #endif
 @endcode
 

-By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
-    to 1 for the previous stable branch, for example
-        in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
-            stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
-                            for @c 2.6.x. Earlier than that, obsolete features are removed.
-                                These macros can be changed in @c setup.h. Or on UNIX-like systems you can
-                                set them using the @c --disable-compat24 and @c --enable-compat22
-                                options to @c configure.
-                                They can be useful in two ways:
+By default the @c WXWIN_COMPATIBILITY_X_X macro is set to 1 for the previous
+stable branch, for example in 2.8.x, @c WXWIN_COMPATIBILITY_2_6 = 1. For the
+next earlier stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_4 = 0
+for 2.8.x. Earlier than that, obsolete features are removed.
+
+These macros can be changed in @c setup.h. Or on UNIX-like systems you can set
+them using the @c --disable-compat26 and @c --enable-compat24 options to
+configure.

 
 

+They can be useful in two ways:

 
 

-Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
-find uses of deprecated features in your program.
-Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
-compile a program developed using @c 2.2.x that no longer compiles
-with @c 2.6.x.
+@li Changing @c WXWIN_COMPATIBILITY_2_6 to 0 can be useful to find uses of
+    deprecated features in your program that should eventually be removed.
+@li Changing @c WXWIN_COMPATIBILITY_2_4 to 1 can be useful to compile a program
+    developed using 2.4.x that no longer compiles with 2.8.x.

 
 

+A program requiring one of these macros to be 1 will become incompatible with
+some future version of wxWidgets, and you should consider updating it.

 
 

-A program requiring one of these macros to be 1 will become
-incompatible with some future version of wxWidgets, and you should consider
-updating it.

 
 

-@section libbincompatibility Library binary compatibility
+@section overview_backwardcompat_libbincompat Library Binary Compatibility

 
 For some platforms, releases from a stable branch are not only source level
 compatible but can also be binary compatible.
 
 For some platforms, releases from a stable branch are not only source level
 compatible but can also be binary compatible.

-Binary compatibility makes it possible to get the maximum benefit from
-using shared libraries, also known as dynamic link libraries (DLLs) on
-Windows or dynamic shared libraries on OS X.
-For example, suppose several applications are installed on a system requiring
-wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
-backward compatible with the earlier versions, it should be enough to
-install just wxWidgets @c 2.6.2 shared libraries, and all the applications
-should be able to use them. If binary compatibility is not supported, then all
-the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
-installed side by side.
-Achieving this, without the user being required to have the source code
-and recompile everything, places many extra constraints on the changes
-that can be made within the stable branch. So it is not supported for all
-platforms, and not for all versions of wxWidgets. To date it has mainly
-    been supported by wxGTK for UNIX-like platforms.
-        Another practical consideration is that for binary compatibility to work,
-            all the applications and libraries must have been compiled with compilers
-            that are capable of producing compatible code;
-that is, they must use the
-same ABI (Application Binary Interface). Unfortunately most different C++
-compilers do not produce code compatible with each other, and often even
-    different versions of the same compiler are not compatible.
-
-    @section appbincompatibility Application binary compatibility
-
-    The most important aspect of binary compatibility is that applications
-    compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work
-    with shared libraries of a later binary compatible version, for example @c 2.6.2.
-    The converse can also be useful however. That is, it can be useful for a
-        developer using a later version, e.g. @c 2.6.2 to be able to create binary
-        application packages that will work with all binary compatible versions of
-        the shared library starting with, for example @c 2.6.0.
-            To do this the developer must, of course, avoid any features not available
-                in the earlier versions. However this is not necessarily enough;
-in some
-cases an application compiled with a later version may depend on it even
-though the same code would compile fine against an earlier version.
-To help with this, a preprocessor symbol @c wxABI_VERSION can be defined
-during the compilation of the application (this would usually be done in the
-        application's makefile or project settings). It should be set to the lowest
-        version that is being targeted, as a number with two decimal digits for each
-        component, for example @c wxABI_VERSION=20600 for @c 2.6.0.
-        Setting @c wxABI_VERSION should prevent the application from implicitly
-        depending on a later version of wxWidgets, and also disables any new features
-        in the API, giving a compile time check that the source is compatible with
-        the versions of wxWidgets being targeted.
-        Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when
-        each new development branch is created. Therefore it is only useful to help
-        achieve compatibility with earlier versions with the same major
-        and even minor version numbers. It won't, for example, help you write
-        code compatible with @c 2.4.x using wxWidgets @c 2.6.x.
-
-        */

 
 

+Binary compatibility makes it possible to get the maximum benefit from using
+shared libraries, also known as dynamic link libraries (DLLs) on Windows or
+dynamic shared libraries on OS X.
+
+For example, suppose several applications are installed on a system requiring
+wxWidgets 2.6.0, 2.6.1 and 2.6.2. Since 2.6.2 is backward compatible with the
+earlier versions, it should be enough to install just wxWidgets 2.6.2 shared
+libraries, and all the applications should be able to use them. If binary
+compatibility is not supported, then all the required versions 2.6.0, 2.6.1 and
+2.6.2 must be installed side by side.
+
+Achieving this, without the user being required to have the source code and
+recompile everything, places many extra constraints on the changes that can be
+made within the stable branch. So it is not supported for all platforms, and
+not for all versions of wxWidgets. To date it has mainly been supported by
+wxGTK for UNIX-like platforms.
+
+Another practical consideration is that for binary compatibility to work, all
+the applications and libraries must have been compiled with compilers that are
+capable of producing compatible code; that is, they must use the same ABI
+(Application Binary Interface). Unfortunately most different C++ compilers do
+not produce code compatible with each other, and often even different versions
+of the same compiler are not compatible.
+
+
+@section overview_backwardcompat_appbincompat Application Binary Compatibility
+
+The most important aspect of binary compatibility is that applications compiled
+with one version of wxWidgets, e.g. 2.6.1, continue to work with shared
+libraries of a later binary compatible version, for example 2.6.2. The converse
+can also be useful however. That is, it can be useful for a developer using a
+later version, e.g. 2.6.2 to be able to create binary application packages that
+will work with all binary compatible versions of the shared library starting
+with, for example 2.6.0.
+
+To do this the developer must, of course, avoid any features not available in
+the earlier versions. However this is not necessarily enough; in some cases an
+application compiled with a later version may depend on it even though the same
+code would compile fine against an earlier version.
+
+To help with this, a preprocessor symbol @c wxABI_VERSION can be defined during
+the compilation of the application (this would usually be done in the
+application's makefile or project settings). It should be set to the lowest
+version that is being targeted, as a number with two decimal digits for each
+component, for example @c wxABI_VERSION=20600 for 2.6.0.
+
+Setting @c wxABI_VERSION should prevent the application from implicitly
+depending on a later version of wxWidgets, and also disables any new features
+in the API, giving a compile time check that the source is compatible with the
+versions of wxWidgets being targeted.
+
+Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when each
+new development branch is created. Therefore it is only useful to help achieve
+compatibility with earlier versions with the same major and even minor version
+numbers. It won't, for example, help you write code compatible with 2.6.x using
+wxWidgets 2.8.x.
+
+*/