X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e6a5dac664ff1399e2939dc912f1495ca1e0dfba..8f8c4b40456b5a4ef56a704c69570c7a1c86e714:/wxPython/docs/MigrationGuide.txt diff --git a/wxPython/docs/MigrationGuide.txt b/wxPython/docs/MigrationGuide.txt index 8e5da9fe2e..c9dfddbedb 100644 --- a/wxPython/docs/MigrationGuide.txt +++ b/wxPython/docs/MigrationGuide.txt @@ -9,12 +9,27 @@ usual to see info about the not so major changes and other things that have been added to wxPython. +wxName Change +------------- + +The **wxWindows** project and library is now known as +**wxWidgets**. Please see here_ for more details. + +.. _here: http://www.wxwindows.org/name.htm + +This won't really affect wxPython all that much, other than the fact +that the wxwindows.org domain name will be changing to wxwidgets.org, +so mail list, CVS, and etc. addresses will be changing. We're going +to try and smooth the transition as much as possible, but I wanted you +all to be aware of this change if you run into any issues. + + Module Initialization --------------------- The import-startup-bootstrap process employed by wxPython was changed -such that wxWindows and the underlying gui toolkit are **not** +such that wxWidgets and the underlying gui toolkit are **not** initialized until the wx.App object is created (but before wx.App.OnInit is called.) This was required because of some changes that were made to the C++ wxApp class. @@ -28,7 +43,7 @@ potential problems are that the C++ side of the "stock-objects" (wx.BLUE_PEN, wx.TheColourDatabase, etc.) are not initialized until the wx.App object is created, so you should not use them until after you have created your wx.App object. If you do then an exception will -be raised telling you that the C++ object has not bene initialized +be raised telling you that the C++ object has not been initialized yet. Also, you will probably not be able to do any kind of GUI or bitmap @@ -107,11 +122,32 @@ Some examples of its use:: self.Bind(wx.EVT_SIZE, self.OnSize) self.Bind(wx.EVT_BUTTON, self.OnButtonClick, theButton) - self.Bind(wx.EVT_MENU, self.OnExit, id=ID_EXIT) - -I hope to be able to remove the need for using IDs even for menu -events too... + self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT) + + +The wx.Menu methods that add items to a wx.Menu have been modified +such that they return a reference to the wx.MenuItem that was created. +Additionally menu items and toolbar items have been modified to +automatically generate a new ID if -1 is given, similar to using -1 +with window classess. This means that you can create menu or toolbar +items and event bindings without having to predefine a unique menu ID, +although you still can use IDs just like before if you want. For +example, these are all equivallent other than their specific ID +values:: + + 1. + item = menu.Append(-1, "E&xit", "Terminate the App") + self.Bind(wx.EVT_MENU, self.OnExit, item) + 2. + item = menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App") + self.Bind(wx.EVT_MENU, self.OnExit, item) + + 3. + menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App") + self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT) + + If you create your own custom event types and EVT_* functions, and you want to be able to use them with the Bind method above then you should change your EVT_* to be an instance of wxPyEventBinder instead of a @@ -132,6 +168,8 @@ number of IDs that are needed to be passed to Connect. + + The wx Namespace ---------------- @@ -377,6 +415,135 @@ Insert, Prepend, and etc.) methods any longer. Just use Add and the wrappers will figure out what to do. +PlatformInfo +------------ + +Added wx.PlatformInfo which is a tuple containing strings that +describe the platform and build options of wxPython. This lets you +know more about the build than just the __WXPORT__ value that +wx.Platform contains, such as if it is a GTK2 build. For example, +instead of:: + + if wx.Platform == "__WXGTK__": + ... + +you should do this:: + + if "__WXGTK__" in wx.PlatformInfo: + ... + +and you can specifically check for a wxGTK2 build by looking for +"gtk2" in wx.PlatformInfo. Unicode builds are also detectable this +way. If there are any other platform/toolkit/build flags that make +sense to add to this tuple please let me know. + +BTW, wx.Platform will probably be deprecated in the future. + + + +ActiveX +------- + +Lindsay Mathieson's newest wxActiveX_ class has been wrapped into a new +extension module called wx.activex. It is very generic and dynamic +and should allow hosting of arbitray ActiveX controls within your +wxPython apps. So far I've tested it with IE, PDF, and Flash +controls, (and there are new samples in the demo and also library +modules supporting these.) + +.. _wxActiveX: http://members.optusnet.com.au/~blackpaw1/wxactivex.html + +The new wx.activex module contains a bunch of code, but the most +important things to look at are ActiveXWindow and ActiveXEvent. +ActiveXWindow derives from wxWindow and the constructor accepts a +CLSID for the ActiveX Control that should be created. (There is also +a CLSID class that can convert from a progID or a CLSID String.) The +ActiveXWindow class simply adds methods that allow you to query some +of the TypeInfo exposed by the ActiveX object, and also to get/set +properties or call methods by name. The Python implementation +automatically handles converting parameters and return values to/from +the types expected by the ActiveX code as specified by the TypeInfo, +(just bool, integers, floating point, strings and None/Empty so far, +but more can be handled later.) + +That's pretty much all there is to the class, as I mentioned before it +is very generic and dynamic. Very little is hard-coded and everything +that is done with the actual ActiveX control is done at runtime and +referenced by property or method name. Since Python is such a dynamic +language this is a very good match. I thought for a while about doing +some Python black-magic and making the specific methods/properties of +the actual ActiveX control "appear" at runtime, but then decided that +it would be better and more understandable to do it via subclassing. +So there is a utility class in wx.activex that given an existing +ActiveXWindow instance can generate a .py module containing a derived +class with real methods and properties that do the Right Thing to +reflect those calls to the real ActiveX control. There is also a +script/tool module named genaxmodule that given a CLSID or progID and +a class name, will generate the module for you. There are a few +examples of the output of this tool in the wx.lib package. See +iewin.py, pdfwin.py and flashwin.py. + +Currently the genaxmodule tool will tweak some of the names it +generates, but this can be controled if you would like to do it +differently by deriving your own class from GernerateAXModule, +overriding some methods and then using this class from a tool like +genaxmodule. [TODO: make specifying a new class on genaxmodule's +command-line possible.] The current default behavior is that any +event names that start with "On" will have the "On" dropped, property +names are converted to all lower case, and if any name is a Python +keyword it will have an underscore appended to it. GernerateAXModule +does it's best when generating the code in the new module, but it can +only be as good as the TypeInfo data available from the ActiveX +control so sometimes some tweaking will be needed. For example, the +IE web browser control defines the Flags parameter of the Navigate2 +method as required, but MSDN says it is optional. + +It is intended that this new wx.activex module will replace both the +older version of Lindsay's code available in iewin.IEHtmlWindow, and +also the wx.lib.activexwraper module. Probably the biggest +differences you'l ecounted in migrating activexwrapper-based code +(besides events working better without causing deadlocks) is that +events are no longer caught by overriding methods in your derived +class. Instead ActiveXWindow uses the wx event system and you bind +handlers for the ActiveX events exactly the same way you do for any wx +event. There is just one extra step needed and that is creating an +event ID from the ActiveX event name, and if you use the genaxmodule +tool then this extra step will be handled for you there. For example, +for the StatusTextChange event in the IE web browser control, this +code is generated for you:: + + wxEVT_StatusTextChange = wx.activex.RegisterActiveXEvent('StatusTextChange') + EVT_StatusTextChange = wx.PyEventBinder(wxEVT_StatusTextChange, 1) + +and you would use it in your code like this:: + + self.Bind(iewin.EVT_StatusTextChange, self.UpdateStatusText, self.ie) + +When the event happens and your event handler function is called the +event properties from the ActiveX control (if any) are converted to +attributes of the event object passed to the handler. (Can you say +'event' any more times in a single sentence? ;-) ) For example the +StatusTextChange event will also send the text that should be put into +the status line as an event parameter named "Text" and you can access +it your handlers as an attribute of the evnt object like this:: + + def UpdateStatusText(self, evt): + self.SetStatusText(evt.Text) + +These event object attributes should be considered read-only since +support for output parameters on the events is not yet implemented. +But that could/should change in the future. + +So how do you know what methods, events and properties that am ActiveX +control supports? There is a funciton in wx.activex named GetAXInfo +that returns a printable summary of the TypeInfo from the ActiveX +instance passed in. You can use this as an example of how to browse +the TypeInfo provided, and there is also a copy of this function's +output appended as a comment to the modules produced by the +genaxmodule tool. Beyond that you'll need to consult the docs +provided by the makers of the ActiveX control that you are using. + + Other Stuff ----------- @@ -414,3 +581,26 @@ wxPyTypeCast at all. If you use the old wxPython package and wxPython.wx namespace then there are compatibility aliases for much of the above items. + +The wxWave class has been renamed to wxSound, and now has a slightly +different API. + +wx.TaskbarIcon works on wxGTK-based platforms now, however you have to +manage it a little bit more than you did before. Basically, the app +will treat it like a top-level frame in that if the wx.TaskBarIcon +still exists when all the frames are closed then the app will still +not exit. You need to ensure that the wx.TaskBarIcon is destroyed +when your last Frame is closed. For wxPython apps it is usually +enough if your main frame object holds the only reference to the +wx.TaskBarIcon, then when the frame is closed Python reference +counting takes care of the rest. + +If you are embedding wxPython in a C++ app, or are writing wxPython +compatible extensions modules, then the usage of wxPyBeginAllowThreads +and wxPyEndAllowThreads has changed slightly. wxPyBeginAllowThreads +now returns a boolean value that must be passed to the coresponding +wxPyEndAllowThreads function call. This is to help do the RightThing +when calls to these two functions are nested, or if calls to external +code that are wrapped in the standard Py_(BEGIN|END)_ALLOW_THERADS may +result in wx event handlers being called (such as os.startfile.) +