From fd1c26d2e14fc0cee3e03a794c49446f9f45e2af Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Tue, 12 Feb 2019 18:51:28 -0800 Subject: [PATCH] Add info about wx.NewIdRef to MigrationGuid, and update OnHTMLOpeningURL section too. --- docs/MigrationGuide.rst | 39 ++++++++++++++++++++++++++++++++++----- etg/utils.py | 8 ++++---- 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/docs/MigrationGuide.rst b/docs/MigrationGuide.rst index 157757ba..d3417776 100644 --- a/docs/MigrationGuide.rst +++ b/docs/MigrationGuide.rst @@ -599,11 +599,14 @@ drop the version number from the pip command above. wx.html.HtmlWindow.OnOpeningURL ------------------------------- -In Classic the return value of ``wx.html.HtmlWindow.OnOpeningURL`` 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:: +In wxPython Classic the return value of ``wx.html.HtmlWindow.OnOpeningURL`` and +``wx.html.HtmlWindoInterface.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: @@ -611,6 +614,32 @@ returned as a tuple. For example:: 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. + .. toctree:: :maxdepth: 2 diff --git a/etg/utils.py b/etg/utils.py index 1bf00922..0c186a2c 100644 --- a/etg/utils.py +++ b/etg/utils.py @@ -92,9 +92,9 @@ def run(): f.deprecated = """\ IDs generated by this function can possibly conflict with IDs used elsewhere in the application code. It is recommended to instead use the ``wx.ID_ANY`` ID to -assign generated IDs for the controls menu items and etc. that you create in the -application. These IDs are guaranteed to not conflict with the other IDs that -are in use in the application. For those cases where you need to create an ID +assign generated IDs for the controls, menu items and etc. that you create in the +application. These IDs are guaranteed to not conflict with the other IDs that +are in use in the application. For those cases where you need to create an ID that can be used more than once then please see :func:`wx.NewIdRef`.""".replace('\n', ' ') for funcname in ['wxBell', @@ -110,7 +110,7 @@ that can be used more than once then please see :func:`wx.NewIdRef`.""".replace( f = module.find(funcname) f.mustHaveApp() - + #----------------------------------------------------------------- tools.doCommonTweaks(module)