docs for Change/GetMode(s) (patch 966312)

[wxWidgets.git] / docs / changes.txt

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

INCOMPATIBLE CHANGES SINCE 2.4.x
================================

    Please take a few minutes to read the following list, especially
    paying attention to the most important changes which are marked
    with '!' in the first column.

    Also please note that you should ensure that WXWIN_COMPATIBILITY_2_4
    is defined to 1 if you wish to retain maximal compatibility with 2.4
    series.

! windows are no longer fully repainted when resized, use new style
  wxFULL_REPAINT_ON_RESIZE to force this (wxNO_FULL_REPAINT_ON_RESIZE still
  exists but doesn't do anything any more, this behaviour is default now)

! wxWindow::m_font and m_backgroundColour/m_foregroundColour are no longer
  always set, use GetFont(), GetBack/ForegroundColour() to access
  them, and they will be dynamically determined if necessary.


! The Sizers have had some fundamental internal changes in the 2.5.2
  and 2.5.3 releases intended to make them do more of the "Right
  Thing" but also be as backwards compatible as possible.  First a bit
  about how things used to work:

    * The size that a window had when Add()ed to the sizer was assumed
      to be its minimal size, and that size would always be used by
      default when calculating layout size and positions, and the
      sizer itself would keep track of that minimal size.

    * If the window item was Add()ed with the wxADJUST_MINSIZE flag
      then when layout was calculated the item's GetBestSize would be
      used to reset the minimal size that the sizer used.

  The main thrust of the new Sizer changes was to make behaviour like
  wxADJUST_MINSIZE be the default, and also to push the tracking of
  the minimal size to the window itself (since it knows its own needs)
  instead of having the sizer take care of it.  Consequently these
  changes were made:

    * The wxFIXED_MINSIZE flag was added to allow for the old
      behaviour.  When this flag is used the size a window has when
      Add()ed to the sizer will be treated as its minimal size and it
      will not be readjusted on each layout.

    * The min size stored in wxWindow and settable with SetSizeHints or
      SetMinSize will by default be used by the sizer (if it was set)
      as the minimal size of the sizer item.  If the minsize was not
      set (or was only partially set) then the window's best size is
      fetched and it is used instead of (or blended with) the minsize.
      wxWindow:GetBestFittingSize was added to facilitate getting the
      size to be used by the sizers.

    * The best size of a window is cached so it doesn't need to
      recaculated on every layout.  wxWindow::InvalidateBestSize was
      added and should be called (usually just internally in control
      methods) whenever something is done that would make the best
      size change.

    * All wxControls were changed to set the minsize to what is passed
      to the constructor or Create method, and also to set the real
      size of the control to the blending of the minsize and bestsize.
      wxWindow::SetBestFittingSize was added to help with this,
      although most controls don't need to call it directly because it
      is called indirectly via the SetInitialSize called in the base
      classes.

  At this time, the only situation known not to work the same as
  before is the following:

	 win = new SomeWidget(parent);
	 win->SetSize(SomeNonDefaultSize);
	 sizer->Add(win);

  In this case the old code would have used the new size as the
  minimum, but now the sizer will use the default size as the minimum
  rather than the size set later.  It is an easy fix though, just move
  the specification of the size to the constructor (assuming that
  SomeWidget will set its minsize there like the rest of the controls
  do) or call SetMinSize instead of SetSize.

  In order to fit well with this new scheme of things, all wxControls
  or custom controls should do the following things.  (Depending on
  how they are used you may also want to do the same thing for
  non-control custom windows.)

    * Either override or inherit a meaningful DoGetBestSize method
      that calculates whatever size is "best" for the control.  Once
      that size is calculated then there should normally be a call to
      CacheBestSize to save it for later use, unless for some reason
      you want the best size to be recalculated on every layout.

    * Any method that changes the attributes of the control such that
      the best size will change should call InvalidateBestSize so it
      will be recalculated the next time it is needed.

    * The control's constructor and/or Create method should ensure
      that the minsize is set to the size passed in, and that the
      control is sized to a blending of the min size and best size.
      This can be done by calling SetBestFittingSize.



- no initialization/cleanup can be done in wxApp/~wxApp because they are
  now called much earlier/later than before; please move any exiting code
  from there to wxApp::OnInit()/OnExit()
- also, OnExit() is not called if OnInit() fails
- finally the program exit code is OnRun() return value, not OnExit() one
- wxTheApp can't be assigned to any longer, use wxApp::SetInstance() instead
- wxFileType::GetIcon() returns wxIconLocation, not wxIcon
- wxColourDatabase is not a wxList any more, use AddColour to add new colours
- wxWindow::Clear() is now called ClearBackground()
- pointer returned by wxFont::GetNativeFontInfo() must not be deleted now
- wxMouseEvent::Moving() doesn't return true if mouse is being dragged any more
- (most) controls now inherit parents colours by default, override
  ShouldInheritColours() to return false if you don't want this to happen
- wxApp::SendIdleEvent() now takes 2 arguments
- wxTabView::GetLayers() changed return type from wxList& to wxTabLayerList&
  (when WXWIN_COMPATIBILITY_2_4 == 0)
- wxID_SEPARATOR (id used for the menu separators) value changed from -1 to -2
- wxGetNumberFromUser() is now in separate wx/numdlg.h, not wx/textdlg.h
- wxChoice and wxCombobox now handle their size in the same way as in all the
  other ports under MSW, new code is actually correct but different from weird
  stuff they were doing before so the behaviour of your programs might change
- wxTaskBarIcon objects must now be destroyed before the application can exit.
  Previously, the application terminated if there were no top level windows;
  now it terminates if there are no top level windows or taskbar icons left.
- wxZlibInputStream is not by default compatible with the output of the
  2.4.x version of wxZlibOutputStream. However, there is a compatibilty mode,
  switched on by passing wxZLIB_24COMPATIBLE to the constructor.
- when WXWIN_COMPATIBILITY_2_4 == 0 wxHashTable uses a new implementation
  not using wxList keyed interface (the same used when wxUSE_STL == 1),
  the only incompatibility being that Next() returns a wxHashTable::Node*
  instead of a wxNode*.
- non-const wxDC methods GetBackground(), GetBrush(), GetFont() and GetPen()
  as well as wxWindow methods GetFont() and GetCursor() don't exist any more,
  please fix your code -- it never worked correctly anyhow if you modified the
  objects returned by these methods so you should simply switch to using const
  methods.
- wxWindow::GetFont() now returns wxFont object instead of reference
- EVT_XXX macros are now type-safe; code that uses wrong type for event
  handler's argument will no longer compile.
- Identical functionality of wxFileDialog::ParseWildcard,
  wxGenericDirCtrl::ParseFilter, Motif and MSW parsing native dialogs
  is now accessible in ::wxParseCommonDialogsFilter
- wxNotebookSizer and wxBookCtrlSizer are now deprecated -- the are no longer
  needed, you can treat wxNotebook as any other control and put it directly
  into the sizer that was wxNotebookSizer's parent sizer in old code.



DEPRECATED METHODS SINCE 2.4.x
==============================

Deprecated methods may still be used but will disappear in future wxWidgets
versions, please update your code to not use them.

- wxDocManager::GetNoHistoryFiles() renamed to GetHistoryFilesCount()
- wxSizer::Remove(wxWindow *), use Detach() instead [it is more clear]
- wxSizer::Set/GetOption(): use Set/GetProportion() instead
- wxKeyEvent::KeyCode(): use GetKeyCode instead
- wxList::Number, First, Last, Nth: use GetCount, GetFirst/Last, Item instead
- wxNode::Next, Previous, Data: use GetNext, GetPrevious, GetData instead
- wxListBase::operator wxList&(): use typesafe lists instead
- wxTheFontMapper: use wxFontMapper::Get() instead
- wxStringHashTable: use wxHashMap instead
- wxHashTableLong: use wxHashMap instead
- wxArrayString::GetStringArray: use wxCArrayString or alternative wxWidgets
                                 methods taking wxArrayString
- wxArrayString::Remove(index, count): use RemoveAt instead
- wxTreeItemId conversion to long is deprecated and shouldn't be used
- wxTreeCtrl::GetFirst/NextChild() 2nd argument now has type wxTreeItemIdValue
  and not long, please change declarations of "cookie"s in your code
  accordingly -- otherwise your code won't work on 64 bit platforms
- [MSW only] wxWindow::GetUseCtl3D(), GetTransparentBackground() and
             SetTransparent() as well as wxNO_3D and wxUSER_COLOURS styles
- wxList keyed interface: use wxHashMap instead
- wxColourDatabase::FindColour(): use Find() instead (NB: different ret type)
- wxHashTable::Next: use wxHashTable::Node* or
                     wxHashTable::compatibility_iterator to store the return
                     value
- wxWave class; use wxSound instead
- The wxHIDE_READONLY flag for wxFileDialog was not implemented
  and has now been removed
- wxTaskBarIcon::OnXXX() virtual methods: use events instead


OTHER CHANGES
=============

2.5.3
-----

All:

- number of fixes to wxPluginManager (Rick Brice, Hans Van Leemputten)
- fixed memory leak in wxURL when using a proxy (Steven Van Ingelgem)
- fixed bug in wxDateTime::Set(jdn) when DST was in effect
- fixed fatal bug in wxString when wxUSE_STL==1 (Kurt Granroth)
- support msgids in charsets other than C and languages other than English
  (based on patch by Stefan Kowski)
- added wxMicroSleep() and wxMilliSleep() replacing deprecated wxUsleep()

All (GUI):

- added wxWindow::MoveBefore/AfterInTabOrder() to change tab navigation order
- added wxTaskBarIcon::CreatePopupMenu which is now recommended way
  of showing popup menu; calling wxTaskBarIcon::PopupMenu directly
  is discouraged
- added ..._CMD_...(id) variants for wxGrid event table entry macros
- added wxWindow::Navigate for programmatic navigation to the next control.
- wxTextCtrl::OnChar now inserts a tab character if wxTE_PROCESS_TAB is set
- added wxKeyEvent::GetUnicodeKey()
- added wxKeyEvent::CmdDown() and wxMouseEvent::CmdDown()

Unix:

- wxTaskBarIcon now supports freedesktop.org System Tray protocol
- security fixes to wxSingleInstanceChecker
- wx-config script was modified to allow choosing from multiple installed
  builds of wxWidgets

wxGTK:

- wxGTK uses GTK+ 2.x by default now, you have to pass --disable-gtk2 to
  configure if you want to use GTK+ 1.2
- fixed many rendering artifacts and wrong colours with lots of GTK+ themes
- implemented wxColourDialog as native dialog
- implemented wxTextCtrl::HitTest() (GTK+ >= 2)
- implemented wxTextCtrl::ScrollLines() and ScrollPages for GTK+ 2.x
- wxTreeCtrl::GetCount() counts root as well now (compatible with MSW)
- added support for wxCHK_3STATE style (GTK2 only)
- implemented text underlining under GTK2
- implemented wxFRAME_NO_TASKBAR style (GTK >= 2.2)
- implemented support for wxSYS_DCLICK_?, wxSYS_DRAG_? and wxSYS_CURSOR_?
  in wxSystemSettings::GetMetric (Mart Raudsepp)
- implemented wxTopLevel::IsMaximized() for GTK+2 and WMs that implement
  freedesktop.org's wm-spec (Mart Raudsepp)
- wxEVT_CONTEXT_MENU is now generated for right mouse press, not release

wxMotif:

- added support for wxCHK_3STATE style (3 state checkbox)

wxMSW:

- fixed UNC paths handling in wxFileSystem (Daniel Nash)
- set wxKeyEvent::m_uniChar in Unicode build

wxWinCE:

- added automatized but customizable handling of native SmartPhone menus

wxHTML:

- added support for nested index entries and index entries pointing to more
  than one page to wxHtmlHelpController


2.5.2
-----

All:

- Hindi translation added (Dhananjaya Sharma)
- Brazilian Portuguese translation added (E. A. Tacao)
- wxDynamicCast() now uses static_cast<wxObject *> internally and so using it
  with anything not deriving from wxObject will fail at compile time (instead
  of run-time) now
- when wxUSE_STL == 1 and STL provides quasi-standard hash_map/hash_set,
  wxHashMap/wxHashSet are just typedefs for them. This makes impossible
  to forward declare these classes.

All (GUI):

- wxHtmlWindow now delays image scaling until rendering,
  resulting in much better display of scaled images
- Added UpdateSize to wxSplitterWindow to allow layout while hidden
- implemented Freeze/Thaw() for wxGenericTreeCtrl (Kevin Hock)
- support for KOI8-U encoding added (Yuriy Tkachenko)
- The old wxADJUST_MINSIZE behaviour is now the default behaviour for
  sizer items that are windows.  This means that GetAdjustedBestSize
  will now be called by default to determine the minimum size that a
  window in a sizer should have.  If you want to still use the initial
  size (and not the BestSize) then use the wxFIXED_MINSIZE flag.  When
  windows are added to a sizer their initial size is made the window's
  min size using SetSizeHints, and calls to wxSizer::SetItemMinSize
  are also forwarded to SetSizeHints for window items.
- added wxRegEx::GetMatchCount()
- it is now possible to display images in wxHtmlListBox

wxMSW:

- wxWindow::Freeze()/Thaw() can now be nested
- Added wxSP_NO_XP_THEME style to wxSplitterWindow to switch off
  XP theming (some applications look bad without 3D borders)
- wxMenuBar::GetLabelTop() doesn't include '&'s in the label any more
- wxRegConf couldn't read global settings without admin privileges and didn't
  even try to do it by default -- now it does
- wxTaskBarIcon must be explicitly destroyed now, otherwise the application
  won't exit even though there are no top level windows
- wxFileName::GetModificationTime() works with opened files too now
- wxDC::GetClippingBox() now works even for clipping regions created by Windows
- fixed wxFileDataObject in Unicode build (Alex D)
- subdindented paragraphs support (Tim Kosse)

wxGTK:

- added support for wxTE_RIGHT and wxTE_CENTRE styles under GTK2 (Mart Raudsepp)

wxMotif:

- removed wxMenuItem::DeleteSubMenu()
- wxButtons use Motif default size, which is smaller than it used to be
  and closer to wxMSW/wxGTK look. This can be disabled by setting
  motif.largebuttons system option to 1 (see wxSystemOptions).

wxUniv/X11:

- implemented DrawRoundedRectangle() (clawghoul)

wxHTML:

- improved tables and lists layout algorithms (Tim Kosse)
- <div> handling fix (Xavier Nodet)

Unix:

- fixed priorities of mailcap entries (David Hart)
- added "wx-config --libs=std,<extra>" syntax (i.e. support for "std")

wxODBC:

- Full Unicode support is now available
- BLOB support is working


2.5.1
-----

All: