fixing return values and handling of invalid files

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

diff --git a/docs/doxygen/overviews/changes_since28.h b/docs/doxygen/overviews/changes_since28.h
index 0f7846ccdb7b50c77025fa3f490b6f2d5d5f448f..f7dc4dffb25fa28689f5f8e72a70a03d606918a6 100644 (file)
--- a/docs/doxygen/overviews/changes_since28.h
+++ b/docs/doxygen/overviews/changes_since28.h
@@ -46,6 +46,22 @@ passing it to @c printf() will now result in a crash. It is strongly advised to
 recompile your code with a compiler warning about passing non-POD objects to
 vararg functions, such as g++.
 
+The change of the type of wxString::c_str() can also result in compilation
+errors when passing its result to a function overloaded to take both narrow and
+wide strings and in this case you must select the version which you really want
+to use, e.g.:
+@code
+    void OpenLogFile(const char *filename);
+    void OpenLogFile(const wchar_t *filename);
+
+    wxString s;
+    OpenLogFile(s);             // ERROR: ambiguity
+    OpenLogFile(s.c_str());     // ERROR: ambiguity
+    OpenLogFile(s.wx_str());    // OK: function called depends on the build
+    OpenLogFile(s.mb_str());    // OK: always calls narrow string overload
+    OpenLogFile(s.wc_str());    // OK: always calls wide string overload
+@endcode
+
 The other class of incompatible changes is due to modifying some virtual
 methods to use @c wxString parameters instead of @c const @c wxChar* ones to
 make them accept both narrow and wide strings. This is not a problem if you
@@ -93,5 +109,54 @@ Finally, a few structure fields, notable @c wxCmdLineEntryDesc::shortName,
   your code if you overrode these functions and change the functions in the
   derived classes to use const reference as well.
 
+- Calling wxConfig::Write() with an enum value will fail to compile because
+  wxConfig now tries to convert all unknown types to wxString automatically
+  using wxToString() function.
+
+  The simplest solution is to cast the enum value to int, e.g.
+  @code
+    enum Colour { Red, Green, Blue };
+
+    wxConfig conf;
+    conf.Write("MyFavouriteColour", Red);       // ERROR: no match
+    conf.Write("MyFavouriteColour", int(Red));  // OK
+  @endcode
+
+  Another possibility which exists now is to provide an overload of
+  wxToString() (and wxFromString()) for your own type, e.g.
+
+  @code
+    wxString wxToString(Colour col)
+    {
+        return col == Red ? "R" : col == Green ? "G" : "B";
+    }
+
+    bool wxFromString(const wxString& s, Colour* col)
+    {
+        if ( s.length() != 1 )
+            return false;
+
+        switch ( s[0].GetValue() )
+        {
+            case 'R': *col = Red; return true;
+            case 'G': *col = Green; return true;
+            case 'B': *col = Blue; return true;
+        }
+
+        return false;
+    }
+  @endcode
+
+  Of course, this will change the format of the wxConfig output which may be
+  undesirable.
+
+- wxTE_AUTO_SCROLL style is deprecated as it's always on by default anyhow in
+  the ports which support it so you should simply remove any mentions of it
+  from your code.
+
+- If you use wxScrolled<T>::SetTargetWindow() you must override
+  wxScrolled<T>::GetSizeAvailableForScrollTarget() method to compute the size
+  available for the scroll target as function of the main window size, please
+  see the documentation of this method for more details.
 */