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