| | 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.2.8: http://docutils.sourceforge.net/" /> |
| | 7 | <title>The wxPython wx Package</title> |
| | 8 | <meta name="author" content="Patrick K. O'Brien" /> |
| | 9 | <meta name="organization" content="Orbtech" /> |
| | 10 | <meta name="date" content="2003-05-08" /> |
| | 11 | <link rel="stylesheet" href="default.css" type="text/css" /> |
| | 12 | </head> |
| | 13 | <body> |
| | 14 | <div class="document" id="the-wxpython-wx-package"> |
| | 15 | <h1 class="title">The wxPython wx Package</h1> |
| | 16 | <h2 class="subtitle" id="or-how-to-survive-the-new-wx-namespace-changes">Or, how to survive the new wx namespace changes.</h2> |
| | 17 | <table class="docinfo" frame="void" rules="none"> |
| | 18 | <col class="docinfo-name" /> |
| | 19 | <col class="docinfo-content" /> |
| | 20 | <tbody valign="top"> |
| | 21 | <tr><th class="docinfo-name">Author:</th> |
| | 22 | <td>Patrick K. O'Brien</td></tr> |
| | 23 | <tr><th class="docinfo-name">Contact:</th> |
| | 24 | <td><a class="first last reference" href="mailto:pobrien@orbtech.com">pobrien@orbtech.com</a></td></tr> |
| | 25 | <tr><th class="docinfo-name">Organization:</th> |
| | 26 | <td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr> |
| | 27 | <tr><th class="docinfo-name">Date:</th> |
| | 28 | <td>2003-05-08</td></tr> |
| | 29 | <tr><th class="docinfo-name">Revision:</th> |
| | 30 | <td>1.1.2.4</td></tr> |
| | 31 | </tbody> |
| | 32 | </table> |
| | 33 | <div class="contents topic" id="contents"> |
| | 34 | <p class="topic-title"><a name="contents">Contents</a></p> |
| | 35 | <ul class="simple"> |
| | 36 | <li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li> |
| | 37 | <li><a class="reference" href="#why-change-anything" id="id2" name="id2">Why change anything?</a></li> |
| | 38 | <li><a class="reference" href="#what-does-the-new-wx-package-do" id="id3" name="id3">What does the new wx package do?</a></li> |
| | 39 | <li><a class="reference" href="#will-any-of-this-effect-my-existing-code" id="id4" name="id4">Will any of this effect my existing code?</a></li> |
| | 40 | <li><a class="reference" href="#how-does-the-new-wx-package-work" id="id5" name="id5">How does the new wx package work?</a></li> |
| | 41 | <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> |
| | 42 | <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> |
| | 43 | <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> |
| | 44 | <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> |
| | 45 | </ul> |
| | 46 | </div> |
| | 47 | <div class="section" id="introduction"> |
| | 48 | <h1><a class="toc-backref" href="#id1" name="introduction">Introduction</a></h1> |
| | 49 | <p>Big things sometimes come in small packages. This is certainly true |
| | 50 | of the new wx package, which is being introduced in wxPython 2.4.1 as |
| | 51 | a way to allow the "wx" prefix to be dropped from the names of all |
| | 52 | wxPython classes, functions, and constants. This document should |
| | 53 | answer all the questions you might have concerning the new wx package. |
| | 54 | If not, feel free to contact the author. I hope you like the new wx |
| | 55 | package as much as I do.</p> |
| | 56 | </div> |
| | 57 | <div class="section" id="why-change-anything"> |
| | 58 | <h1><a class="toc-backref" href="#id2" name="why-change-anything">Why change anything?</a></h1> |
| | 59 | <p>This change is being made for a couple of reasons. The first reason |
| | 60 | is to discourage the use of <tt class="literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous |
| | 61 | technique that can create name conflicts and bloated namespaces.</p> |
| | 62 | <p>The second reason is to remove what some perceive to be a "wart." For |
| | 63 | example, the following code is rather ugly in that the "wx" prefix on |
| | 64 | the wxFrame class name is no longer useful when you're using the wx |
| | 65 | module prefix:</p> |
| | 66 | <pre class="literal-block"> |
| | 67 | from wxPython import wx |
| | 68 | |
| | 69 | class Frame(wx.wxFrame) |
| | 70 | </pre> |
| | 71 | <p>The new wx package allows you to write code like this, instead:</p> |
| | 72 | <pre class="literal-block"> |
| | 73 | import wx |
| | 74 | |
| | 75 | class Frame(wx.Frame) |
| | 76 | </pre> |
| | 77 | <p>The third reason is that the wxWindows project intends to do the same |
| | 78 | thing (implement a new wx namespace and drop the "wx" prefix) and we |
| | 79 | want wxPython to lead the way.</p> |
| | 80 | </div> |
| | 81 | <div class="section" id="what-does-the-new-wx-package-do"> |
| | 82 | <h1><a class="toc-backref" href="#id3" name="what-does-the-new-wx-package-do">What does the new wx package do?</a></h1> |
| | 83 | <p>As a way of getting to this new syntax as quickly as possible, the |
| | 84 | code in this new wx package was created. What it does is alter the |
| | 85 | existing wx namespace dynamically. By making the changes on-the-fly |
| | 86 | at runtime, we can try out the new syntax before any permanent changes |
| | 87 | are made to the underlying class library. The downside of making |
| | 88 | these changes at runtime is that there is a slight delay when you |
| | 89 | <tt class="literal"><span class="pre">import</span> <span class="pre">wx</span></tt>; the upside is that you can start using the new syntax |
| | 90 | now.</p> |
| | 91 | </div> |
| | 92 | <div class="section" id="will-any-of-this-effect-my-existing-code"> |
| | 93 | <h1><a class="toc-backref" href="#id4" name="will-any-of-this-effect-my-existing-code">Will any of this effect my existing code?</a></h1> |
| | 94 | <p>No. Your existing code will continue to work and be supported for |
| | 95 | some time. It will be up to you to decide when to switch to the new |
| | 96 | syntax. But all new documentation and code examples will use the new |
| | 97 | syntax. So don't wait too long. You wouldn't want anyone calling you |
| | 98 | old-fashioned, would you?</p> |
| | 99 | </div> |
| | 100 | <div class="section" id="how-does-the-new-wx-package-work"> |
| | 101 | <h1><a class="toc-backref" href="#id5" name="how-does-the-new-wx-package-work">How does the new wx package work?</a></h1> |
| | 102 | <p>It's pretty simple, and pretty clever. The wx directory contains an |
| | 103 | <tt class="literal"><span class="pre">__init__.py</span></tt> file, making it a Python package. (In contrast, the |
| | 104 | old wxPython.wx module is a module, not a package.) When you <tt class="literal"><span class="pre">import</span> |
| | 105 | <span class="pre">wx</span></tt> the code in the <tt class="literal"><span class="pre">__init__.py</span></tt> file is executed, and that's |
| | 106 | where all the magic takes place. Let's take a look at the code inside |
| | 107 | the <tt class="literal"><span class="pre">__init__.py</span></tt> file:</p> |
| | 108 | <pre class="literal-block"> |
| | 109 | """wx package |
| | 110 | |
| | 111 | Provides a way to drop the wx prefix from wxPython objects.""" |
| | 112 | |
| | 113 | __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>" |
| | 114 | __cvsid__ = "$Id$" |
| | 115 | __revision__ = "$Revision$"[11:-2] |
| | 116 | |
| | 117 | from wxPython import wx |
| | 118 | |
| | 119 | import types |
| | 120 | |
| | 121 | d_new = globals() |
| | 122 | d_old = wx.__dict__ |
| | 123 | |
| | 124 | for old, obj in d_old.items(): |
| | 125 | if type(obj) is types.ModuleType or old.startswith('_'): |
| | 126 | # Skip modules and private names. |
| | 127 | continue |
| | 128 | new = old |
| | 129 | if old.startswith('EVT_'): |
| | 130 | # Leave name unmodified; add to the new wx namespace. |
| | 131 | d_new[new] = obj |
| | 132 | elif old.startswith('wxEVT_'): |
| | 133 | # Leave name unmodified; add to the new wx namespace. |
| | 134 | d_new[new] = obj |
| | 135 | else: |
| | 136 | if old.startswith('wx'): |
| | 137 | # Remove the 'wx' prefix. |
| | 138 | new = old[2:] |
| | 139 | # Add to the new wx package namespace. |
| | 140 | d_new[new] = obj |
| | 141 | |
| | 142 | del d_new |
| | 143 | del d_old |
| | 144 | del new |
| | 145 | del obj |
| | 146 | del old |
| | 147 | del types |
| | 148 | |
| | 149 | del wx |
| | 150 | |
| | 151 | </pre> |
| | 152 | <p>Namespaces in Python are implemented as dictionaries. The dictionary |
| | 153 | used to create the wx package's namespace is accessible using the |
| | 154 | <tt class="literal"><span class="pre">globals()</span></tt> function. The dictionary used to create the old |
| | 155 | wxPython.wx module's namespace is <tt class="literal"><span class="pre">wx.__dict__</span></tt>. Once we have these |
| | 156 | two dictionaries, it's a simple matter of iterating through one, |
| | 157 | changing the names, adding the renamed object to the other dictionary, |
| | 158 | and cleaning up a few local variables and imported modules. Voila!</p> |
| | 159 | </div> |
| | 160 | <div class="section" id="what-about-all-the-other-modules-like-grid-html-and-stc"> |
| | 161 | <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> |
| | 162 | <p>There's more to wxPython than just the wx namespace. And we've got |
| | 163 | those extra modules covered as well. For each of those modules (as |
| | 164 | well as the lib package) we've got matching modules in the new wx |
| | 165 | package. Let's take a look at a few of them.</p> |
| | 166 | <p>Here is <tt class="literal"><span class="pre">html.py</span></tt>:</p> |
| | 167 | <pre class="literal-block"> |
| | 168 | """Provides a way to drop the wx prefix from wxPython objects.""" |
| | 169 | |
| | 170 | __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>" |
| | 171 | __cvsid__ = "$Id$" |
| | 172 | __revision__ = "$Revision$"[11:-2] |
| | 173 | |
| | 174 | import wx |
| | 175 | from wx import prefix |
| | 176 | |
| | 177 | from wxPython import html |
| | 178 | prefix.rename(d_new=globals(), d_old=html.__dict__) |
| | 179 | del html |
| | 180 | |
| | 181 | del prefix |
| | 182 | del wx |
| | 183 | |
| | 184 | </pre> |
| | 185 | <p>And here is <tt class="literal"><span class="pre">lib/dialogs.py</span></tt>:</p> |
| | 186 | <pre class="literal-block"> |
| | 187 | """Provides a way to drop the wx prefix from wxPython objects.""" |
| | 188 | |
| | 189 | __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>" |
| | 190 | __cvsid__ = "$Id$" |
| | 191 | __revision__ = "$Revision$"[11:-2] |
| | 192 | |
| | 193 | import wx |
| | 194 | from wx import prefix |
| | 195 | |
| | 196 | from wxPython.lib import dialogs |
| | 197 | prefix.rename(d_new=globals(), d_old=dialogs.__dict__) |
| | 198 | del dialogs |
| | 199 | |
| | 200 | del prefix |
| | 201 | del wx |
| | 202 | |
| | 203 | </pre> |
| | 204 | <p>As you can see, they both rely on the <tt class="literal"><span class="pre">prefix.rename()</span></tt> function |
| | 205 | defined in <tt class="literal"><span class="pre">prefix.py</span></tt>:</p> |
| | 206 | <pre class="literal-block"> |
| | 207 | """Renaming utility. |
| | 208 | |
| | 209 | Provides a way to drop the wx prefix from wxPython objects.""" |
| | 210 | |
| | 211 | __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>" |
| | 212 | __cvsid__ = "$Id$" |
| | 213 | __revision__ = "$Revision$"[11:-2] |
| | 214 | |
| | 215 | import types |
| | 216 | |
| | 217 | def rename(d_new, d_old): |
| | 218 | for old, obj in d_old.items(): |
| | 219 | if type(obj) is types.ModuleType or old.startswith('_'): |
| | 220 | # Skip modules and private names. |
| | 221 | continue |
| | 222 | ## mod = d_old['__name__'] |
| | 223 | ## if hasattr(obj, '__module__') and not obj.__module__.startswith(mod): |
| | 224 | ## # Skip objects imported from other modules, except those |
| | 225 | ## # related to the current module, such as stc_. |
| | 226 | ## continue |
| | 227 | new = old |
| | 228 | if old.startswith('EVT_') or old.startswith('wxEVT_'): |
| | 229 | # Leave these names unmodified. |
| | 230 | pass |
| | 231 | elif old.startswith('wx'): |
| | 232 | new = old[2:] |
| | 233 | if new: |
| | 234 | d_new[new] = d_old[old] |
| | 235 | |
| | 236 | </pre> |
| | 237 | <p>Again, the technique is very similar to the one used by the wx |
| | 238 | package.</p> |
| | 239 | </div> |
| | 240 | <div class="section" id="how-do-i-use-this-new-wx-package"> |
| | 241 | <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> |
| | 242 | <p>The wx package is automatically created when you install wxPython |
| | 243 | version 2.4.1 or higher. So all you have to do is:</p> |
| | 244 | <pre class="literal-block"> |
| | 245 | import wx |
| | 246 | </pre> |
| | 247 | </div> |
| | 248 | <div class="section" id="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package"> |
| | 249 | <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> |
| | 250 | <p>Obviously, you need to change your import statements from:</p> |
| | 251 | <pre class="literal-block"> |
| | 252 | from wxPython import wx |
| | 253 | </pre> |
| | 254 | <p>or:</p> |
| | 255 | <pre class="literal-block"> |
| | 256 | from wxPython.wx import * |
| | 257 | </pre> |
| | 258 | <p>to:</p> |
| | 259 | <pre class="literal-block"> |
| | 260 | import wx |
| | 261 | </pre> |
| | 262 | <p>Then you need to refer to wx attributes without a "wx" prefix, such |
| | 263 | as:</p> |
| | 264 | <pre class="literal-block"> |
| | 265 | class MyFrame(wx.Frame): |
| | 266 | </pre> |
| | 267 | <p>In most cases, existing code can be modified with a simple search and |
| | 268 | replace.</p> |
| | 269 | <p>One extra issue you might run into when converting existing code is |
| | 270 | that the wx.__version__ attribute is no longer available, since the |
| | 271 | new wx namespace doesn't include any private attributes from the old |
| | 272 | wxPython.wx namespace. The solution is to use the wx.VERSION_STRING |
| | 273 | attribute, which was introduced in wxPython 2.4.1.</p> |
| | 274 | </div> |
| | 275 | <div class="section" id="where-can-i-find-example-programs-using-the-new-wx-syntax"> |
| | 276 | <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> |
| | 277 | <p>Example programs are included in the wxPython/samples/wx_examples |
| | 278 | directory, and are documented in the <a class="reference" href="wxPythonExamples.html">wxPythonExamples</a> documentation |
| | 279 | file. Also, all the code in the py package uses the new wx syntax. |
| | 280 | You can learn more about these in the <a class="reference" href="PyManual.html">PyManual</a>.</p> |
| | 281 | </div> |
| | 282 | </div> |
| | 283 | <hr class="footer"/> |
| | 284 | <div class="footer"> |
| | 285 | <a class="reference" href="wxPackage.txt">View document source</a>. |
| | 286 | Generated on: 2003-06-04 18:07 UTC. |
| | 287 | Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. |
| | 288 | </div> |
| | 289 | </body> |
| | 290 | </html> |
projects / wxWidgets.git / blame_incremental