Add info about wx.NewIdRef to MigrationGuid, and update OnHTMLOpeningURL section too.

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

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)