docs/doxygen/overviews/changes_since28.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        changes_since28.h
   3 // Purpose:     topic overview
   4 // Author:      Vadim Zeitlin
   5 // Created:     2008-05-08
   6 // RCS-ID:      $Id$
   7 // Licence:     wxWindows license
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11
  12 @page overview_changes_since28 Changes Since wxWidgets 2.8
  13
  14 This topic describes backwards-incompatible changes in wxWidgets 3.0 compared
  15 to the last stable release.
  16
  17 The incompatible changes can be grouped into the following categories:
  18
  19 @li @ref overview_changes_unicode
  20 @li @ref overview_changes_other
  21
  22
  23 <hr>
  24
  25 @section overview_changes_unicode Unicode-related Changes
  26
  27 If you used Unicode build of wxWidgets 2.8 or previous version, please read
  28 @ref overview_unicode for the details about how the API changed in 3.0 as a lot
  29 of the information which was correct before doesn't apply any longer.
  30
  31 For example, the notorious (due to the confusion they created) macros @c wxT()
  32 and @c _T() are not needed at all any longer. Basically, you can remove them
  33 from any code which used them. On the other hand, there is no particular harm
  34 in leaving them neither as the code will still compile and work correctly --
  35 you only need to remove them if you think that your code looks tidier without
  36 them. You also don't need to use @c wxChar any longer but can directly use the
  37 standard @c wchar_t type even if, again, @c wxChar continues to work.
  38
  39 The most serious backwards-incompatible change is related to the change of
  40 return type of wxString::c_str() method: it returns a special proxy object
  41 instead of a simple @c char* or @c wchar_t* now. Because of this, you cannot
  42 pass its result to any standard vararg functions such as @c printf() any more
  43 as described in @ref overview_unicode_compilation_errors. All wxWidgets
  44 functions, such as wxPrintf(), wxLogMessage() &c still work with it, but
  45 passing it to @c printf() will now result in a crash. It is strongly advised to
  46 recompile your code with a compiler warning about passing non-POD objects to
  47 vararg functions, such as g++.
  48
  49 The change of the type of wxString::c_str() can also result in compilation
  50 errors when passing its result to a function overloaded to take both narrow and
  51 wide strings and in this case you must select the version which you really want
  52 to use, e.g.:
  53 @code
  54     void OpenLogFile(const char *filename);
  55     void OpenLogFile(const wchar_t *filename);
  56
  57     wxString s;
  58     OpenLogFile(s);             // ERROR: ambiguity
  59     OpenLogFile(s.c_str());     // ERROR: ambiguity
  60     OpenLogFile(s.wx_str());    // OK: function called depends on the build
  61     OpenLogFile(s.mb_str());    // OK: always calls narrow string overload
  62     OpenLogFile(s.wc_str());    // OK: always calls wide string overload
  63 @endcode
  64 A common example of such problem arises with @c std::fstream class constructor
  65 in Microsoft Visual C++ standard library implementation. In addition to a
  66 constructor from @c const @c char * which this class must have, it also
  67 provides a constructor taking a wide character file name. Because of this, code
  68 like the following
  69 @code
  70     #include <fstream>
  71
  72     void MyFunc(const wxString& filename)
  73     {
  74         std::ifstream ifs(filename.c_str());
  75         ...
  76     }
  77 @endcode
  78 does not compile when using Microsoft Visual C++ and needs to be changed to use
  79 mb_str() (which will not work for file names containing Unicode characters,
  80 consider using wxWidgets classes and functions to work with such file names as
  81 they are not supported by standard C++ library).
  82
  83 The other class of incompatible changes is due to modifying some virtual
  84 methods to use @c wxString parameters instead of @c const @c wxChar* ones to
  85 make them accept both narrow and wide strings. This is not a problem if you
  86 simply call these functions but you need to change the signature of the derived
  87 class versions if you override them as otherwise they wouldn't be called any
  88 more. Again, the best way to ensure that this problem doesn't arise is to
  89 rebuild your code using a compiler which warns about function signature
  90 mismatch (you can use @c -Woverloaded-virtual g++ option).
  91
  92 Finally, a few structure fields, notable @c wxCmdLineEntryDesc::shortName,
  93 @c longName and @c description fields have been changed to be of type @c const
  94 @c char* instead of @c const @c wxChar* so you will need to remove @c wxT() or
  95 @c _T() if you used it with their initializers.
  96
  97 @section overview_changes_other Miscellaneous Other Changes
  98
  99 - Default location of wxFileConfig files has changed under Windows, you will
 100   need to update your code if you access these files directly.
 101
 102 - wxWindow::IsEnabled() now returns false if a window parent (and not
 103   necessarily the window itself) is disabled, new function IsThisEnabled()
 104   with the same behaviour as old IsEnabled() was added.
 105
 106 - Generating wxNavigationKeyEvent events doesn't work any more under wxGTK (and
 107   other platforms in the future), use wxWindow::Navigate() or NavigateIn()
 108   instead.
 109
 110 - Sizers distribute only the extra space between the stretchable items
 111   according to their proportions and not all available space. We believe the
 112   new behaviour corresponds better to user expectations but if you did rely
 113   on the old behaviour you will have to update your code to set the minimal
 114   sizes of the sizer items to be in the same proportion as the items
 115   proportions to return to the old behaviour.
 116
 117 - wxWindow::Freeze/Thaw() are not virtual any more, if you overrode them in
 118   your code you need to override DoFreeze/Thaw() instead now.
 119
 120 - wxCalendarCtrl has native implementation in wxGTK, but it has less features
 121   than the generic one. The native implementation is used by default, but you
 122   can still use wxGenericCalendarCtrl instead of wxCalendarCtrl in your code if
 123   you need the extra features.
 124
 125 - wxDocument::FileHistoryLoad() and wxFileHistory::Load() now take const
 126   reference to wxConfigBase argument and not just a reference, please update
 127   your code if you overrode these functions and change the functions in the
 128   derived classes to use const reference as well.
 129
 130 - Calling wxConfig::Write() with an enum value will fail to compile because
 131   wxConfig now tries to convert all unknown types to wxString automatically
 132   using wxToString() function.
 133
 134   The simplest solution is to cast the enum value to int, e.g.
 135   @code
 136     enum Colour { Red, Green, Blue };
 137
 138     wxConfig conf;
 139     conf.Write("MyFavouriteColour", Red);       // ERROR: no match
 140     conf.Write("MyFavouriteColour", int(Red));  // OK
 141   @endcode
 142
 143   Another possibility which exists now is to provide an overload of
 144   wxToString() (and wxFromString()) for your own type, e.g.
 145
 146   @code
 147     wxString wxToString(Colour col)
 148     {
 149         return col == Red ? "R" : col == Green ? "G" : "B";
 150     }
 151
 152     bool wxFromString(const wxString& s, Colour* col)
 153     {
 154         if ( s.length() != 1 )
 155             return false;
 156
 157         switch ( s[0].GetValue() )
 158         {
 159             case 'R': *col = Red; return true;
 160             case 'G': *col = Green; return true;
 161             case 'B': *col = Blue; return true;
 162         }
 163
 164         return false;
 165     }
 166   @endcode
 167
 168   Of course, this will change the format of the wxConfig output which may be
 169   undesirable.
 170
 171 - wxTE_AUTO_SCROLL style is deprecated as it's always on by default anyhow in
 172   the ports which support it so you should simply remove any mentions of it
 173   from your code.
 174
 175 - If you use wxScrolled<T>::SetTargetWindow() you must override
 176   wxScrolled<T>::GetSizeAvailableForScrollTarget() method to compute the size
 177   available for the scroll target as function of the main window size, please
 178   see the documentation of this method for more details.
 179 */
 180