diff --git a/docs/MigrationGuide.txt b/docs/MigrationGuide.txt index d3227007..96f503b1 100644 --- a/docs/MigrationGuide.txt +++ b/docs/MigrationGuide.txt @@ -15,7 +15,7 @@ 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 +general patterns of the changes will be documented. Most programmers should then be able to work out the details for themselves. @@ -53,22 +53,22 @@ 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 +the new tools used for Project Phoenix 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. +API and the proper version of the C++ function or method is chosen at +runtime based on the number and 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 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 +longer necessary and you can just call the class with no parameters like normal. -For those renamed items that are more commonly used in the old +For those renamed items that are more commonly used in the old Classic wxPython I'll add some aliases 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. @@ -138,12 +138,15 @@ 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. +In Python 3.x, where strings are already Unicode objects, most of the above +confusion goes away, however if you have bytes objects then the same rules of +auto-converting only from utf-8 will still apply. Font, Pen, and Brush Styles --------------------------- -The following aliases are currently added for backwards compatiblity, +The following aliases are currently added for backwards compatibility, 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:: @@ -240,25 +243,25 @@ the :ref:`Classic vs. Phoenix ` document for details. 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. +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. wx.TreeCtrl ----------- -* The GetItemData and SetItemData now behave just like GetItemPyData - and SetItemPyData did in Classic wxPython. In other words, instead - of needing to create and use instances of wx.TreeItemData to - associate Python data objects with tree items, you just use the - Python objects directly. It will also work when passing the data - objects directly to the AppendItem, InsertItem, etc. methods. (If - anybody was actually using the wx.TreeItemData objects directly - before and are unable to adapt then please let Robin know.) The - [G|S]etItemPyData members still exist, but are now deprecated - aliases for [G|S]etItemData. +The GetItemData and SetItemData now behave just like GetItemPyData +and SetItemPyData did in Classic wxPython. In other words, instead +of needing to create and use instances of wx.TreeItemData to +associate Python data objects with tree items, you just use the +Python objects directly. It will also work when passing the data +objects directly to the AppendItem, InsertItem, etc. methods. (If +anybody was actually using the wx.TreeItemData objects directly +before and are unable to adapt then please let Robin know.) The +[G|S]etItemPyData members still exist, but are now deprecated +aliases for [G|S]etItemData. @@ -411,10 +414,10 @@ relationship. See samples/combo/combo1.py for an example. XRC -------- +--- The "LoadOnFoo" methods of the XmlResource class were renamed overloads of -the coresponding "LoadFoo" methods. Since we no longer need to rename +the corresponding "LoadFoo" methods. Since we no longer need to rename overloaded methods the "LoadOn" version has been removed and you should just use the "LoadFoo" version instead. These methods are used to load some XRC content onto an existing window, such as a Frame, instead of creating a new @@ -425,7 +428,7 @@ Frame for the content. wx.PyEvent and wx.PyCommandEvent -------------------------------- -Unlike most other wx.Py classes these two still exist in Phoenix, and are +Unlike most other ``wx.Py`` classes these two still exist in Phoenix, and are still the base classes that you should use when creating your own custom event classes. For the most part they work just like they did in Classic, and they take care of ensuring that any Python attributes that you assign to @@ -452,7 +455,7 @@ MakeModal Since it is usually not a good idea to make arbitrary top-level windows be modal, (you should just use a wx.Dialog instead,) the MakeModal method has been removed. The recommended alternative is to use the wx.WindowDisabler -class instead, but if you prefer the semenatics of having a method to call to +class instead, but if you prefer the semantics of having a method to call to turn on or off the modalness of a window then you can add a method like this to your classes to give you a way to do it::