]> git.saurik.com Git - wxWidgets.git/blame - wxPython/demo/data/wxPackage.html
Fixed typo
[wxWidgets.git] / wxPython / demo / data / wxPackage.html
CommitLineData
1fded56b
RD
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&#64;orbtech.com">pobrien&#64;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
50of the new wx package, which is being introduced in wxPython 2.4.1 as
51a way to allow the &quot;wx&quot; prefix to be dropped from the names of all
52wxPython classes, functions, and constants. This document should
53answer all the questions you might have concerning the new wx package.
54If not, feel free to contact the author. I hope you like the new wx
55package 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
60is to discourage the use of <tt class="literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous
61technique that can create name conflicts and bloated namespaces.</p>
62<p>The second reason is to remove what some perceive to be a &quot;wart.&quot; For
63example, the following code is rather ugly in that the &quot;wx&quot; prefix on
64the wxFrame class name is no longer useful when you're using the wx
65module prefix:</p>
66<pre class="literal-block">
67from wxPython import wx
68
69class 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">
73import wx
74
75class Frame(wx.Frame)
76</pre>
77<p>The third reason is that the wxWindows project intends to do the same
78thing (implement a new wx namespace and drop the &quot;wx&quot; prefix) and we
79want 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
84code in this new wx package was created. What it does is alter the
85existing wx namespace dynamically. By making the changes on-the-fly
86at runtime, we can try out the new syntax before any permanent changes
87are made to the underlying class library. The downside of making
88these 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
90now.</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
95some time. It will be up to you to decide when to switch to the new
96syntax. But all new documentation and code examples will use the new
97syntax. So don't wait too long. You wouldn't want anyone calling you
98old-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
104old 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
106where all the magic takes place. Let's take a look at the code inside
107the <tt class="literal"><span class="pre">__init__.py</span></tt> file:</p>
108<pre class="literal-block">
109&quot;&quot;&quot;wx package
110
111Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
112
113__author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
114__cvsid__ = &quot;$Id$&quot;
115__revision__ = &quot;$Revision$&quot;[11:-2]
116
117from wxPython import wx
118
119import types
120
121d_new = globals()
122d_old = wx.__dict__
123
124for 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
142del d_new
143del d_old
144del new
145del obj
146del old
147del types
148
149del wx
150
151</pre>
152<p>Namespaces in Python are implemented as dictionaries. The dictionary
153used 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
155wxPython.wx module's namespace is <tt class="literal"><span class="pre">wx.__dict__</span></tt>. Once we have these
156two dictionaries, it's a simple matter of iterating through one,
157changing the names, adding the renamed object to the other dictionary,
158and 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
163those extra modules covered as well. For each of those modules (as
164well as the lib package) we've got matching modules in the new wx
165package. 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&quot;&quot;&quot;Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
169
170__author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
171__cvsid__ = &quot;$Id$&quot;
172__revision__ = &quot;$Revision$&quot;[11:-2]
173
174import wx
175from wx import prefix
176
177from wxPython import html
178prefix.rename(d_new=globals(), d_old=html.__dict__)
179del html
180
181del prefix
182del 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&quot;&quot;&quot;Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
188
189__author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
190__cvsid__ = &quot;$Id$&quot;
191__revision__ = &quot;$Revision$&quot;[11:-2]
192
193import wx
194from wx import prefix
195
196from wxPython.lib import dialogs
197prefix.rename(d_new=globals(), d_old=dialogs.__dict__)
198del dialogs
199
200del prefix
201del 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
205defined in <tt class="literal"><span class="pre">prefix.py</span></tt>:</p>
206<pre class="literal-block">
207&quot;&quot;&quot;Renaming utility.
208
209Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
210
211__author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
212__cvsid__ = &quot;$Id$&quot;
213__revision__ = &quot;$Revision$&quot;[11:-2]
214
215import types
216
217def 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
238package.</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
243version 2.4.1 or higher. So all you have to do is:</p>
244<pre class="literal-block">
245import 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">
252from wxPython import wx
253</pre>
254<p>or:</p>
255<pre class="literal-block">
256from wxPython.wx import *
257</pre>
258<p>to:</p>
259<pre class="literal-block">
260import wx
261</pre>
262<p>Then you need to refer to wx attributes without a &quot;wx&quot; prefix, such
263as:</p>
264<pre class="literal-block">
265class MyFrame(wx.Frame):
266</pre>
267<p>In most cases, existing code can be modified with a simple search and
268replace.</p>
269<p>One extra issue you might run into when converting existing code is
270that the wx.__version__ attribute is no longer available, since the
271new wx namespace doesn't include any private attributes from the old
272wxPython.wx namespace. The solution is to use the wx.VERSION_STRING
273attribute, 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
278directory, and are documented in the <a class="reference" href="wxPythonExamples.html">wxPythonExamples</a> documentation
279file. Also, all the code in the py package uses the new wx syntax.
280You 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>.
286Generated on: 2003-06-04 18:07 UTC.
287Generated 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>