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
  65 The other class of incompatible changes is due to modifying some virtual
  66 methods to use @c wxString parameters instead of @c const @c wxChar* ones to
  67 make them accept both narrow and wide strings. This is not a problem if you
  68 simply call these functions but you need to change the signature of the derived
  69 class versions if you override them as otherwise they wouldn't be called any
  70 more. Again, the best way to ensure that this problem doesn't arise is to
  71 rebuild your code using a compiler which warns about function signature
  72 mismatch (you can use @c -Woverloaded-virtual g++ option).
  73
  74 Finally, a few structure fields, notable @c wxCmdLineEntryDesc::shortName,
  75 @c longName and @c description fields have been changed to be of type @c const
  76 @c char* instead of @c const @c wxChar* so you will need to remove @c wxT() or
  77 @c _T() if you used it with their initializers.
  78
  79 @section overview_changes_other Miscellaneous Other Changes
  80
  81 - Default location of wxFileConfig files has changed under Windows, you will
  82   need to update your code if you access these files directly.
  83
  84 - wxWindow::IsEnabled() now returns false if a window parent (and not
  85   necessarily the window itself) is disabled, new function IsThisEnabled()
  86   with the same behaviour as old IsEnabled() was added.
  87
  88 - Generating wxNavigationKeyEvent events doesn't work any more under wxGTK (and
  89   other platforms in the future), use wxWindow::Navigate() or NavigateIn()
  90   instead.
  91
  92 - Sizers distribute only the extra space between the stretchable items
  93   according to their proportions and not all available space. We believe the
  94   new behaviour corresponds better to user expectations but if you did rely
  95   on the old behaviour you will have to update your code to set the minimal
  96   sizes of the sizer items to be in the same proportion as the items
  97   proportions to return to the old behaviour.
  98
  99 - wxWindow::Freeze/Thaw() are not virtual any more, if you overrode them in
 100   your code you need to override DoFreeze/Thaw() instead now.
 101
 102 - wxCalendarCtrl has native implementation in wxGTK, but it has less features
 103   than the generic one. The native implementation is used by default, but you
 104   can still use wxGenericCalendarCtrl instead of wxCalendarCtrl in your code if
 105   you need the extra features.
 106
 107 - wxDocument::FileHistoryLoad() and wxFileHistory::Load() now take const
 108   reference to wxConfigBase argument and not just a reference, please update
 109   your code if you overrode these functions and change the functions in the
 110   derived classes to use const reference as well.
 111
 112 - Calling wxConfig::Write() with an enum value will fail to compile because
 113   wxConfig now tries to convert all unknown types to wxString automatically
 114   using wxToString() function.
 115
 116   The simplest solution is to cast the enum value to int, e.g.
 117   @code
 118     enum Colour { Red, Green, Blue };
 119
 120     wxConfig conf;
 121     conf.Write("MyFavouriteColour", Red);       // ERROR: no match
 122     conf.Write("MyFavouriteColour", int(Red));  // OK
 123   @endcode
 124
 125   Another possibility which exists now is to provide an overload of
 126   wxToString() (and wxFromString()) for your own type, e.g.
 127
 128   @code
 129     wxString wxToString(Colour col)
 130     {
 131         return col == Red ? "R" : col == Green ? "G" : "B";
 132     }
 133
 134     bool wxFromString(const wxString& s, Colour* col)
 135     {
 136         if ( s.length() != 1 )
 137             return false;
 138
 139         switch ( s[0].GetValue() )
 140         {
 141             case 'R': *col = Red; return true;
 142             case 'G': *col = Green; return true;
 143             case 'B': *col = Blue; return true;
 144         }
 145
 146         return false;
 147     }
 148   @endcode
 149
 150   Of course, this will change the format of the wxConfig output which may be
 151   undesirable.
 152
 153 - wxTE_AUTO_SCROLL style is deprecated as it's always on by default anyhow in
 154   the ports which support it so you should simply remove any mentions of it
 155   from your code.
 156 */
 157