mirror of
https://github.com/wxWidgets/Phoenix.git
synced 2026-01-04 19:10:09 +01:00
af2a23c0ee
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@71020 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
239 lines
10 KiB
Plaintext
239 lines
10 KiB
Plaintext
========================================
|
|
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 --> RuntimeError
|
|
-------------------------------------
|
|
|
|
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()
|
|
|
|
|
|
|
|
wx.PyAssertionError --> wx.wxAssertionError
|
|
-------------------------------------------
|
|
|
|
This is the exception raised when one of the wxASSERT (or similar) statements
|
|
in the wx C++ code fails. Since it is a wxWidgets assertion and not a
|
|
wxPython assertion the name was changed to make that a little more clear. A
|
|
compatibility alias exists so using wx.PyAssertionError will still work, but
|
|
you should migrate those uses to wx.wxAssertionError if possible.
|
|
|
|
|
|
|
|
|
|
The 'wx' namespace and submodules reorganized
|
|
---------------------------------------------
|
|
|
|
Some reorganization of what classes and functions goes in which internal wx
|
|
extension module has been done. In Classic the organization of the extension
|
|
modules was somewhat haphazard and caotic. For example there were 5 separate
|
|
modules whose contents were loaded into the main "wx" package namespace and
|
|
several others that needed to be imported separately. However since there was
|
|
not much organization of the core the C++ wxadv and wxhtml DLLs would need to
|
|
be distributed with any applications built with a bundling tool even if the
|
|
application did not use any of those classes.
|
|
|
|
For Phoenix the location of the wrapper code for the classes and functions
|
|
will attempt to follow the same organization that wxWidgets uses for putting
|
|
those same classes and functions into DLLs or shared libraries. This means
|
|
that some things that were formerly in the core wx package namespace are no
|
|
longer there. They will have to be used by importing a wx sumbodule. Most of
|
|
them will be in the wx.adv module. Once nice advantage of doing this is that
|
|
if your application is not using any of these lesser used classes then you
|
|
will not have to bundle the new modules (nor the associated wx DLLs) with
|
|
your application when you use py2exe or other executable builder.
|
|
|
|
|
|
|
|
wx.ListCtrl
|
|
-----------
|
|
|
|
* In wx.ListItem and wx.ListEvent the "m_" properties are no longer
|
|
public. Instead use the associated getter/setter methods or the
|
|
auto-generated properties that are using them.
|
|
|