wxWidgets/docs/changes.txt

-------------------------------------------------------------------------------
                             wxWidgets Change Log
-------------------------------------------------------------------------------

Note: This file contains the list of changes since wxWidgets 3.2, please see
      docs/changes_32.txt for the earlier changes.

INCOMPATIBLE CHANGES SINCE 3.2.x:
=================================

Changes in behaviour not resulting in compilation errors
--------------------------------------------------------

- wxMSW now uses double buffering by default, meaning that updating the
  windows using wxClientDC doesn't work any longer, which is consistent with
  the behaviour of wxGTK with Wayland backend and of wxOSX, but not with the
  traditional historic behaviour of wxMSW (or wxGTK/X11). You may call
  MSWDisableComposited() to restore the previous behaviour, however it is
  strongly recommended to change your redrawing logic to avoid using wxClientDC
  instead, as the code using it still won't work with wxGTK/wxOSX.

  You may also choose to globally set the new msw.window.no-composited system
  option to disable the use of double buffering, but please consider doing it
  only as a last resort and/or temporary solution, as this _will_ result in
  flicker and won't be supported at all in the future wxWidgets versions.

- wxMSW doesn't support versions of Microsoft Windows before Windows 7. If you
  need Windows XP or Vista support, please use wxWidgets 3.2.

- Default exit code in case of fatal error is now consistently 255, including
  when using MSVC for which it was 127 previously. Use wxApp::SetErrorExitCode()
  and wxApp::SetFatalErrorExitCode() to change this to old value if needed.

- wxGLCanvas doesn't use multi-sampling by default any longer, please use
  wxGLAttributes::Samplers(1).SampleBuffers(4) explicitly if you need to keep
  using the same attributes that were previously used by default.

- Default location of file used by wxFileConfig under Unix has changed to
  XDG-compliant ~/.config/appname.conf instead of ~/.appname but note that
  any existing files at the old location will still continue to be used.
  See wxCONFIG_USE_XDG and wxCONFIG_USE_HOME for how to customize this
  behaviour. You may also find wxFileConfig::MigrateLocalFile() useful.

- Values of many colours in wxColourDatabase have been changed to use the
  values from the CSS standard. Use wxColourDatabase::UseScheme() to revert to
  using the traditional values if your application appearance depends on them.

- As first mentioned in 3.0 release notes, the value of wxTHREAD_WAIT_DEFAULT,
  used by wxThread::Delete() and Wait() by default, has changed from
  wxTHREAD_WAIT_YIELD to wxTHREAD_WAIT_BLOCK for safety and consistency.

- wxDocument::OnCloseDocument() was called twice in previous versions when
  closing the document from the menu. Now it is only called once and after
  destroying all the existing document views. If you overrode this function,
  please check that you don't rely on any views existing when it's called.

- wxGrid::FreezeTo() now asserts when passed invalid (out of range) number of
  rows or columns to freeze. But it also does freeze the requested rows/columns
  even if the grid is currently too small to show all of them or if there are
  no unfrozen rows/columns remaining.

- Calling wxImageList methods on an invalid wxImageList object now consistently
  results in assert failures instead of just failing silently. To avoid these
  asserts, make sure that wxImageList is created with a valid size before
  operating on it.

- wxTRANSPARENT_WINDOW doesn't do anything and shouldn't be used any more. If
  you ever used it under MSW (it never did anything in the other ports), you
  can turn on the native WS_EX_TRANSPARENT extended style if really needed.

- In wxMSW, size passed to wxTextDataObject::SetData() must include the size of
  the trailing NUL (in bytes, i.e. 2) now, for consistency with GetDataSize().
  Typically this function shouldn't be used directly as SetText() should be
  used instead, but if you do use it, you need to update your code to prevent
  the last character of the data from being chopped.

- Calling wxListCtrl::EditLabel() now asserts if the control doesn't have
  wxLC_EDIT_LABELS style: previously this silently didn't work in wxMSW.

- wxSystemAppearance::IsDark() now returns whether this application uses dark
  mode under MSW, use the new AreAppsDark() or IsSystemDark() to check if the
  other applications or the system are using dark mode.

- wxUILocale::IsSupported() now returns false for unavailable locales under
  Unix systems without trying to fall back on another locale using the same
  language in a different region, e.g. it doesn't use fr_FR if fr_BE is not
  available. If any locale using the given language is acceptable, the region
  must be left empty, e.g. just "fr" would use any available "fr_XX".

- Deprecated wxPGCellRenderer::DrawCaptionSelectionRect() overload is not
  called any longer by default, you need to explicitly enable 3.0 compatibility
  or change your code to override the newer overload, taking a wxWindow pointer.

- wxImageList size is now expressed in physical pixels, i.e. its size must be
  the same as the size of bitmaps added to it, in pixels. This is inconvenient
  but should be viewed as a hint not to use wxImageList (but wxBitmapBundle)
  in the applications supporting high DPI.

- wxWebRequest doesn't use persistent storage under Mac any longer, as this
  made is behaviour there incompatible with the other platforms. Please call
  wxWebRequest::EnablePersistentStorage() explicitly if you need it.

- In wxMSW, behaviour of wxBitmap::Create(size, dc) overload has changed to
  not scale the size by the content scale factor of the DC any longer, as the
  size here is expressed in physical pixels and not in DIPs.

- wxIMAGE_QUALITY_NEAREST has a different numeric value and is not the same
  as wxIMAGE_QUALITY_NORMAL any longer, see documentation for more details.

- wxTextCtrl::{Save,Load}File() will use RTF format when saving/loading files
  with .rtf extension, and not plain text any longer, by default for the
  platforms with RTF support. If you need to save/load plain text even for the
  files with the .rtf extension, specify wxTEXT_TYPE_PLAIN explicitly.

- wxClientDC and wxPaintDC now correctly offset their origin by wxFrame
  toolbar, if any. This is consistent with the behaviour of the other ports
  but may require removing any compensation for not doing this before that may
  be present in the application code.

- Calling wxTextCtrl::SetLabel() now consistently does nothing and asserts
  under all platforms instead of behaving as SetValue() under MSW and doing
  nothing elsewhere.

- The meaning of page index in wxAuiNotebook has changed if the pages have
  been reordered (see wxAUI_NB_TAB_MOVE) and now always refers to the page
  logical index, which is not affected by reordering. To get the position of
  the page on screen, which doesn't make sense without reference to the tab
  control containing it, use GetPagePosition() to retrieve both of them.

- wxListbook and wxChoicebook now interpret (but ignore) mnemonics in their
  page titles, just as the other wx*book classes already did. Double "&"
  in the page text if it should be interpreted as a literal "&".

- wxAUI_MGR_HINT_FADE is not included in default wxAuiManager style any longer,
  please add it explicitly if you really want to use it.

Changes in behaviour which may result in build errors
-----------------------------------------------------

- Symbols deprecated in 3.0 are still available in this version but disabled by
  default, you need to set WXWIN_COMPATIBILITY_3_0 to 1 to enable them. Symbols
  deprecated in 2.8 are not available any longer.

- Building with wxUSE_UNICODE=0 is not supported any longer.

- wxUSE_STD_CONTAINERS is now set to 1 by default, see "Container Classes"
  overview in the manual for the description of the changes this may require in
  the existing code. Alternatively, explicitly set wxUSE_STD_CONTAINERS=0 when
  compiling the library to preserve full compatibility with the old versions.

- wxUSE_STL option doesn't exist any longer, standard library is always used.
  However previously setting wxUSE_STL=1 enabled implicit conversion from
  wxString to std::[w]string which are not enabled by default now, please set
  wxUSE_STD_STRING_CONV_IN_WXSTRING=1 explicitly if you need them.

- wxMSW now requires linking with gdiplus.lib and msimg32.lib.
  This is done automatically in most cases, but if you use a static build of
  the library with a non-MSVC compiler such as MinGW and do not use wx-config,
  then you will need to add these libraries to your make or project files
  yourself.

- wxMotif and wxGTK1 ports have been removed, please use wxWidgets 3.2 if you
  still need them.

- Several private container classes that never made part of wxWidgets public
  API have been removed. If you used any of them (e.g. wxSimpleDataObjectList)
  in your code, please switch to using std::vector<> or std::list<> instead.
  Some other legacy "object array" classes (e.g. wxImageArray) still exist, but
  are now similar to std::vector<> containing the objects -- they remain mostly
  compatible with the previous wxWidgets versions, but now compare values, and
  not pointers, in their Index() member function.

- All operators (e.g. "==", "+", etc) on wx types are not defined in global
  scope any more, resulting in much better error messages but also preventing
  them from implicitly being used with types convertible to wx types. If you
  really need to use these operators with your own types, please use explicit
  conversions.

- Due to the possibility to construct wxString from std::string_view some
  previously valid code, such as "wxstr = {"Hello", 2}", is now ambiguous.
  Please use explicit class name, e.g. "wxstr = wxString{"Hello", 2}" to
  preserve the previous behaviour.

- Generic wxSearchCtrl doesn't provide methods that make sense only for
  multiline text controls any longer, for consistency with the other ports.

- wxOnAssert() overload taking wide character file name was removed. If you
  call it for any reason, please use one of the other overloads instead.

- 64-bit DLLs now use "x64" suffix in their names for all builds, not just
  the official ones and those using MSVS projects, but also when using
  makefile.vc or CMake, for consistency.

- Support for memory debugging that was previously disabled but could be
  activated by using wxUSE_MEMORY_TRACING, wxUSE_GLOBAL_MEMORY_OPERATORS etc
  options was completely removed. Please use address sanitizer or similar
  tools that are incomparably more useful for this than that legacy code.

- wxTEST_DIALOG() macro now must be followed by semicolon, whereas previously
  it was only supposed to, but it wasn't mandatory to use one after it.

- wxWindow::GetDefaultBorderForControl() is not virtual any longer and will
  be completely removed in the future. If you overrode this function, don't
  do it any longer. If you call it, replace it with wxBORDER_THEME constant.

- wxGTK wxDirButton::Create() doesn't have unused "wildcard" parameter any
  longer, please just remove it from your code if you used it.

- Several functions now take wxReadOnlyDC instead of wxDC as argument. While
  any code calling these functions keeps compiling and working, classes that
  override these functions must be updated to use the new argument type too.
  Simply replacing wxDC with wxReadOnlyDC should be sufficient.

- wxSizer::Detach() takes wxWindowBase pointer now instead of wxWindow.
  This only matters if you override this virtual function in your own classes
  deriving from wxSizer, please change the function in the derived class to
  take wxWindowBase pointer too in this case.


3.3.0: (released 2022-??-??)
----------------------------

NOTE: In addition to the note below, also incorporate (either by
      copy or by reference) all the changes in the 3.2 branch (i.e.
      everything in this file after 3.2.0 in that branch).

NOTE: This file is updated only before the release, please use

    $ git log --notes=changelog --format='%N' v3.2.0..|grep .

      to see all the change log entries since the last release.

      To update the notes, fetch them first:

    $ git fetch origin refs/notes/changelog:refs/notes/changelog

      then use the following command to update them locally

    $ git notes --ref=changelog add -m 'wxPort: description.'

      and finally push it to the server.

    $ git push origin refs/notes/changelog:refs/notes/changelog

      If this fails due to a conflict because you had forgotten to
      run git-fetch first, you can always reset your local notes
      (LOSING YOUR CHANGES TO THEM, so make sure to make a copy)

    $ git fetch origin refs/notes/changelog
    $ git update-ref refs/notes/changelog FETCH_HEAD

      and then redo "git-notes add" and git-push.