docs/latex/wx/tchanges.tex

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