You should not use AddWindow, AddSizer, AddSpacer (and similar for
Insert, Prepend, and etc.) methods any longer. Just use Add and the
wrappers will figure out what to do. **[Changed in 2.5.2.x]**
-AddWindow, AddSize, AddSpacer and etc. will now issue a
+AddWindow, AddSizer, 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``.
version.
There are only a few known compatibility issues at this time. First
-is the location of OGL. The deprecated version is located in the
-wx.ogl module, and the new version is in the wx.lib.ogl package. So
-this just means that to start using the new version you need to adjust
-your imports. So if your code currently has something like this::
+is that the ogl.DrawnShape has not been reimplemented yet. Next is the
+location of OGL. The deprecated version is located in the wx.ogl
+module, and the new version is in the wx.lib.ogl package. So this
+just means that to start using the new version you need to adjust your
+imports. So if your code currently has something like this::
import wx
import wx.ogl as ogl
the "internal" module names have changed, but you shouldn't have been
using them anyway so it shouldn't bother you. ;-) In case you were
erroneously using them in 2.4, here are the internal extension modules
-no longer exist:
+that no longer exist:
* clip_dnd
* cmndlgs
of the core module imported with wxPython.wx or the wx package.
+wx.TaskBarIcon
+--------------
+
+**[Changed in 2.5.3.x]**
+
+wx.TaskbarIcon now works on all three platforms, although for wxGTK it
+depends on support from the Window Manager. On OS X the icon replaces
+the application's icon on the dock and when you right click on it the
+app's default popup menu is merged with the wx.TaskBarIcon's menu.
+Because of how it is implemented on the Mac using the Dock most of the
+TaskBarIcon events will _not_ be emitted on that platform, but since
+98% of the time you simply want to display an icon and have a popup
+menu it shouldn't be much of a problem. You can still use the other
+events on the other platforms, you'll just want to be sure that you
+can do everything you want via the menu too.
+
+Since popping up a menu is the most common thing to do with a
+TaskBarIcon the class has some new built in functionality to
+facilitate that. To use the TaskBarIcon in this new way, simply
+derive a new class from TaskBarIcon and implement a CreatePopupMenu
+method that creates and returns the menu. That's all there is to it,
+besides binding event handlers for the menu items of course. Take a
+look at the DemoTaskBarIcon class in the demo/Main.py module for an
+example.
+
+**NOTE**: Unfortunately due to being able to support virtualizing
+CreatePopupMenu the C++ TaskBarIcon instance now holds a reference to
+the Python instance, and so you will need to explicitly Destroy() your
+TaskBarIcon instance when you are done with it. (Like you do with
+wx.Dialogs.) If you don't destroy it then wxWidgets will assume that
+you want the app to keep running with just the icon in the task bar
+and the MainLoop will not exit.
+
+
Other Stuff
The wxWave class has been renamed to wxSound, and now has a slightly
different API.
-wx.TaskbarIcon works on wxGTK-based platforms (for some window
-managers,) however you have to manage it a little bit more than you
-did before. Basically, the app will treat it like a top-level frame
-in that if the wx.TaskBarIcon still exists when all the frames are
-closed then the app will still not exit. You need to ensure that the
-wx.TaskBarIcon is destroyed when your last Frame is closed. For
-wxPython apps it is usually enough if your main frame object holds the
-only reference to the wx.TaskBarIcon, then when the frame is closed
-Python reference counting takes care of the rest.
-
Before Python 2.3 it was possible to pass a floating point object as a
parameter to a function that expected an integer, and the
PyArg_ParseTuple family of functions would automatically convert to
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)
+
+
projects / wxWidgets.git / blobdiff