======================================== wxPython Project Phoenix Migration Guide ======================================== wxPython's Project Phoenix is a new incarnation of the wxPython toolkit in which everything that existed before will be cast into the flames in the hopes that that which emerges from the ashes will be better, brighter, stronger and faster than before. For more details about why and how, please see the ProjectPhoenix_ pages in the wiki. .. _ProjectPhoenix: http://wiki.wxpython.org/ProjectPhoenix This document will describe some of the incompatibilities that programmers will run into when migrating code from Classic wxPython to the Phoenix. For some types of changes there won't be any attempt to document the nitty gritty details of the differences, but rather the general patterns of the changes will be documented. Most proggrammers should then be able to work out the details for themselves. Overloaded Functions -------------------- In order to support more than one of the versions of an overloaded C++ function or class method in Classic wxPython, we had to rename all but one of them. For example, for the wxWindow::SetSize method we have SetSize, SetDimensions, SetRect and SetSizeWH. One of the features of the new tools used for Project Pheonix is that we no longer need to do that and instead we can have just one function or method in the Python API and the propper version of the C++ function or method is chosen at runtime based on the types of parameters passed to the function. So in most cases the renamed versions of the overloaded functions have been removed and you can call the function with the same name as the C++ API. This also includes the default constructor for all widget classes, used for the 2-phase create. Previously they were renamed to to be the class name with "Pre" prepended to it. For example, wx.PreWindow(), wx.PreFrame(), etc. Now in the Phoenix build of wxPython that is no longer neccessary and you can just call the class with no parameters like normal. For those renamed items that are more commonly used in the old wxPython I'll add some alias that will issue a DeprecationWarning for the first release or two after we switch over to the Phoenix version of the code, and then remove them in a later release. Static Methods -------------- In the distant past when SWIG was generating wrapper code for C++ static methods it would create a standalone function named ClassName_MethodName for it. When Python added support for static methods then SWIG was able to use that to make a real static method named ClassName.MethodName, but it still generated the standalone function named with the underscore, for compatibility. That underscore verison of the static methods is now gone, and you will get an AttributeError in existing code that is using them. To fix the problem simply change the underscore to a dot, for example you should change this:: c = wx.SystemSettings_GetColour(wx.SYS_COLOUR_MENUTEXT) to this:: c = wx.SystemSettings.GetColour(wx.SYS_COLOUR_MENUTEXT) You can also make this change in your existing code that is using pre-Phoenix versions of wxPython, in order to help you prepare for the transition. Unicode and Auto-Converting Strings ----------------------------------- Starting with the wxPython 2.9 release series, there are no longer separate ansi/Unicode builds of wxPython. All wxPython builds are now essentially the same as the old Unicode builds. This means that all string objects passed to wx API functions or methods are converted to Unicode before calling the C++ function or method. By default wxPython would use the encoding specified by the locale that was current at the time of the import of the wx module. However using the default locale could sometimes cause issues because it meant that slightly different encodings could be used on different platforms, even in the same locale, or the program could end up using an encoding in a different locale that the developer has not tested their code with. Project Phoenix takes this Unicode simplification one step further by stipulating that only the utf-8 encoding will be used for auto-converting string objects to the Unicode objects that will be passed on to the wx APIs. If you need to deal with text using a different encoding then you will need to convert it to Unicode yourself before passing the text to the wx API. For the most part this should not be much of a problem for well written programs that support Unicode because they will typically only convert to/from Unicode when reading/writing text to a file or database, and will use Unicode objects throughout the rest of the code. The common exception to this is that string-literals are often used in the code for specifying labels, etc. for UI elements. If your text for the string literals in your code are all ascii or utf-8 then you should not need to make any changes at all. If you have literals with some other encoding then you'll need to deal with them one way or another, either change the encoding of your source file to utf-8, or convert the literals from your encoding to Unicode before passing the text to the wx API. wx.Platform, wx.PlatformInfo ---------------------------- wx.Platform has been renamed to wx.Port, and wx.PlatformInfo has been renamed to wx.PortInfo. The reason for this change is that wrappers for a C++ class named wxPlatformInfo have been added, and would have caused a name conflict if the old wx.PlatformInfo had not been renamed. To make transitioning a little easier, I've made instances of the new wx.PlatformInfo class act like a Python sequence containing the same items as the old wx.PlatformInfo. So that means that you can simply change things like this:: if 'wxMac' in wx.PlatformInfo: ... to this:: if 'wxMac' in wx.PlatformInfo.Get(): ... Font, Pen, and Brush Styles --------------------------- The following aliases are currently added for backwards compatiblity, but will be removed in a future release. You should migrate any code that is using the old names to use the new ones instead:: wx.DEFAULT = wx.FONTFAMILY_DEFAULT wx.DECORATIVE = wx.FONTFAMILY_DECORATIVE wx.ROMAN = wx.FONTFAMILY_ROMAN wx.SCRIPT = wx.FONTFAMILY_SCRIPT wx.SWISS = wx.FONTFAMILY_SWISS wx.MODERN = wx.FONTFAMILY_MODERN wx.TELETYPE = wx.FONTFAMILY_TELETYPE wx.NORMAL = wx.FONTWEIGHT_NORMAL wx.LIGHT = wx.FONTWEIGHT_LIGHT wx.BOLD = wx.FONTWEIGHT_BOLD wx.NORMAL = wx.FONTSTYLE_NORMAL wx.ITALIC = wx.FONTSTYLE_ITALIC wx.SLANT = wx.FONTSTYLE_SLANT wx.SOLID = wx.PENSTYLE_SOLID wx.DOT = wx.PENSTYLE_DOT wx.LONG_DASH = wx.PENSTYLE_LONG_DASH wx.SHORT_DASH = wx.PENSTYLE_SHORT_DASH wx.DOT_DASH = wx.PENSTYLE_DOT_DASH wx.USER_DASH = wx.PENSTYLE_USER_DASH wx.TRANSPARENT = wx.PENSTYLE_TRANSPARENT wx.STIPPLE_MASK_OPAQUE = wx.BRUSHSTYLE_STIPPLE_MASK_OPAQUE wx.STIPPLE_MASK = wx.BRUSHSTYLE_STIPPLE_MASK wx.STIPPLE = wx.BRUSHSTYLE_STIPPLE wx.BDIAGONAL_HATCH = wx.BRUSHSTYLE_BDIAGONAL_HATCH wx.CROSSDIAG_HATCH = wx.BRUSHSTYLE_CROSSDIAG_HATCH wx.FDIAGONAL_HATCH = wx.BRUSHSTYLE_FDIAGONAL_HATCH wx.CROSS_HATCH = wx.BRUSHSTYLE_CROSS_HATCH wx.HORIZONTAL_HATCH = wx.BRUSHSTYLE_HORIZONTAL_HATCH wx.VERTICAL_HATCH = wx.BRUSHSTYLE_VERTICAL_HATCH wx.PyDeadObjectError --------------------- Classic wxPython tracks when the C++ part of some types of objects (pretty much just window types) is destroyed and then replaces the proxy object's class with one that rases a wx.PyDeadObjectError exception. SIP takes care of that for us now in a much better way, so that custom hack is no longer present in Phoenix, however a RuntimeError is the exception that is raised now. The wx.Window class has a __nonzero__ method that tests if the C++ object has been deleted, so you can still test the window with an if or other conditional statement to see if it is safe to use, like this:: if someWindow: doSomething()