X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6431656829b94369e1a74a6197df5541aba382d4..dcbbda5451ead669e94e17a2a4d206295bed183b:/wxPython/docs/MigrationGuide.txt diff --git a/wxPython/docs/MigrationGuide.txt b/wxPython/docs/MigrationGuide.txt index 4f8bd7bed5..24bbb6540e 100644 --- a/wxPython/docs/MigrationGuide.txt +++ b/wxPython/docs/MigrationGuide.txt @@ -427,31 +427,95 @@ wrappers will figure out what to do. **[Changed in 2.5.2.x]** AddWindow, AddSize, AddSpacer and etc. will now issue a DeprecationWarning. -**[Changed in 2.5.2.x]** wx.ADJUST_MINSIZE is now the default -behaviour for window items in sizers. This means that the item's -GetMinSize and/or GetBestSize will be called when calculating layout -and the return value from that will be used for the minimum size used -by the sizer. The wx.FIXED_MINSIZE flag was added that will cause the -sizer to use the old behaviour in that it will *not* call the window's -methods to determine the new best size, instead the minsize that the -window had when added to the sizer (or the size the window was created -with) will always be used. - -Related to the above, when controls and some other window types are -created either the size passed to the constructor, or their "best -size" if an explicit size was not passed in, is set as the window's -minimal size. For non top-level windows that hasn't meant much in the -past, but now the sizers are sensitive to the window's minimal size. -The key point to understand here is that it is no longer the window's -size it has when added to the sizer that matters, but its minimal -size. So you might have some issues to iron out if you create a -control without a size and then set its size to something before -adding it to the sizer. Since it's minimal size is probably not the -size you set then the sizer will appear to be misbehaving. The fix is -to either set the size when calling the window's constructor, or to -reset the min size by calling SetSizeHints. You can call SetSizeHints -at anytime to change the minsize of a window, just call the sizer's -Layout method to redistribute the controls as needed. +**[Changed in 2.5.2.x]** The Sizers have had some fundamental internal +changes in the 2.5.2.x release 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 added with the ``wx.ADJUST_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 +``wx.ADJUST_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 ``wx.FIXED_MINSIZE`` flag was added to allow for the old + behaviour. When this flag is used the size a window has when + added to the sizer will be treated as its minimal size and it + will not be readjusted on each layout. + + * The min size stored in ``wx.Window`` 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 min size 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 min size. ``wx.Window.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. ``wx.Window.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 min size and best + size. ``wx.Window.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 = 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. + + Note: In order to successfully override ``DoGetBestSize`` in + Python the class needs to be derived from ``wx.PyWindow``, + ``wx.PyControl``, or etc. If your class instead derives from + one of the standard wx classes then just be sure that the min + size gets explicitly set to what would have been the best size + and things should work properly in almost all situations. + + * 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``. @@ -799,3 +863,21 @@ for changes in capabilities, usage, etc. and will raise a DeprecationWarning if used. The main wx.Mask constructor has been modified to be compatible with wx.MaskColour so you should use it instead. + +**[Changed in 2.5.2.x]** In wx.TextCtrls that have the +wx.TE_PROCESS_TAB style the TAB key will be treated like an ordinary +character and will not cause any tab traversal navigation at all. If +you use this style but would still like to have the normal tab +traversal take place then you should send your own +wx.NavigationKeyEvent from the wx.EVT_KEY_DOWN handler. There is a +new Navigate method in the wx.Window class to help send the event and +it is used something like this:: + + flags = wx.NavigationKeyEvent.IsForward + if event.ShiftDown(): + flags = wx.NavigationKeyEvent.IsBackward + if event.ControlDown(): + flags |= wx.NavigationKeyEvent.WinChange + self.Navigate(flags) + +