update date for 2.9.0 release; set the title to "Reference manual"

[wxWidgets.git] / docs / changes.txt

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

INCOMPATIBLE CHANGES SINCE 2.8.x
================================


        Notice that these changes are described in more details in
        the "Changes Since wxWidgets 2.8" section of the manual,
        please read it if the explanation here is too cryptic.


Unicode-related changes
-----------------------

The biggest changes in wxWidgets 3.0 are the changes due to the merge of the
old ANSI and Unicode build modes in a single build. See the Unicode overview
in the manual for more details but here are the most important incompatible
changes:

- Many wxWidgets functions taking "const wxChar *" have been changed to take
  either "const wxString&" (so that they accept both Unicode and ANSI strings;
  the argument can't be NULL anymore in this case) or "const char *" (if the
  strings are always ANSI; may still be NULL). This change is normally
  backwards compatible except:

  a) Virtual functions: derived classes versions must be modified to take
     "const wxString&" as well to make sure that they continue to override the
     base class version.

  b) Passing NULL as argument: as NULL can't be unambiguously converted to
     wxString, in many cases code using it won't compile any more and NULL
     should be replaced with an empty string.


- Some structure fields which used to be of type "const wxChar *" (such as
  wxCmdLineEntryDesc::shortName, longName and description fields) are now of
  type "const char *", you need to remove wxT() or _T() around the values used
  to initialize them (which should normally always be ASCII).

- wxIPC classes didn't work correctly in Unicode build before, this was fixed
  but at a price of breaking backwards compatibility: many methods which used
  to work with "wxChar *" before use "void *" now (some int parameters were
  also changed to size_t). While wxIPC_TEXT can still be used to transfer 7
  bit text, the new wxIPC_UTF8TEXT format is used for transferring wxStrings.
  Also notice that connection classes should change the parameter types of
  their overridden OnExecute() or override a more convenient OnExec() instead.


wxODBC and contrib libraries removal
------------------------------------

wxODBC library was unmaintained since several years and we couldn't continue
supporting it any longer so it was removed. Please use any of the other open
source ODBC libraries in the future projects.

Also the "applet", "deprecated", "fl", "mmedia" and "plot" contrib libraries
were removed as they were unmaintained and broken since several years.
The "gizmos", "ogl", "net" and "foldbar" contribs have been moved to
wxCode (see http://wxcode.sourceforge.net/complist.php); they are now
open for futher development by volunteers.

The "stc" and "svg" contribs instead have been moved respectively into a new
"official" library stc and in the core lib.


Changes in behaviour not resulting in compilation errors, please read this!
---------------------------------------------------------------------------

- 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.

- Under MSW wxExecute() arguments are now always properly quoted, as under
  Unix, and so shouldn't contain quotes unless they are part of the argument.

- wxDocument::OnNewDocument() doesn't call OnCloseDocument() any more.

- If you use wxScrolledWindow::SetTargetWindow() you must implement its
  GetSizeAvailableForScrollTarget() method, please see its documentation for
  more details.

- Processing of pending events now requires a running event loop.
  Thus initialization code (e.g. showing a dialog) previously done in wxApp::OnRun()
  or equivalent function should now be done into wxApp::OnEventLoopEnter().
  See wxApp::OnEventLoopEnter() and wxApp::OnEventLoopExit() docs for more info.


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

- WXWIN_COMPATIBILITY_2_4 doesn't exist any more, please update your code if
  you still relied on features deprecated since version 2.4

- wxDC classes hierarchy has changed, if you derived any classes from wxDC you
  need to review them as wxDC doesn't have any virtual methods any longer and
  uses delegation instead of inheritance to present different behaviours.

- wxWindow::ProcessEvent() (and other wxEvtHandler methods inherited by wxWindow)
  has been made protected to prevent wrongly using it instead of correct
  GetEventHandler()->ProcessEvent().
  New ProcessWindowEvent() was added for convenience.

- Return type of wxString::operator[] and wxString::iterator::operator* is no
  longer wxChar (i.e. char or wchar_t), but wxUniChar. This is not a problem
  in vast majority of cases because of conversion operators, but it can break
  code that depends on the result being wxChar.

- The value returned by wxString::c_str() cannot be casted to non-const char*
  or wchar_t* anymore. The solution is to use newly added wxString methods
  char_str() (which returns a buffer convertible to char*) or wchar_str()
  (which returns a buffer convertible to wchar_t*). These methods are
  available in wxWidgets 2.8 series beginning with 2.8.4 as well.

- The value returned by wxString::operator[] or wxString::iterator cannot be
  used in switch statements anymore, because it's a class instance. Code like
  this won't compile:
     switch (str[i]) { ... }
  and has to be replaced with this:
     switch (str[i].GetValue()) { ... }

- Return type of wxString::c_str() is now a helper wxCStrData struct and not
  const wxChar*. wxCStrData is implicitly convertible to both "const char *"
  and "const wchar_t *", so this only presents a problem if the compiler cannot
  apply the conversion. This can happen in 2 cases:

  + There is an ambiguity because the function being called is overloaded to
    take both "const char *" and "const wchar_t *" as the compiler can't choose
    between them. In this case you may use s.wx_str() to call the function
    matching the current build (Unicode or not) or s.mb_str() or s.wc_str() to
    explicitly select narrow or wide version of it.

    Notice that such functions are normally not very common but unfortunately
    Microsoft decided to extend their STL with standard-incompatible overloads
    of some functions accepting "const wchar_t *" so you may need to replace
    some occurrences of c_str() with wx_str() when using MSVC 8 or later.

  + Some compilers, notably Borland C++ and DigitalMars, don't correctly
    convert operator?: operands to the same type and fail with compilation
    error instead. This can be worked around by explicitly casting to const
    wxChar*: wxLogError(_("error: %s"), !err.empty() ? (const wxChar*)err.c_str() : "")

- wxCtime() and wxAsctime() return char*; this is incompatible with Unicode
  build in wxWidgets 2.8 that returned wchar_t*.

- DigitalMars compiler has a bug that prevents it from using
  wxUniChar::operator bool in conditions and it erroneously reports type
  conversion ambiguity in expressions such as this:
     for ( wxString::const_iterator p = s.begin(); *p; ++p )
  This can be worked around by explicitly casting to bool:
     for ( wxString::const_iterator p = s.begin(); (bool)*p; ++p )

- Virtual wxHtmlParser::AddText() takes wxString, not wxChar*, argument now.

- Functions that took wxChar* arguments that could by NULL in wxWidgets 2.8
  are deprecated and passing NULL to them won't compile anymore, wxEmptyString
  must be used instead.

- wxTmemxxx() functions take either wxChar* or char*, not void*: use memxxx()
  with void pointers.

- Removed insecure wxGets() and wxTmpnam() functions.

- Removed global GetLine() function from wx/protocol/protocol.h, use
  wxProtocol::ReadLine() instead.

- wxVariant no longer derives from wxObject. wxVariantData also no longer
  derives from wxObject; instead of using wxDynamicCast with wxVariantData you
  can use the macro wxDynamicCastVariantData with the same arguments.

- wxWindow::Next/PrevControlId() don't exist any more as they couldn't be
  implemented correctly any longer because automatically generated ids are not
  necessarily allocated consecutively now. Use GetChildren() to find the
  next/previous control sibling instead.

- Calling wxConfig::Write() with an enum value will fail to compile because
  wxConfig now tries to convert all unknown types to wxString automatically.
  The simplest solution is to cast the enum value to int.

- Several wxImage methods which previously had "long bitmaptype" parameters
  have been changed to accept "wxBitmapType bitmaptype", please use enum
  wxBitmapType in your code.

- wxGridCellEditor::EndEdit() signature has changed and it was split in two
  functions, one still called EndEdit() and ApplyEdit(). See the documentation
  of the new functions for more details about how grid editors should be
  written now.

- wxEVT_GRID_CELL_CHANGE event renamed to wxEVT_GRID_CELL_CHANGED and shouldn't
  be vetoed any more, use the new wxEVT_GRID_CELL_CHANGING event to do it.

- Now wxWidgets at startup in debug builds checks if all wxEvent-derived classes
  correctly implement the Clone() function, logging a warning if they don't.
  A correct implementation for MyCustomEventClass::Clone() is simply:
    virtual wxEvent *Clone() const  { return new MyCustomEventClass(*this); }

- Global wxPendingEvents and wxPendingEventsLocker objects were removed.
  You may use wxEventLoopBase::SuspendProcessingOfPendingEvents instead of
  locking wxPendingEventsLocker now.


Deprecated methods and their replacements
-----------------------------------------

- wxCreateGreyedImage() deprecated, use wxImage::ConvertToGreyscale() instead.
- wxString::GetWriteBuf() and UngetWriteBuf() deprecated, using wxStringBuffer
  or wxStringBufferLength instead.
- wxDIRCTRL_SHOW_FILTERS style is deprecated, filters are alwsys shown if
  specified so this style should simply be removed
- wxDocManager::MakeDefaultName() replaced by MakeNewDocumentName() and
  wxDocument::GetPrintableName() with GetUserReadableName() which are simpler
  to use
- wxXmlProperty class was renamed to wxXmlAttribute in order to use standard
  terminology. Corresponding wxXmlNode methods were renamed to use
  "Attribute" instead of "Property" or "Prop" in their names.
- wxConnection::OnExecute() is not formally deprecated yet but new code should
  use simpler OnExec() version which is called with wxString argument
- Various wxMenuItem methods were deprecated in favour of more consisently
  named new versions:
    . GetLabel() is now GetItemLabelText()
    . GetText() is not GetItemLabel()
    . GetLabelFromText() is now GetLabelText()
    . SetText() is now SetItemLabel()
- wxBrush's, wxPen's SetStyle() and GetStyle() as well as the wxBrush/wxPen
  ctor now take respectively a wxBrushStyle and a wxPenStyle value instead of a
  plain "int style"; use the new wxBrush/wxPen style names (wxBRUSHSTYLE_XXX
  and wxPENSTYLE_XXX) instead of the old deprecated wxXXX styles.
- EVT_GRID_CELL_CHANGE was deprecated, use EVT_GRID_CELL_CHANGED instead if you
  don't veto the event in its handler and EVT_GRID_CELL_CHANGING if you do.
- EVT_CALENDAR_DAY event has been deprecated, use EVT_CALENDAR_SEL_CHANGED.
- EVT_CALENDAR_MONTH and EVT_CALENDAR_YEAR events are deprecated,
  use EVT_CALENDAR_PAGE_CHANGED which replaces both of them.
- wxCalendarCtrl::EnableYearChange() and wxCAL_NO_YEAR_CHANGE are deprecated.
  There is no replacement for this functionality, it is being dropped as it is
  not available in native wxCalendarCtrl implementations.
- wxDC::SetClippingRegion(const wxRegion&) overload is deprecated as it used
  different convention from the other SetClippingRegion() overloads: wxRegion
  passed to it was interpreted in physical, not logical, coordinates. Replace
  it with SetDeviceClippingRegion() if this was the correct thing to do in your
  code.
- wxTE_AUTO_SCROLL style is deprecated as it's always on by default anyhow.
- wxThreadHelper::Create() has been renamed to CreateThread which has a better
  name for a mix-in class, and allows setting the thread type.
- wxDos2UnixFilename, wxUnix2DosFilename, wxStripExtension, wxGetTempFileName,
  wxExpandPath, wxContractPath, wxRealPath, wxCopyAbsolutePath, wxSplitPath
  were deprecated in favour of wxFileName methods. See docs for more info.
- wxEvtHandler::TryValidator/Parent() are deprecated, override the new and
  documented TryBefore/After() methods if you used to override these ones.
- wxGetMultipleChoices() is deprecated, use wxGetSelectedChoices() which has
  the same signature but returns -1 and not 0 if the dialog was cancelled.

Major new features in this release
----------------------------------

- wxWidgets is now always built with Unicode support but provides the same
  simple (i.e. "char *"-tolerant) API as was available in ANSI build in the
  past.

- wxWidgets may now use either wchar_t (UTF-16/32) or UTF-8 internally,
  depending on what is optimal for the target platform.

- New propgrid library containing wxPropertyGrid and related classes.

- Many enhancements to wxDataViewCtrl.

- Event loops, timers and sockets can now be used in wxBase, without GUI.

- Events can now be connected to any functor, not necessarily a method of
  wxEvtHandler-derived class. The compile-time safety was also improved.

- Documentation for wxWidgets has been converted from LaTex to C++ headers
  with Doxygen comments and significantly improved in the process (screenshots
  of various controls were added, more identifiers are now linked to their
  definition &c). Any reports about inaccuracies in the documentation are
  welcome (and due to using the simple Doxygen syntax it is now easier than
  ever to submit patches correcting them! :-)

- Support for persistent objects automatically saving and restoring their state
  was added.


2.9.0
-----

All:

- Added (experimental) IPv6 support to wxSocket (Arcen).
- Cleaned up wxURI and made it Unicode-friendly.
- Add support for wxExecute(wxEXEC_ASYNC) in wxBase (Lukasz Michalski).
- Added wxXLocale class and xlocale-like functions using it.
- Allow loading message catalogs from wxFileSystem (Axel Gembe).
- Added wxMessageQueue class for inter-thread communications
- Use UTF-8 for Unicode data in wxIPC classes (Anders Larsen)
- Added support for user-defined types to wxConfig (Marcin Wojdyr).
- Added numeric options support to wxCmdLineParser (crjjrc)
- Added wxJoin() and wxSplit() functions (Francesco Montorsi).
- Added wxDateTime::FormatISOCombined() and ParseISODate/Time/Combined()
- Added wxMutex::LockTimeout() (Aleksandr Napylov).
- Added wxMemoryInputStream(wxInputStream&) ctor (Stas Sergeev).
- Implemented wxMemoryInputStream::CanRead().
- Implemented wxMemoryFSHandler::FindFirst/Next().
- Added wxEventLoop::DispatchTimeout().
- Added wxZlibStream::SetDictionary() (Axel Gembe).
- Added wxEXEC_BLOCK flag (Hank Schultz).
- Add support for wxStream-derived classes to wxRTTI (Stas Sergeev).
- Added wxStreamBuffer::Truncate() (Stas Sergeev).
- Allow using  wxEventLoop in console applications (Lukasz Michalski).
- Added functions for Base64 en/decoding (Charles Reimers).
- Added support for binary data to wxConfig (Charles Reimers).
- Added functions for atomically inc/decrementing integers (Armel Asselin).
- wxLogInterposer has been added to replace wxLogPassThrough and new
  wxLogInterposerTemp was added.
- Added support for broadcasting to UDP sockets (Andrew Vincent).
- Documentation now includes the wx library in which each class is defined.
- wxrc --gettext now generates references to source .xrc files (Heikki
  Linnakangas).
- wxVariant::Unshare allows exclusive allocation of data that must be shared,
  if the wxVariantData::Clone function is implemented.
- Added wxWeakRef<T>, wxScopedPtr<T>, wxScopedArray<T>, wxSharedPtr<T> templates
  and renamed old wx/ptr_{scpd,shrd}.h headers to wx/scoped{ptr,array}.h and
  wx/sharedptr.h (but old headers are still provided for compatibility).
- Added wxVector<T> class templates
- Added wxON_BLOCK_EXIT_SET() and wxON_BLOCK_EXIT_NULL() to wx/scopeguard.h.
- Added wxEvtHandler::QueueEvent() replacing AddPendingEvent() and
  wxQueueEvent() replacing wxPostEvent().
- wxString now uses std::[w]string internally by default, meaning that it is
  now thread-safe if the standard library provided with your compiler is.
- Added wxCmdLineParser::AddUsageText() (Marcin 'Malcom' Malich).
- Fix reading/writing UTF-7-encoded text streams.
- Corrected bug in wxTimeSpan::IsShorterThan() for equal time spans.
- Use std::unordered_{map,set} for wxHashMap/Set if available (Jan van Dijk).
- Added wxString::Capitalize() and MakeCapitalized().
- Added wxArray::swap().
- Added wxSHUTDOWN_LOGOFF and wxSHUTDOWN_FORCE wxShutdown() flags (troelsk).
- Added wxSocket::ShutdownOutput().
- Handle exceptions thrown from overridden wxView::OnCreate() gracefully.
- Added wxPATH_RMDIR_FULL/RECURSIVE wxFileName::Rmdir() flags (Marcin Malich).
- Added wxStandardPaths::GetAppDocumentsDir().
- Added wx-prefixed versions of DECLARE_NO_{COPY,ASSIGN}_CLASS macros.
- Added wxFileName::ReplaceEnvVariable and wxFileName::ReplaceHomeDir.
- Added wxProtocol::SetDefaultTimeout(); the default timeout for both wxHTTP and wxFTP
  protocols is 60 seconds.
- Added wxStrnlen() for safe computation of string length.
- Added wxImage::Clear() (troelsk).
- Added wxLog::Log().
- Added wxProtocolLog and use it in wxFTP.
- Added wxXmlResource::GetResourceNode().
- Optimize wxString::Replace() to use an O(N) algorithm (Kuang-che Wu).
- Added support of %l format specifier to wxDateTime::ParseFormat().
- wxImage handlers can now support multiple extensions (Ivan Krestinin).

All (Unix):

- Added wx-config --optional-libs command line option (John Labenski).
- Noticeably (by a factor of ~150) improve wxIPC classes performance.
- Configure options --with-opengl and --enable-mediactrl now default to "auto":
  if OpenGL and GStreamer libraries are available the "gl" and "media" wx libraries
  are automatically built.

All (GUI):

- Added wxDataViewCtrl class and helper classes.
- Integrated wxPropertyGrid in wxWidgets itself (Jaakko Salli).
- Provide native implementation of wxCalendarCtrl under wxMSW and wxGTK.
- Added wxHeaderCtrl and allow using it in wxGrid.
- Added wxRearrangeList, wxRearrangeCtrl and wxRearrangeDialog.
- Added {wxTextCtrl,wxComboBox}::AutoComplete() and AutoCompleteFileNames().
- Added wxH[V]ScrolledWindow (Brad Anderson, Bryan Petty).
- Added wxNotificationMessage class for non-intrusive notifications.
- Added wxWindow::Show/HideWithEffect().
- Added wxWrapSizer (Arne Steinarson).
- Added wxSpinCtrlDouble (John Labenski).
- Support custom labels in wxMessageDialog (Gareth Simpson for wxMac version).
- Added wxScrolledWindow::ShowScrollbars().
- Also added wxCANCEL_DEFAULT to wxMessageDialog.
- Allow copying text in the log dialogs.
- Added multisample (anti-aliasing) support to wxGLCanvas (Olivier Playez).
- Added wxEVT_COMMAND_COMBOBOX_DROPDOWN/CLOSEUP events (Igor Korot).