| | 1 | <?xml version="1.0" encoding="iso-8859-1" ?> |
| | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| | 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| | 4 | <head> |
| | 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
| | 6 | <meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" /> |
| | 7 | <title>The wxPython wx Package</title> |
| | 8 | <meta name="author" content="Patrick K. O'Brien" /> |
| | 9 | <meta name="author" content="Robin Dunn" /> |
| | 10 | <meta name="organization" content="Orbtech" /> |
| | 11 | <meta name="date" content="2004-03-26" /> |
| | 12 | <link rel="stylesheet" href="default.css" type="text/css" /> |
| | 13 | </head> |
| | 14 | <body> |
| | 15 | <div class="document" id="the-wxpython-wx-package"> |
| | 16 | <h1 class="title">The wxPython wx Package</h1> |
| | 17 | <h2 class="subtitle" id="or-how-to-survive-the-new-wx-namespace-changes">Or, how to survive the new wx namespace changes.</h2> |
| | 18 | <table class="docinfo" frame="void" rules="none"> |
| | 19 | <col class="docinfo-name" /> |
| | 20 | <col class="docinfo-content" /> |
| | 21 | <tbody valign="top"> |
| | 22 | <tr><th class="docinfo-name">Author:</th> |
| | 23 | <td>Patrick K. O'Brien</td></tr> |
| | 24 | <tr><th class="docinfo-name">Author:</th> |
| | 25 | <td>Robin Dunn</td></tr> |
| | 26 | <tr><th class="docinfo-name">Contact:</th> |
| | 27 | <td><a class="first last reference" href="mailto:pobrien@orbtech.com">pobrien@orbtech.com</a></td></tr> |
| | 28 | <tr><th class="docinfo-name">Organization:</th> |
| | 29 | <td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr> |
| | 30 | <tr><th class="docinfo-name">Date:</th> |
| | 31 | <td>2004-03-26</td></tr> |
| | 32 | <tr><th class="docinfo-name">Revision:</th> |
| | 33 | <td>1.4</td></tr> |
| | 34 | </tbody> |
| | 35 | </table> |
| | 36 | <div class="contents topic" id="contents"> |
| | 37 | <p class="topic-title first"><a name="contents">Contents</a></p> |
| | 38 | <ul class="simple"> |
| | 39 | <li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li> |
| | 40 | <li><a class="reference" href="#why-change-anything" id="id3" name="id3">Why change anything?</a></li> |
| | 41 | <li><a class="reference" href="#what-does-the-new-wx-package-do" id="id4" name="id4">What does the new wx package do?</a></li> |
| | 42 | <li><a class="reference" href="#will-any-of-this-effect-my-existing-code" id="id5" name="id5">Will any of this effect my existing code?</a></li> |
| | 43 | <li><a class="reference" href="#what-about-all-the-other-modules-like-grid-html-and-stc" id="id6" name="id6">What about all the other modules, like grid, html, and stc?</a></li> |
| | 44 | <li><a class="reference" href="#how-do-i-use-this-new-wx-package" id="id7" name="id7">How do I use this new wx package?</a></li> |
| | 45 | <li><a class="reference" href="#what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package" id="id8" name="id8">What are the issues with converting old code to use the new wx package?</a></li> |
| | 46 | <li><a class="reference" href="#where-can-i-find-example-programs-using-the-new-wx-syntax" id="id9" name="id9">Where can I find example programs using the new wx syntax?</a></li> |
| | 47 | </ul> |
| | 48 | </div> |
| | 49 | <div class="section" id="introduction"> |
| | 50 | <h1><a class="toc-backref" href="#id2" name="introduction">Introduction</a></h1> |
| | 51 | <p>In the begining there was Python, and Python had modules, and Python |
| | 52 | was good. But after a time Guido looked on Python and saw that Python |
| | 53 | needed organizational assistance, and so Guido took code from Python's |
| | 54 | side and created Packages and then Python was very good. About this |
| | 55 | time wxPython was reborn, and wxPython used Packages, but being young |
| | 56 | and trying to use a new technology wxPython did not know how to use |
| | 57 | Packages effectivly. wxPython was good, but dreamed of being much |
| | 58 | better...</p> |
| | 59 | <p>Now many years later, after tons of code reorganization and build |
| | 60 | hacking wxPython has reached that goal. In version 2.4.1 a prototype |
| | 61 | of this new structure was introduced that dynamically built at import |
| | 62 | time a new toplevel package named simply "wx" that contained all the |
| | 63 | items from wxPython.wx but with the names edited to remove the wx |
| | 64 | prefix. Now in 2.5 the final phase of that switcheroo has been |
| | 65 | completed and the <em>real</em> classes, functions and constants are now |
| | 66 | located in the wx package, leaving some compatibility modules in |
| | 67 | wxPython.wx. This document should answer all the questions you might |
| | 68 | have concerning the new wx package. Please also take a look at the |
| | 69 | <a class="reference" href="MigrationGuide.html">2.5 Migration Guide</a> to see notes about other big differences in |
| | 70 | this release.</p> |
| | 71 | </div> |
| | 72 | <div class="section" id="why-change-anything"> |
| | 73 | <h1><a class="toc-backref" href="#id3" name="why-change-anything">Why change anything?</a></h1> |
| | 74 | <p>This change is being made for a couple of reasons. The first reason |
| | 75 | is to discourage the use of <tt class="docutils literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous |
| | 76 | technique that can create name conflicts and bloated namespaces.</p> |
| | 77 | <p>The second reason is to remove what some perceive to be a "wart." For |
| | 78 | example, the following code is rather ugly in that the "wx" prefix on |
| | 79 | the wxFrame class name is no longer useful when you're using the wx |
| | 80 | module prefix:</p> |
| | 81 | <pre class="literal-block"> |
| | 82 | from wxPython import wx |
| | 83 | |
| | 84 | class Frame(wx.wxFrame) |
| | 85 | </pre> |
| | 86 | <p>The new wx package allows you to write code like this, instead:</p> |
| | 87 | <pre class="literal-block"> |
| | 88 | import wx |
| | 89 | |
| | 90 | class Frame(wx.Frame) |
| | 91 | </pre> |
| | 92 | <p>The third reason is that the wxWindows project has considered doing |
| | 93 | the same thing (implement a new wx namespace and drop the "wx" prefix) |
| | 94 | and we want wxPython to lead the way.</p> |
| | 95 | </div> |
| | 96 | <div class="section" id="what-does-the-new-wx-package-do"> |
| | 97 | <h1><a class="toc-backref" href="#id4" name="what-does-the-new-wx-package-do">What does the new wx package do?</a></h1> |
| | 98 | <p>As mentioned in the Introduction, wxPython 2.4.1 introduced a way of |
| | 99 | getting to this new syntax as quickly as possible. It would import |
| | 100 | the old names (like "wxFrame") from the old package and then create new |
| | 101 | names in the wx package without the wx prefix, (like "Frame".) |
| | 102 | Starting with wxPython 2.5 the renaming is moved up to the wxPython |
| | 103 | build step, so the real classes and etc. are actually named with the |
| | 104 | new name (like "Frame") and are located in the new wx package.</p> |
| | 105 | <p>For compatibility the old wxPython package still exists, but now it is |
| | 106 | populated with modules that simply import the new names and then |
| | 107 | "reverse-renames" them to the old names. It probably sounds a bit |
| | 108 | complicated, but it is mostly automated and so it doesn't cause |
| | 109 | problems in most cases.</p> |
| | 110 | </div> |
| | 111 | <div class="section" id="will-any-of-this-effect-my-existing-code"> |
| | 112 | <h1><a class="toc-backref" href="#id5" name="will-any-of-this-effect-my-existing-code">Will any of this effect my existing code?</a></h1> |
| | 113 | <p>No. Your existing code will continue to work and be supported for |
| | 114 | some time. It will be up to you to decide when to switch to the new |
| | 115 | syntax. But all new documentation and code examples will use the new |
| | 116 | syntax. So don't wait too long. You wouldn't want anyone calling you |
| | 117 | old-fashioned, would you?</p> |
| | 118 | <p>When you import from wxPython.wx and use a class with the old name, |
| | 119 | such as wxButton, you are actually using the wx.Button class. I |
| | 120 | expect that the vast majority of the existing code should work fine |
| | 121 | using this scheme. The only things that may cause problems is if your |
| | 122 | old code is depending on some of the implemtation details, or if you |
| | 123 | are using other things that have changed in the API. See the |
| | 124 | <a class="reference" href="MigrationGuide.html">Migration Guide</a> for more details.</p> |
| | 125 | </div> |
| | 126 | <div class="section" id="what-about-all-the-other-modules-like-grid-html-and-stc"> |
| | 127 | <h1><a class="toc-backref" href="#id6" name="what-about-all-the-other-modules-like-grid-html-and-stc">What about all the other modules, like grid, html, and stc?</a></h1> |
| | 128 | <p>There's more to the old wxPython than just the wxPython.wx module. |
| | 129 | And we've got those extra modules covered as well. Each of those |
| | 130 | modules (as well as the lib subpackage) has been moved to the new wx |
| | 131 | package and reverse-renamers have been placed in the wxPython package |
| | 132 | as needed.</p> |
| | 133 | </div> |
| | 134 | <div class="section" id="how-do-i-use-this-new-wx-package"> |
| | 135 | <h1><a class="toc-backref" href="#id7" name="how-do-i-use-this-new-wx-package">How do I use this new wx package?</a></h1> |
| | 136 | <p>The wx package is automatically created when you install wxPython |
| | 137 | version 2.4.1 or higher. So all you have to do is:</p> |
| | 138 | <pre class="literal-block"> |
| | 139 | import wx |
| | 140 | </pre> |
| | 141 | </div> |
| | 142 | <div class="section" id="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package"> |
| | 143 | <h1><a class="toc-backref" href="#id8" name="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package">What are the issues with converting old code to use the new wx package?</a></h1> |
| | 144 | <p>Obviously, you need to change your import statements from:</p> |
| | 145 | <pre class="literal-block"> |
| | 146 | from wxPython import wx |
| | 147 | </pre> |
| | 148 | <p>or:</p> |
| | 149 | <pre class="literal-block"> |
| | 150 | from wxPython.wx import * |
| | 151 | </pre> |
| | 152 | <p>to:</p> |
| | 153 | <pre class="literal-block"> |
| | 154 | import wx |
| | 155 | </pre> |
| | 156 | <p>Then you need to refer to wx attributes without a "wx" prefix, such |
| | 157 | as:</p> |
| | 158 | <pre class="literal-block"> |
| | 159 | class MyFrame(wx.Frame): |
| | 160 | </pre> |
| | 161 | <p>In most cases, existing code can be modified with a simple search and |
| | 162 | replace.</p> |
| | 163 | </div> |
| | 164 | <div class="section" id="where-can-i-find-example-programs-using-the-new-wx-syntax"> |
| | 165 | <h1><a class="toc-backref" href="#id9" name="where-can-i-find-example-programs-using-the-new-wx-syntax">Where can I find example programs using the new wx syntax?</a></h1> |
| | 166 | <p>The wxPython demo application and most of the sample apps have been |
| | 167 | converted to use the new <tt class="docutils literal"><span class="pre">import</span> <span class="pre">wx</span></tt> style of programming with |
| | 168 | wxPython, so there are lots of examples to look at and to play with. |
| | 169 | Here is one of them, it is the <tt class="docutils literal"><span class="pre">simple</span></tt> sample.</p> |
| | 170 | <pre class="literal-block"> |
| | 171 | #---------------------------------------------------------------------- |
| | 172 | # A very simple wxPython example. Just a wx.Frame, wx.Panel, |
| | 173 | # wx.StaticText, wx.Button, and a wx.BoxSizer, but it shows the basic |
| | 174 | # structure of any wxPython application. |
| | 175 | #---------------------------------------------------------------------- |
| | 176 | |
| | 177 | import wx |
| | 178 | |
| | 179 | |
| | 180 | class MyFrame(wx.Frame): |
| | 181 | """ |
| | 182 | This is MyFrame. It just shows a few controls on a wxPanel, |
| | 183 | and has a simple menu. |
| | 184 | """ |
| | 185 | def __init__(self, parent, title): |
| | 186 | wx.Frame.__init__(self, parent, -1, title, |
| | 187 | pos=(150, 150), size=(350, 200)) |
| | 188 | |
| | 189 | # Create the menubar |
| | 190 | menuBar = wx.MenuBar() |
| | 191 | |
| | 192 | # and a menu |
| | 193 | menu = wx.Menu() |
| | 194 | |
| | 195 | # add an item to the menu, using \tKeyName automatically |
| | 196 | # creates an accelerator, the third param is some help text |
| | 197 | # that will show up in the statusbar |
| | 198 | menu.Append(wx.ID_EXIT, "E&xit\tAlt-X", "Exit this simple sample") |
| | 199 | |
| | 200 | # bind the menu event to an event handler |
| | 201 | self.Bind(wx.EVT_MENU, self.OnTimeToClose, id=wx.ID_EXIT) |
| | 202 | |
| | 203 | # and put the menu on the menubar |
| | 204 | menuBar.Append(menu, "&File") |
| | 205 | self.SetMenuBar(menuBar) |
| | 206 | |
| | 207 | self.CreateStatusBar() |
| | 208 | |
| | 209 | |
| | 210 | # Now create the Panel to put the other controls on. |
| | 211 | panel = wx.Panel(self) |
| | 212 | |
| | 213 | # and a few controls |
| | 214 | text = wx.StaticText(panel, -1, "Hello World!") |
| | 215 | text.SetFont(wx.Font(14, wx.SWISS, wx.NORMAL, wx.BOLD)) |
| | 216 | text.SetSize(text.GetBestSize()) |
| | 217 | btn = wx.Button(panel, -1, "Close") |
| | 218 | funbtn = wx.Button(panel, -1, "Just for fun...") |
| | 219 | |
| | 220 | # bind the button events to handlers |
| | 221 | self.Bind(wx.EVT_BUTTON, self.OnTimeToClose, btn) |
| | 222 | self.Bind(wx.EVT_BUTTON, self.OnFunButton, funbtn) |
| | 223 | |
| | 224 | # Use a sizer to layout the controls, stacked vertically and with |
| | 225 | # a 10 pixel border around each |
| | 226 | sizer = wx.BoxSizer(wx.VERTICAL) |
| | 227 | sizer.Add(text, 0, wx.ALL, 10) |
| | 228 | sizer.Add(btn, 0, wx.ALL, 10) |
| | 229 | sizer.Add(funbtn, 0, wx.ALL, 10) |
| | 230 | panel.SetSizer(sizer) |
| | 231 | panel.Layout() |
| | 232 | |
| | 233 | |
| | 234 | def OnTimeToClose(self, evt): |
| | 235 | """Event handler for the button click.""" |
| | 236 | print "See ya later!" |
| | 237 | self.Close() |
| | 238 | |
| | 239 | def OnFunButton(self, evt): |
| | 240 | """Event handler for the button click.""" |
| | 241 | print "Having fun yet?" |
| | 242 | |
| | 243 | |
| | 244 | class MyApp(wx.App): |
| | 245 | def OnInit(self): |
| | 246 | frame = MyFrame(None, "Simple wxPython App") |
| | 247 | self.SetTopWindow(frame) |
| | 248 | |
| | 249 | print "Print statements go to this stdout window by default." |
| | 250 | |
| | 251 | frame.Show(True) |
| | 252 | return True |
| | 253 | |
| | 254 | app = MyApp(redirect=True) |
| | 255 | app.MainLoop() |
| | 256 | |
| | 257 | |
| | 258 | </pre> |
| | 259 | </div> |
| | 260 | </div> |
| | 261 | </body> |
| | 262 | </html> |
projects / wxWidgets.git / blame_incremental