docs/latex/wx/tchanges.tex

   1 \section{Changes since 2.4.x}\label{changes}
   2
   3 Listed here are the depreciated and incompatible changes made to wxWidgets.
   4
   5 For other changes (such as additional features, bug fixes, etc.) see the changes.txt file located in the docs directory of your wxWidgets directory.
   6
   7
   8
   9 \subsection{Incompatible changes since 2.4.x}\label{incompatiblesince24}
  10
  11 \subsubsection{New window repainting behaviour}\label{newwindowrepainting}
  12
  13 Windows are no longer fully repainted when resized, use new style \windowstyle{wxFULL\_REPAINT\_ON\_RESIZE} to force this (\windowstyle{wxNO\_FULL\_REPAINT\_ON\_RESIZE} still exists but doesn't do anything any more, this behaviour is default now).
  14
  15
  16
  17 \subsubsection{Window class member changes}\label{windowclassmemberchanges}
  18
  19 wxWindow::m\_font and m\_backgroundColour/m\_foregroundColour are no longer always set, use \helpref{GetFont()}{wxwindowgetfont}, \helpref{GetBack}{wxwindowgetbackgroundcolour}/\helpref{ForegroundColour()}{wxwindowgetforegroundcolour} to access them, and they will be dynamically determined if necessary.
  20
  21
  22
  23 \subsubsection{Sizers Internal Overhaul}\label{sizersinternaloverhaul}
  24
  25 \helpref{The Sizers}{sizeroverview} 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:
  26
  27 \begin{itemize}\itemsep=0pt
  28 \item The size that a window had when \helpref{Add()}{wxsizeradd}ed to the sizer was assumed
  29       to be its minimal size, and that size would always be used by
  30       default when calculating layout size and positions, and the
  31       sizer itself would keep track of that minimal size.
  32
  33 \item If the window item was \helpref{Add()}{wxsizeradd}ed with the \windowstyle{wxADJUST\_MINSIZE} flag
  34       then when layout was calculated the item's \helpref{GetBestSize}{wxwindowgetbestsize} would be
  35       used to reset the minimal size that the sizer used.
  36 \end{itemize}
  37
  38   The main thrust of the new Sizer changes was to make behaviour like
  39   \windowstyle{wxADJUST\_MINSIZE} be the default, and also to push the tracking of
  40   the minimal size to the window itself (since it knows its own needs)
  41   instead of having the sizer take care of it.  Consequently these
  42   changes were made:
  43
  44 \begin{itemize}\itemsep=0pt
  45 \item The \windowstyle{wxFIXED\_MINSIZE} flag was added to allow for the old
  46       behaviour.  When this flag is used the size a window has when
  47       \helpref{Add()}{wxsizeradd}ed to the sizer will be treated as its minimal size and it
  48       will not be readjusted on each layout.
  49
  50 \item The min size stored in wxWindow and settable with \helpref{SetSizeHints}{wxwindowsetsizehints} or
  51       \helpref{SetMinSize}{wxwindowsetminsize} will by default be used by the sizer (if it was set)
  52       as the minimal size of the sizer item.  If the minsize was not
  53       set (or was only partially set) then the window's best size is
  54       fetched and it is used instead of (or blended with) the minsize.
  55       \helpref{wxWindow::GetBestFittingSize}{wxwindowgetbestfittingsize} was added to facilitate getting the
  56       size to be used by the sizers.
  57
  58 \item The best size of a window is cached so it doesn't need to
  59       recalculated on every layout. \helpref{wxWindow::InvalidateBestSize}{wxwindowinvalidatebestsize} was
  60       added and should be called (usually just internally in control
  61       methods) whenever something is done that would make the best
  62       size change.
  63
  64 \item All \helpref{wxControls}{wxcontrol} were changed to set the minsize to what is passed
  65       to the constructor or their Create method, and also to set the real
  66       size of the control to the blending of the minsize and bestsize.
  67       \helpref{wxWindow::SetBestFittingSize}{wxwindowsetbestfittingsize} was added to help with this,
  68       although most controls don't need to call it directly because it
  69       is called indirectly via the \helpref{SetInitialBestSize}{wxwindowsetinitialbestsize} called in the base
  70       classes.
  71 \end{itemize}
  72
  73   At this time, the only situation known not to work the same as
  74   before is the following:
  75
  76 \begin{verbatim}
  77 win = new SomeWidget(parent);
  78 win->SetSize(SomeNonDefaultSize);
  79 sizer->Add(win);
  80 \end{verbatim}
  81
  82   In this case the old code would have used the new size as the
  83   minimum, but now the sizer will use the default size as the minimum
  84   rather than the size set later.  It is an easy fix though, just move
  85   the specification of the size to the constructor (assuming that
  86   SomeWidget will set its minsize there like the rest of the controls
  87   do) or call \helpref{SetMinSize}{wxwindowsetminsize} instead of \helpref{SetSize}{wxwindowsetsize}.
  88
  89   In order to fit well with this new scheme of things, all \helpref{wxControls}{wxcontrol}
  90   or custom controls should do the following things.  (Depending on
  91   how they are used you may also want to do the same thing for
  92   non-control custom windows.)
  93
  94 \begin{itemize}\itemsep=0pt
  95 \item Either override or inherit a meaningful \helpref{DoGetBestSize}{wxwindowdogetbestsize} method
  96       that calculates whatever size is "best" for the control.  Once
  97       that size is calculated then there should normally be a call to
  98       \helpref{CacheBestSize}{wxwindowcachebestsize} to save it for later use, unless for some reason
  99       you want the best size to be recalculated on every layout.
 100
 101 \item Any method that changes the attributes of the control such that
 102       the best size will change should call \helpref{InvalidateBestSize}{wxwindowinvalidatebestsize} so it
 103       will be recalculated the next time it is needed.
 104
 105 \item The control's constructor and/or Create method should ensure
 106       that the minsize is set to the size passed in, and that the
 107       control is sized to a blending of the min size and best size.
 108       This can be done by calling \helpref{SetBestFittingSize}{wxwindowsetbestfittingsize}.
 109 \end{itemize}
 110
 111
 112
 113 \subsubsection{Massive wxURL Rewrite}\label{wxurlrewrite}
 114
 115 \helpref{wxURL}{wxurl} has undergone some radical changes.
 116
 117 \begin{itemize}\itemsep=0pt
 118 \item Many accessors of \helpref{wxURL}{wxurl} - GetHostName, GetProtocolName, and GetPath,
 119       have been replaced by its parent's (\helpref{wxURI}{wxuri}) counterparts - \helpref{GetServer}{wxurigetserver},
 120       \helpref{GetScheme}{wxurigetscheme}, and \helpref{GetPath}{wxurigetpath}, respectively.
 121
 122 \item ConvertToValidURI has been replaced by \helpref{wxURI}{wxuri}.  Do not use
 123       ConvertToValidURI for future applications.
 124
 125 \item ConvertFromURI has been replaced by \helpref{wxURI::Unescape}{wxuriunescape}.
 126 \end{itemize}
 127
 128
 129
 130 \subsubsection{Less drastic incompatible changes since 2.4.x}\label{24incompatiblelessdrastic}
 131
 132 - no initialization/cleanup can be done in \helpref{wxApp}{wxappctor}/\helpref{~wxApp}{wxappdtor} because they are
 133   now called much earlier/later than before; please move any exiting code
 134   from there to \helpref{wxApp::OnInit()}{wxapponinit}/\helpref{OnExit()}{wxapponexit}
 135
 136 - also, \helpref{OnExit()}{wxapponexit} is not called if \helpref{OnInit()}{wxapponinit} fails
 137
 138 - finally the program exit code is \helpref{OnRun()}{wxapponrun} return value, not \helpref{OnExit()}{wxapponexit} one
 139
 140 - \texttt{wxTheApp} can't be assigned to any longer, use \helpref{wxApp::SetInstance()}{wxappsetinstance} instead
 141
 142 - \helpref{wxFileType::GetIcon()}{wxfiletypegeticon} returns \helpref{wxIconLocation}{wxiconlocation}, not \helpref{wxIcon}{wxicon}
 143
 144 - wxColourDatabase is not a \helpref{wxList}{wxlist} any more, use AddColour to add new colours
 145
 146 - wxWindow::Clear() is now called ClearBackground()
 147
 148 - pointer returned by wxFont::GetNativeFontInfo() must not be deleted now
 149
 150 - wxMouseEvent::Moving() doesn't return true if mouse is being dragged any more
 151
 152 - (most) controls now inherit parents colours by default, override
 153   ShouldInheritColours() to return false if you don't want this to happen
 154
 155 - \helpref{wxApp::SendIdleEvents()}{wxappsendidleevents} now takes 2 arguments
 156
 157 - wxTabView::GetLayers() changed return type from \helpref{wxList&}{wxlist} to wxTabLayerList&
 158   (when WXWIN\_COMPATIBILITY\_2\_4 == 0)
 159
 160 - wxID\_SEPARATOR (id used for the menu separators) value changed from -1 to -2
 161
 162 - wxGetNumberFromUser() is now in separate wx/numdlg.h, not wx/textdlg.h
 163
 164 - wxChoice and wxCombobox now handle their size in the same way as in all the
 165   other ports under MSW, new code is actually correct but different from weird
 166   stuff they were doing before so the behaviour of your programs might change
 167
 168 - \helpref{wxTaskBarIcon}{wxtaskbaricon} objects must now be destroyed before the application can exit.
 169   Previously, the application terminated if there were no top level windows;
 170   now it terminates if there are no top level windows or taskbar icons left.
 171
 172 - \helpref{wxZlibInputStream}{wxzlibinputstream} is not by default compatible with the output of the
 173   2.4.x version of \helpref{wxZlibOutputStream}{wxzliboutputstream}. However, there is a compatibility mode,
 174   switched on by passing wxZLIB\_24COMPATIBLE to the constructor.
 175
 176 - when WXWIN\_COMPATIBILITY\_2\_4 == 0 \helpref{wxHashTable}{wxhashtable} uses a new implementation
 177   not using \helpref{wxList}{wxlist} keyed interface (the same used when wxUSE\_STL == 1),
 178   the only incompatibility being that Next() returns a wxHashTable::Node*
 179   instead of a wxNode*.
 180
 181 - non-const wxDC methods GetBackground(), GetBrush(), GetFont() and GetPen()
 182   as well as wxWindow methods GetFont() and GetCursor() don't exist any more,
 183   please fix your code -- it never worked correctly anyhow if you modified the
 184   objects returned by these methods so you should simply switch to using const
 185   methods.
 186
 187 - \helpref{wxWindow::GetFont()}{wxwindowgetfont} now returns \helpref{wxFont}{wxfont} object instead of reference
 188
 189 - EVT\_XXX macros are now type-safe; code that uses wrong type for event
 190   handler's argument will no longer compile.
 191
 192 - Identical functionality of wxFileDialog::ParseWildcard,
 193   wxGenericDirCtrl::ParseFilter, Motif and MSW parsing native dialogs
 194   is now accessible in ::wxParseCommonDialogsFilter
 195
 196 - wxNotebookSizer and wxBookCtrlSizer are now deprecated -- they are no longer
 197   needed, you can treat wxNotebook as any other control and put it directly
 198   into the sizer that was wxNotebookSizer's parent sizer in old code.
 199
 200 - \helpref{wxFile}{wxfile} methods now return either wxFileOffset or wxFileSize\_t which may be a
 201   64 bit integer type, even on 32 bit platforms, instead of off\_t and so the
 202   return value of \helpref{wxFile::Length()}{wxfilelength}, for example, shouldn't be assigned to off\_t
 203   variable any more (the compiler might warn you about this)
 204
 205 - wxListItem::m\_data is now of type wxUIntPtr, not long, for compatibility
 206   with 64 bit systems
 207
 208 - wxSizer::Add/Insert returns pointer to wxSizerItem just added so conditions
 209   writeen with if(Add(..)==true) will not work. Use if(Add(..)) instead.
 210
 211 - New \helpref{wxBrush::IsHatch()}{wxbrushishatch} checking for brush type replaces IS_HATCH macro.
 212
 213
 214
 215 \subsection{Depreciated changes since 2.4.x}\label{depreciatedsince24}
 216
 217 - wxURL::GetInputStream() and similar functionality has been depreciated in
 218   favor of other ways of connecting, such as though sockets or wxFileSystem.
 219
 220 - wxDocManager::GetNoHistoryFiles() renamed to \helpref{GetHistoryFilesCount()}{wxdocmanagergethistoryfilescount}
 221
 222 - wxSizer::Remove(wxWindow *), use Detach() instead [it is more clear]
 223
 224 - wxSizer::Set/GetOption(): use Set/GetProportion() instead
 225
 226 - wxKeyEvent::KeyCode(): use GetKeyCode instead
 227
 228 - wxList::Number, First, Last, Nth: use GetCount, GetFirst/Last, Item instead
 229
 230 - wxNode::Next, Previous, Data: use GetNext, GetPrevious, GetData instead
 231
 232 - wxListBase::operator wxList&(): use typesafe lists instead
 233
 234 - wxTheFontMapper: use \helpref{wxFontMapper::Get()}{wxfontmapperget} instead
 235
 236 - wxStringHashTable: use wxHashMap instead
 237
 238 - wxHashTableLong: use wxHashMap instead
 239
 240 - wxArrayString::GetStringArray: use wxCArrayString or alternative wxWidgets
 241                                  methods taking wxArrayString
 242
 243 - wxArrayString::Remove(index, count): use RemoveAt instead
 244
 245 - wxTreeItemId conversion to long is deprecated and shouldn't be used
 246
 247 - wxTreeCtrl::GetFirst/NextChild() 2nd argument now has type wxTreeItemIdValue
 248   and not long, please change declarations of "cookie"s in your code
 249   accordingly -- otherwise your code won't work on 64 bit platforms
 250
 251 - [MSW only] wxWindow::GetUseCtl3D(), GetTransparentBackground() and
 252              SetTransparent() as well as wxNO\_3D and wxUSER\_COLOURS styles
 253
 254 - \helpref{wxList}{wxlist} keyed interface: use \helpref{wxHashMap}{wxhashmap} instead
 255
 256 - wxColourDatabase::FindColour(): use \helpref{Find()}{wxcolourdatabasefind} instead (NB: different ret type)
 257
 258 - wxHashTable::Next: use wxHashTable::Node* or
 259                      wxHashTable::compatibility\_iterator to store the return
 260                      value
 261
 262 - wxWave class; use wxSound instead
 263
 264 - The wxHIDE\_READONLY flag for wxFileDialog was not implemented
 265   and has now been removed
 266
 267 - wxTaskBarIcon::OnXXX() virtual methods: use events instead
 268
 269 - obsolete and not used wxUSE\_GENERIC\_DIALOGS\_IN\_MSW has been removed
 270
 271 - wxDbTable::wxDbTable with wxChar* deprecated, same with wxString& instead