initial commit

Signed-off-by: Peter Siegmund <mars3142@noreply.mars3142.dev>

libs/wxWidgets-3.3.1/docs/doxygen/overviews/changes_since28.h

@@ -0,0 +1,194 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        changes_since28.h
+// Purpose:     topic overview
+// Author:      Vadim Zeitlin
+// Created:     2008-05-08
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page overview_changes_since28 Changes Since wxWidgets 2.8
+
+This topic describes backwards-incompatible changes in wxWidgets 3.0 compared
+to the last stable release and is very important to read if you are updating
+from the 2.8 or an older version. And even if you hadn't used any previous
+version of wxWidgets and are starting directly with 3.0, it can still be useful
+to have at least a quick look at it just to know that some of the older
+examples and tutorials may not be applicable any more to wxWidgets 3.0.
+
+
+The incompatible changes can be grouped into the following categories:
+
+@li @ref overview_changes_unicode
+@li @ref overview_changes_other
+
+
+<hr>
+
+@section overview_changes_unicode Unicode-related Changes
+
+If you used Unicode build of wxWidgets 2.8 or previous version, please read
+@ref overview_unicode for the details about how the API changed in 3.0 as a lot
+of the information which was correct before doesn't apply any longer.
+
+For example, the notorious (due to the confusion they created) macros @c wxT()
+and @c _T() are not needed at all any longer. Basically, you can remove them
+from any code which used them. On the other hand, there is no particular harm
+in leaving them either as the code will still compile and work correctly --
+you only need to remove them if you think that your code looks tidier without
+them. You also don't need to use @c wxChar any longer but can directly use the
+standard @c wchar_t type even if, again, @c wxChar continues to work.
+
+The most serious backwards-incompatible change is related to the change of
+return type of wxString::c_str() method: it returns a special proxy object
+instead of a simple @c char* or @c wchar_t* now. Because of this, you cannot
+pass its result to any standard vararg functions such as @c printf() any more
+as described in @ref overview_unicode_compilation_errors. All wxWidgets
+functions, such as wxPrintf(), wxLogMessage() &c still work with it, but
+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
+A common example of such problem arises with @c std::fstream class constructor
+in Microsoft Visual C++ standard library implementation. In addition to a
+constructor from @c const @c char * which this class must have, it also
+provides a constructor taking a wide character file name. Because of this, code
+like the following
+@code
+    #include <fstream>
+
+    void MyFunc(const wxString& filename)
+    {
+        std::ifstream ifs(filename.c_str());
+        ...
+    }
+@endcode
+does not compile when using Microsoft Visual C++ and needs to be changed to use
+mb_str() (which will not work for file names containing Unicode characters,
+consider using wxWidgets classes and functions to work with such file names as
+they are not supported by standard C++ library).
+
+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
+simply call these functions but you need to change the signature of the derived
+class versions if you override them as otherwise they wouldn't be called any
+more. Again, the best way to ensure that this problem doesn't arise is to
+rebuild your code using a compiler which warns about function signature
+mismatch (you can use @c -Woverloaded-virtual g++ option).
+
+Finally, a few structure fields, notable @c wxCmdLineEntryDesc::shortName,
+@c longName and @c description fields have been changed to be of type @c const
+@c char* instead of @c const @c wxChar* so you will need to remove @c wxT() or
+@c _T() if you used it with their initializers.
+
+@section overview_changes_other Miscellaneous Other Changes
+
+- Default location of wxFileConfig files has changed under Windows, you will
+  need to update your code if you access these files directly.
+
+- wxWindow::IsEnabled() now returns false if a window parent (and not
+  necessarily the window itself) is disabled, new function IsThisEnabled()
+  with the same behaviour as old IsEnabled() was added.
+
+- Generating wxNavigationKeyEvent events doesn't work any more under wxGTK (and
+  other platforms in the future), use wxWindow::Navigate() or NavigateIn()
+  instead.
+
+- Sizers distribute only the extra space between the stretchable items
+  according to their proportions and not all available space. We believe the
+  new behaviour corresponds better to user expectations but if you did rely
+  on the old behaviour you will have to update your code to set the minimal
+  sizes of the sizer items to be in the same proportion as the items
+  proportions to return to the old behaviour.
+
+- wxWindow::Freeze/Thaw() are not virtual any more, if you overrode them in
+  your code you need to override DoFreeze/Thaw() instead now.
+
+- wxCalendarCtrl has native implementation in wxGTK, but it has less features
+  than the generic one. The native implementation is used by default, but you
+  can still use wxGenericCalendarCtrl instead of wxCalendarCtrl in your code if
+  you need the extra features.
+
+- wxDocument::FileHistoryLoad() and wxFileHistory::Load() now take const
+  reference to wxConfigBase argument and not just a reference, please update
+  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.
+
+- Signature of wxDataViewCustomRenderer::StartDrag() virtual method changed.
+  You will need to change it in your derived renderer class too if you override
+  it.
+
+- wxDataViewCustomRenderer::Activate() and
+  wxDataViewCustomRenderer::LeftClick() were replaced with the new
+  wxDataViewCustomRenderer::ActivateCell() method. You will need to change it
+  in your derived renderer class accordingly.
+
+*/
+