]> git.saurik.com Git - wxWidgets.git/blame_incremental - wxPython/docs/wxPackage.html
fixed deadlock when calling wxPostEvent() from worker thread
[wxWidgets.git] / wxPython / docs / wxPackage.html
... / ...
CommitLineData
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.4.1: 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&#64;orbtech.com">pobrien&#64;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">
37<p class="topic-title first"><a id="contents" 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">
50<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1>
51<p>In the begining there was Python, and Python had modules, and Python
52was good. But after a time Guido looked on Python and saw that Python
53needed organizational assistance, and so Guido took code from Python's
54side and created Packages and then Python was very good. About this
55time wxPython was reborn, and wxPython used Packages, but being young
56and trying to use a new technology wxPython did not know how to use
57Packages effectivly. wxPython was good, but dreamed of being much
58better...</p>
59<p>Now many years later, after tons of code reorganization and build
60hacking wxPython has reached that goal. In version 2.4.1 a prototype
61of this new structure was introduced that dynamically built at import
62time a new toplevel package named simply &quot;wx&quot; that contained all the
63items from wxPython.wx but with the names edited to remove the wx
64prefix. Now in 2.5 the final phase of that switcheroo has been
65completed and the <em>real</em> classes, functions and constants are now
66located in the wx package, leaving some compatibility modules in
67wxPython.wx. This document should answer all the questions you might
68have 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
70this release.</p>
71</div>
72<div class="section">
73<h1><a class="toc-backref" href="#id3" id="why-change-anything" name="why-change-anything">Why change anything?</a></h1>
74<p>This change is being made for a couple of reasons. The first reason
75is to discourage the use of <tt class="docutils literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous
76technique that can create name conflicts and bloated namespaces.</p>
77<p>The second reason is to remove what some perceive to be a &quot;wart.&quot; For
78example, the following code is rather ugly in that the &quot;wx&quot; prefix on
79the wxFrame class name is no longer useful when you're using the wx
80module prefix:</p>
81<pre class="literal-block">
82from wxPython import wx
83
84class 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">
88import wx
89
90class Frame(wx.Frame)
91</pre>
92<p>The third reason is that the wxWindows project has considered doing
93the same thing (implement a new wx namespace and drop the &quot;wx&quot; prefix)
94and we want wxPython to lead the way.</p>
95</div>
96<div class="section">
97<h1><a class="toc-backref" href="#id4" id="what-does-the-new-wx-package-do" 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
99getting to this new syntax as quickly as possible. It would import
100the old names (like &quot;wxFrame&quot;) from the old package and then create new
101names in the wx package without the wx prefix, (like &quot;Frame&quot;.)
102Starting with wxPython 2.5 the renaming is moved up to the wxPython
103build step, so the real classes and etc. are actually named with the
104new name (like &quot;Frame&quot;) and are located in the new wx package.</p>
105<p>For compatibility the old wxPython package still exists, but now it is
106populated with modules that simply import the new names and then
107&quot;reverse-renames&quot; them to the old names. It probably sounds a bit
108complicated, but it is mostly automated and so it doesn't cause
109problems in most cases.</p>
110</div>
111<div class="section">
112<h1><a class="toc-backref" href="#id5" id="will-any-of-this-effect-my-existing-code" 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
114some time. It will be up to you to decide when to switch to the new
115syntax. But all new documentation and code examples will use the new
116syntax. So don't wait too long. You wouldn't want anyone calling you
117old-fashioned, would you?</p>
118<p>When you import from wxPython.wx and use a class with the old name,
119such as wxButton, you are actually using the wx.Button class. I
120expect that the vast majority of the existing code should work fine
121using this scheme. The only things that may cause problems is if your
122old code is depending on some of the implemtation details, or if you
123are 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">
127<h1><a class="toc-backref" href="#id6" id="what-about-all-the-other-modules-like-grid-html-and-stc" 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.
129And we've got those extra modules covered as well. Each of those
130modules (as well as the lib subpackage) has been moved to the new wx
131package and reverse-renamers have been placed in the wxPython package
132as needed.</p>
133</div>
134<div class="section">
135<h1><a class="toc-backref" href="#id7" id="how-do-i-use-this-new-wx-package" 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
137version 2.4.1 or higher. So all you have to do is:</p>
138<pre class="literal-block">
139import wx
140</pre>
141</div>
142<div class="section">
143<h1><a class="toc-backref" href="#id8" id="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package" 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">
146from wxPython import wx
147</pre>
148<p>or:</p>
149<pre class="literal-block">
150from wxPython.wx import *
151</pre>
152<p>to:</p>
153<pre class="literal-block">
154import wx
155</pre>
156<p>Then you need to refer to wx attributes without a &quot;wx&quot; prefix, such
157as:</p>
158<pre class="literal-block">
159class MyFrame(wx.Frame):
160</pre>
161<p>In most cases, existing code can be modified with a simple search and
162replace.</p>
163</div>
164<div class="section">
165<h1><a class="toc-backref" href="#id9" id="where-can-i-find-example-programs-using-the-new-wx-syntax" 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
167converted to use the new <tt class="docutils literal"><span class="pre">import</span> <span class="pre">wx</span></tt> style of programming with
168wxPython, so there are lots of examples to look at and to play with.
169Here 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
177import wx
178
179
180class MyFrame(wx.Frame):
181 &quot;&quot;&quot;
182 This is MyFrame. It just shows a few controls on a wxPanel,
183 and has a simple menu.
184 &quot;&quot;&quot;
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, &quot;E&amp;xit\tAlt-X&quot;, &quot;Exit this simple sample&quot;)
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, &quot;&amp;File&quot;)
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, &quot;Hello World!&quot;)
215 text.SetFont(wx.Font(14, wx.SWISS, wx.NORMAL, wx.BOLD))
216 text.SetSize(text.GetBestSize())
217 btn = wx.Button(panel, -1, &quot;Close&quot;)
218 funbtn = wx.Button(panel, -1, &quot;Just for fun...&quot;)
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 &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
236 print &quot;See ya later!&quot;
237 self.Close()
238
239 def OnFunButton(self, evt):
240 &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
241 print &quot;Having fun yet?&quot;
242
243
244class MyApp(wx.App):
245 def OnInit(self):
246 frame = MyFrame(None, &quot;Simple wxPython App&quot;)
247 self.SetTopWindow(frame)
248
249 print &quot;Print statements go to this stdout window by default.&quot;
250
251 frame.Show(True)
252 return True
253
254app = MyApp(redirect=True)
255app.MainLoop()
256
257
258</pre>
259</div>
260</div>
261</body>
262</html>