Phoenix/docs/MigrationGuide.rst

========================================
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 programmers
should then be able to work out the details for themselves.

Please note that throughout this document and elsewhere in the project, as
well as community discussions and such, you may see the term "**Classic**"
used by itself. This refers to the original implementation of wxPython.
Likewise, a standalone "**Phoenix**" or "**Project Phoenix**" will generally
refer to this new implementation of wxPython.


Version Numbers
---------------

The version numbers for wxPython are no longer kept in sync with the wxWidgets
version number. In the past the common version number was used to indicate
exactly which version of wxWidgets should be used for the wxPython build. Now
wxWidgets is a git submodule, and the linked version is included in the
wxPython source tarball, so there is no longer any need to use the matching
version numbers to implicitly specify the version of the wxWidgets source to
use.

This means that wxPython can go back to a 3-component version number and follow
the common conventions used by 99% of the other software projects out there.
The 3 components are commonly called MAJOR, MINOR and RELEASE. Since wxPython
Phoenix is a major upgrade over wxPython Classic then we will start out with a
new MAJOR version number to help communicate that this isn't just a little
update from previous releases.

Additional flags will be appended to the version number in a manner that is
compliant with Python's PEP-440_. This includes syntax for alpha, beta,
release candidate releases, post-release builds, development snapshots, etc.
See ``buildtools/version.py`` in the Phoenix source tree for more details.

.. _PEP-440: https://www.python.org/dev/peps/pep-0440/


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 C++ ``wxWindow::SetSize`` method we have
``SetSize``, ``SetDimensions``, ``SetRect`` and ``SetSizeWH``.  One of the
features of 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 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 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 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.


FindWindow Methods
------------------

One instance of undoing the renames for overloading done in Classic that may
be not make as much sense as the others is the ``wx.Window.FindWindow``
methods.  This is because there are new methods in Phoenix that have the same
names as some of the renames in Classic, so we can't just leave a deprecated
alias in place that will direct the programmer to use the overloaded version
of the method instead of the renamed version.

So we now have the following FindWindow-related methods and static methods
available in the ``wx.Window`` class:

These are non-static and do a recursive search in ``self``::

    wx.Window.FindWindow(self, id)
    wx.Window.FindWindow(self, name)

These are ``staticmethods`` that either search all windows in the application,
or the subtree rooted at ``parent`` if it is given::

    wx.Window.FindWindowById(id, parent=None)
    wx.Window.FindWindowByLabel(label, parent=None)
    wx.Window.FindWindowByName(name, parent=None)

And these extra module-level helper functions added in Classic are still
available in Phoenix::

    wx.FindWindowById(id, parent=None)
    wx.FindWindowByLabel(label, parent=None)
    wx.FindWindowByName(name, parent=None)




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 ``staticmethod`` named ``ClassName.MethodName``, but it still
generated the standalone function named with the underscore, for
compatibility. That underscore version 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 (in Python
2.7) or bytes objects (Python 3+) passed to wx API functions or methods are
converted to Unicode before calling the C++ function or method.  By default
Classic 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/bytes 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.

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 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::

            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 raises 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:
        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 chaotic. 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 submodule. Most of
them will be in the ``wx.adv`` module. One 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.



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``.



wx.DragImage
------------

Phoenix is now providing both ``wx.DragImage`` and ``wx.GenericDragImage``
classes. Classic wxPython only provided ``wx.DragImage``, but it was actually
using ``wx.GenericDragImage`` internally for all platforms. ``wx.DragImage``
will now be a native implementation on Windows, and will still be the generic
version where a native implementation is not available. If you would rather
use the generic implementation on Windows too then switch to using the
``wx.GenericDragImage`` class name.


2-Phase Create
--------------

In Classic wxPython we had to do some fancy footwork to make use of
wxWidget's 2-Phase Create scheme for creating instances of a C++ widget
class, but delaying the creation of the UI object until later. (This is
needed for things like setting extended style flags that can not be set after
creation, or with class factories like XRC.) The old trickery should no
longer be needed, and instead you can write code that is much more sane. For
example, instead of Classic code like this::

    class MyDialog(wx.Dialog):
        def __init__(self, parent, ID, title):
            pre = wx.PreDialog()
            pre.SetExtraStyle(wx.FRAME_EX_CONTEXTHELP)
            pre.Create(parent, ID, title)
            self.PostCreate(pre)                           # 4

In Phoenix that should now be done like this::

    class MyDialog(wx.Dialog):
        def __init__(self, parent, ID, title):
            wx.Dialog.__init__(self)                       # 1
            self.SetExtraStyle(wx.FRAME_EX_CONTEXTHELP)    # 2
            self.Create(parent, ID, title)                 # 3


Notice that we are (#1) calling the base class ``__init__`` like usual, but
passing no parameters so the default C++ constructor will be invoked. Next
(#2, #3) we use ``self`` instead of ``pre`` because ``self`` is now a legitimate
instance of ``wx.Dialog``, and (#4) there is no longer any need to call
``PostCreate`` to do its black magic for us because there is no longer a rogue
instance that needs to be transplanted into ``self``.



wx.Image and Python Buffer Objects
----------------------------------

``wx.Image`` is now using the new buffer APIs for the constructors and methods
which accept any object supporting the buffer protocol.  These are methods
which allow you to set the raw RGB or Alpha data in the image in one step.  As
a consequence of using the new APIs the objects passed must also implement the
new buffer interface in order to be compatible.

``GetData`` and ``GetAlpha`` now return a copy of the image data as a
``bytearray`` object instead of a string object.  This means that since
``bytearrays`` are mutable you can do things like make changes to the data and
then use it in the ``SetData`` of another image.

``GetDataBuffer`` and ``GetAlphaBuffer`` now return ``memoryview`` objects,
which allow direct access to the RGB and Alpha buffers inside the image. Just
as in Classic you should not use those ``memoryview`` buffers after the
``wx.Image`` has been destroyed.  Using the returned ``memoryview`` object you
can manipulate the RGB or Alpha data inside the ``wx.Image`` without needing
to make a copy of the data.

Just as in Classic the ``SetDataBuffer`` and ``SetAlphaBuffer`` methods allow
you to tell the ``wx.Image`` to use memory buffers in other objects (such as a
numpy array) as its RGB or Alpha data, as long as the other object supports
the new buffer protocol.



wx.DropSource
-------------

We don't (yet) have an easy way to support different APIs per platform in the
wx class constructors, so ``wx.DropSource`` (which optionally takes parameters
that should be a ``wx.Icon`` on wxGTK or a ``wx.Cursor`` on the other
platforms) has been changed to not accept the cursor/icon in the constructors.
Instead you'll have to call either ``SetCursor`` or ``SetIcon`` depending on
the platform.



wx.DataObject and derived classes
---------------------------------

The ``wx.DataObject`` and ``wx.DataObjectSimple`` classes can now be
subclassed in Python.  ``wx.DataObject`` will let you provide complex
multi-format data objects that do not need to copy the data until one of the
formats is requested from the clipboard or a DnD operation.
``wx.DataObjectSimple`` is a simplification that only deals with one data
format, (although multiple objects can still be provided with
``wx.DataObjectComposite``.)

Python buffer objects are used for transferring data to/from the clipboard or
DnD partner.  Anything that supports the buffer protocol can be used for
setting or providing data, and a ``memoryview`` object is created for the APIs
where the data object should fetch from or copy to a specific memory location.
 Here is a simple example::

        class MyDataObject(wx.DataObjectSimple):
            def __init__(self, value=''):
                wx.DataObjectSimple.__init__(self)
                self.SetFormat(wx.DataFormat("my data format"))
                self.myData = bytes(value)

            def GetDataSize(self):
                return len(self.myData)

            def GetDataHere(self, buf):
                # copy our local data value to buf
                assert isinstance(buf, memoryview)
                buf[:] = self.myData
                return True

            def SetData(self, buf):
                # copy from buf to our local data value
                assert isinstance(buf, memoryview)
                self.myData = buf.tobytes()
                return True



Multiple Inheritance
--------------------

The SIP tool currently does not support having more than one wrapped C++ class
as the base classes of a Python class.  In most cases this is not a problem
because in wxPython you're more likely to use multiple inheritance with simple
mix-in classes or similar constructs than needing to inherit from more than
one wrapped C++ class.

However there is at least one use case where that can be a problem, and that
is with the ComboCtrl's ``wx.ComboPopup`` class.  In wxWidgets and also in
Classic you're encouraged to use ``wx.ComboPopup`` as a mix-in class combined
with the widget class that is going to be your popup window for the
``wx.ComboCtrl``.  This can not currently be done with Phoenix in the same
way, but you can also use a widget class with a ``wx.ComboPopup`` in a has-a
relationship rather than an is-a relationship.  See
``samples/combo/combo1.py`` for an example.



XRC
---

The "``LoadOnFoo``" methods of the ``XmlResource`` class were renamed
overloads of 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 ``wx.Frame``, instead
of creating a new ``wx.Frame`` for the content.



wx.PyEvent and wx.PyCommandEvent
--------------------------------

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 instances
of the class will still be there when the event is delivered to an event
handler. There is one main difference from Classic however, and that is that
those attributes are now stored in a dictionary object owned by the C++
instance, instead of being stored directly in the Python instance's
dictionary. In most cases this won't matter to you at all, but if your derived
class has a ``__getattr__`` method (or ``__setattr__``, or ``__delattr__``)
then you will need to get the attributes from that other dictionary instead.
You can get a reference to that dictionary using ``_getAttrDict()``. For
example::

    def __getattr__(self, name):
        d = self._getAttrDict()
        if name in d:
            return d[name]
        return doSomethingElse(name)



MakeModal
---------

Since it is usually not a good idea to make arbitrary top-level windows be
modal, (you should normally just use a ``wx.Dialog`` instead,) the
``wx.Frame.MakeModal`` method has been removed. The recommended alternative is
to use the ``wx.WindowDisabler`` 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::

    def MakeModal(self, modal=True):
        if modal and not hasattr(self, '_disabler'):
            self._disabler = wx.WindowDisabler(self)
        if not modal and hasattr(self, '_disabler'):
            del self._disabler



The wxversion module
--------------------

The ``wxversion`` module is gone, and will not be coming back.  The old way of
handling multi-version installs and choosing between them was a giant hack in
my opinion, and I regretted doing it shortly after it was implemented.  However
since there wasn't any other way that made sense at the time, and since some
people were using it already, it got left in the distribution.  But one of the
purposes of the Phoenix project is to remove as many of the hacks and cruft
from Classic as possible, so wxversion is gone.

These days there are **much** better ways to handle the things that the old
multi-versioning and version selection features that the ``wxversion`` module
provided.  Since wxPython Phoenix is built by default to be self-contained and
relocatable on all of the platforms, then unlike Classic there is no problem
with installing it in Python virtual environments.  So if you need to have
multiple versions of wxPython on your system, then create a virtual
environment for each project and install the version that each needs in their
environments.  If you have code that requires a specific version or range of
versions of wxPython then define the dependency in your ``setup.py`` file or a
``requirements.txt`` file and let ``pip`` take care of the details.  I'm
confident that you'll be much happier with this approach.



Property Grid
-------------

In Classic, custom classes derived from ``wx.propgrid.PGProperty`` could
specify which editor to use by providing a ``GetEditor`` method that returned a
string.  This method does not exist in C++, and was hacked in to the Python
wrapper classes in order to remove or simplify other wrapper related problems.

Those problems are no longer present in Phoenix and so it is easiest to go
back to the way C++ handles selecting the cell editor and avoid needing to
awkwardly kludge things together in order to maintain full compatibility.  If
you have a property class that implements the ``GetEditor`` method then adding
the following method to your property class will enable the propgrid to fetch
the editor instance properly::

    def DoGetEditorClass(self):
        return wx.propgrid.PropertyGridInterface.GetEditorByName(self.GetEditor())



wx.gizmos
---------

The ``wx.gizmos`` module in Classic was a set of wrappers around some
3rd-party C++ classes. Unfortunately that code has started rotting a little
since it has been unmaintained for a while. Instead of perpetuating this
problem into Phoenix the C++ wrappers have been tossed out and some of the
more commonly used classes from wx.gizmos has been ported to pure Python code,
which now lives in the ``wx.lib.gizmos`` package. There is also a temporary
``wx.gizmos`` module provided in order to provide the class names at the old
location too in order to ease transitioning to the new package. Please migrate
your code to use ``wx.lib.gizmos`` as ``wx.gizmos`` will likely go away in a
future release.

Please note that the new ``TreeListCtrl`` class is actually a thin wrapper
around AGW's ``HyperTreeList`` class since it was already a near perfect
superset of the old TreeListCtrl features and API. One compatibility
difference that may arise is that like most widgets in the AGW library the
style flags have been split into 2 parameters, ``style`` and ``agwSgtyle``,
but it should be a simple matter of changing existing code to pass the
tree-specific style flags in the ``agwStyle`` parameter, and wxWidgets common
style flags in the ``style`` parameter.


wx.lib.pubsub is deprecated
---------------------------

Although it originally started as part of this project, for a long time the
content of the ``wx.lib.pubsub`` package has been coming from a fork of the
original, called PyPubSub. It's all the same code, but with just a different
access path. However, now that Python 2.7 support in PyPubSub is no longer being
maintained in the latest versions, it is now time for wxPython to disconnect
itself in order to not have to remain on the older version. This means that
``wx.lib.pubsub`` is now deprecated.

Switching to the official PyPubSub is simple however, just install the package::

    pip install -U PyPubSub==3.3.0

And then change your import statements that are importing
``wx.lib.pubsub.whatever``, to just import ``pubsub.whatever`` instead. If you
are using Python3 and would like the newest version of PyPubSub then you can
drop the version number from the pip command above.


wx.html.HtmlWindow.OnOpeningURL
-------------------------------

In wxPython Classic the return value of ``wx.html.HtmlWindow.OnOpeningURL`` and
``wx.html.HtmlWindowInterface.OnHTMLOpeningURL`` could be either a value from the
``wx.html.HtmlOpeningStatus`` enumeration, or a string containing the URL to
redirect to.

In Phoenix this has been changed to a simpler wrapper implementation which
requires that both an enum value and a string be returned as a tuple. For
example::

    def OnHTMLOpeningURL(self, urlType, url):
        if urlType == wx.html.HTML_URL_IMAGE and url != self.otherURL:
            return (wx.html.HTML_REDIRECT, self.otherURL)
        return (wx.html.HTML_OPEN, "")


wx.NewId is deprecated
----------------------

:func:`wx.NewId` has been used forever in wxWidgets and wxPython to generate an
ID for use as the ID for controls, menu items, and similar things. It's really
quite a stupid implementation however, in that it simply increments a counter
and returns that value. There is no way for it to check if the ID is already in
use, for example if the programmer used some static numbers for IDs, or if the
counter wrapped around the max integer value and started over at the min integer
value.

So a few years ago the wxWidgets team implemented a reference counting scheme
for the ID values, and started using it internally. In a more recent release the
``wx.NewId`` function was deprecated. Then, even more recently, when code
was added to Phoenix's generator tools to automatically deprecate things that
are marked as deprecated in wxWidgets, then it became deprecated for us too.

The recommended alternative to ``wx.NewId`` is to just use ``wx.ID_ANY`` when
creating your widgets or other items with IDs. That will use the reference
counted ID scheme internally and the ID will be reserved until that item is
destroyed. In those cases where you would prefer to have items with the same ID,
or to reuse ID values for some other reason, then you should use the
:func:`wx.NewIdRef` function instead. It returns a :class:`wx.WindowIDRef`
object that can be compared with each other, sorted, used as a dictionary key,
converted to the actual integer value of the ID, etc.


wx.WS_EX_VALIDATE_RECURSIVELY is obsolete
-----------------------------------------

The wx.WS_EX_VALIDATE_RECURSIVELY extended style flag is obsolete, as it is
now the default (and only) behavior. The style flag has been added back into
wxPython for compatibility, but with a zero value. You can just stop using it
in your code with no change in behavior.


Parameter name changes in radial gradient methods
-------------------------------------------------

The parameter names for the ``wx.GraphicsContext`` methods for creating radial
gradients have changed in wxPython 4.1 to be a little more understandable. If
you are passing these values via their keyword names then you will need to
change your code. The prior C++ method signatures looked like this::

    virtual wxGraphicsBrush
    CreateRadialGradientBrush(wxDouble xo, wxDouble yo,
                              wxDouble xc, wxDouble yc,
                              wxDouble radius,
                              const wxGraphicsGradientStops& stops);

And they now look like this::

    virtual wxGraphicsBrush
    CreateRadialGradientBrush(wxDouble startX, wxDouble startY,
                              wxDouble endX, wxDouble endY,
                              wxDouble radius,
                              const wxGraphicsGradientStops& stops,
                              const wxGraphicsMatrix& matrix = wxNullGraphicsMatrix);



Possible Locale Mismatch on Windows
-----------------------------------

On the Windows platform, prior to Python 3.8, it appears that Python did not do
any initialization of the process locale settings, at least for the "en_US"
based locales. For example, in Python 3.7::

    >>> import locale
    >>> locale.getdefaultlocale()
    ('en_US', 'cp1252')
    >>> locale.getlocale()
    (None, None)

And in Python 3.8::

    >>> import locale
    >>> locale.getdefaultlocale()
    ('en_US', 'cp1252')
    >>> locale.getlocale()
    ('English_United States', '1252')

Now, when you add in the wxWidgets class wxLocale, then it can get even more
confusing on Windows. It seems that this boils down to wxWidgets setting the
locale using a Windows-specific name like "en-US" (with a hyphen instead of an
underscore). Since Python's locale module does not recognize this as a
legitimate locale alias, then calling `locale.getlocale()` after a `wx.Locale`
has been created will result in a `ValueError` exception.

So wxPython has added code in the `wx.App` class to try and set up the locale so
both Python and wxWidgets are set to equivalent settings. This is still somewhat
experimental however, and the implementation in wxPython 4.1.0 is still
problematic in some cases. If you have problems with it then you can disable or
change this code by overriding the `wx.App.InitLocale` method in a derived
class. It can either just do nothing, or you can implement some alternative
locale setup code there.

There will be a new implementation of `InitLocale` in 4.1.1 which should be
simpler and less likely to still have problems. But you'll still be able to
override `InitLocale` if needed.



Sizer item flags validation
---------------------------

Starting with wxPython 4.1, wxWidgets is now validating the flags passed
when adding items to a sizer, to ensure that they are the correct flags for
the type of the sizer. If the given flags do not make sense, for example using
horizontal alignment flags in a horizontal box sizer, then a wxAssertionError
error is raised.



CheckListCtrlMixin Redundancy
-----------------------------

The wx.lib.mixins.listCtrl.CheckListCtrlMixin is now obsolete because
wx.ListCtrl has new functionality which does pretty much the same thing. In
fact there is some overlap in method names which may trip up some use cases.
It is advised to drop the use of CheckListCtrlMixin and just use the
wx.ListBox functionality. You will need to call EnableCheckBoxes to turn it on,
and you may need to change some event handlers or overloaded methods.



.. toctree::
   :maxdepth: 2
   :hidden: