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