wxPython/docs/wxPackage.html

   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.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" id="contents">
  37 <p class="topic-title"><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 &quot;wx&quot; 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="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 &quot;wart.&quot;  For
  78 example, the following code is rather ugly in that the &quot;wx&quot; 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 &quot;wx&quot; 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 &quot;wxFrame&quot;) from the old package and then create new
 101 names in the wx package  without the wx prefix, (like &quot;Frame&quot;.)
 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 &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
 106 populated 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
 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 &quot;wx&quot; 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="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="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     &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
 244 class 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
 254 app = MyApp(redirect=True)
 255 app.MainLoop()
 256
 257
 258 </pre>
 259 </div>
 260 </div>
 261 </body>
 262 </html>