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.4: 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 <style type="text/css">
  13
  14 /*
  15 :Author: David Goodger
  16 :Contact: goodger@users.sourceforge.net
  17 :Date: $Date$
  18 :Revision: $Revision$
  19 :Copyright: This stylesheet has been placed in the public domain.
  20
  21 Default cascading style sheet for the HTML output of Docutils.
  22
  23 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  24 customize this style sheet.
  25 */
  26
  27 /* used to remove borders from tables and images */
  28 .borderless, table.borderless td, table.borderless th {
  29   border: 0 }
  30
  31 table.borderless td, table.borderless th {
  32   /* Override padding for "table.docutils td" with "! important".
  33      The right padding separates the table cells. */
  34   padding: 0 0.5em 0 0 ! important }
  35
  36 .first {
  37   /* Override more specific margin styles with "! important". */
  38   margin-top: 0 ! important }
  39
  40 .last, .with-subtitle {
  41   margin-bottom: 0 ! important }
  42
  43 .hidden {
  44   display: none }
  45
  46 a.toc-backref {
  47   text-decoration: none ;
  48   color: black }
  49
  50 blockquote.epigraph {
  51   margin: 2em 5em ; }
  52
  53 dl.docutils dd {
  54   margin-bottom: 0.5em }
  55
  56 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  57 dl.docutils dt {
  58   font-weight: bold }
  59 */
  60
  61 div.abstract {
  62   margin: 2em 5em }
  63
  64 div.abstract p.topic-title {
  65   font-weight: bold ;
  66   text-align: center }
  67
  68 div.admonition, div.attention, div.caution, div.danger, div.error,
  69 div.hint, div.important, div.note, div.tip, div.warning {
  70   margin: 2em ;
  71   border: medium outset ;
  72   padding: 1em }
  73
  74 div.admonition p.admonition-title, div.hint p.admonition-title,
  75 div.important p.admonition-title, div.note p.admonition-title,
  76 div.tip p.admonition-title {
  77   font-weight: bold ;
  78   font-family: sans-serif }
  79
  80 div.attention p.admonition-title, div.caution p.admonition-title,
  81 div.danger p.admonition-title, div.error p.admonition-title,
  82 div.warning p.admonition-title {
  83   color: red ;
  84   font-weight: bold ;
  85   font-family: sans-serif }
  86
  87 /* Uncomment (and remove this text!) to get reduced vertical space in
  88    compound paragraphs.
  89 div.compound .compound-first, div.compound .compound-middle {
  90   margin-bottom: 0.5em }
  91
  92 div.compound .compound-last, div.compound .compound-middle {
  93   margin-top: 0.5em }
  94 */
  95
  96 div.dedication {
  97   margin: 2em 5em ;
  98   text-align: center ;
  99   font-style: italic }
 100
 101 div.dedication p.topic-title {
 102   font-weight: bold ;
 103   font-style: normal }
 104
 105 div.figure {
 106   margin-left: 2em ;
 107   margin-right: 2em }
 108
 109 div.footer, div.header {
 110   clear: both;
 111   font-size: smaller }
 112
 113 div.line-block {
 114   display: block ;
 115   margin-top: 1em ;
 116   margin-bottom: 1em }
 117
 118 div.line-block div.line-block {
 119   margin-top: 0 ;
 120   margin-bottom: 0 ;
 121   margin-left: 1.5em }
 122
 123 div.sidebar {
 124   margin-left: 1em ;
 125   border: medium outset ;
 126   padding: 1em ;
 127   background-color: #ffffee ;
 128   width: 40% ;
 129   float: right ;
 130   clear: right }
 131
 132 div.sidebar p.rubric {
 133   font-family: sans-serif ;
 134   font-size: medium }
 135
 136 div.system-messages {
 137   margin: 5em }
 138
 139 div.system-messages h1 {
 140   color: red }
 141
 142 div.system-message {
 143   border: medium outset ;
 144   padding: 1em }
 145
 146 div.system-message p.system-message-title {
 147   color: red ;
 148   font-weight: bold }
 149
 150 div.topic {
 151   margin: 2em }
 152
 153 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 154 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 155   margin-top: 0.4em }
 156
 157 h1.title {
 158   text-align: center }
 159
 160 h2.subtitle {
 161   text-align: center }
 162
 163 hr.docutils {
 164   width: 75% }
 165
 166 img.align-left {
 167   clear: left }
 168
 169 img.align-right {
 170   clear: right }
 171
 172 ol.simple, ul.simple {
 173   margin-bottom: 1em }
 174
 175 ol.arabic {
 176   list-style: decimal }
 177
 178 ol.loweralpha {
 179   list-style: lower-alpha }
 180
 181 ol.upperalpha {
 182   list-style: upper-alpha }
 183
 184 ol.lowerroman {
 185   list-style: lower-roman }
 186
 187 ol.upperroman {
 188   list-style: upper-roman }
 189
 190 p.attribution {
 191   text-align: right ;
 192   margin-left: 50% }
 193
 194 p.caption {
 195   font-style: italic }
 196
 197 p.credits {
 198   font-style: italic ;
 199   font-size: smaller }
 200
 201 p.label {
 202   white-space: nowrap }
 203
 204 p.rubric {
 205   font-weight: bold ;
 206   font-size: larger ;
 207   color: maroon ;
 208   text-align: center }
 209
 210 p.sidebar-title {
 211   font-family: sans-serif ;
 212   font-weight: bold ;
 213   font-size: larger }
 214
 215 p.sidebar-subtitle {
 216   font-family: sans-serif ;
 217   font-weight: bold }
 218
 219 p.topic-title {
 220   font-weight: bold }
 221
 222 pre.address {
 223   margin-bottom: 0 ;
 224   margin-top: 0 ;
 225   font-family: serif ;
 226   font-size: 100% }
 227
 228 pre.literal-block, pre.doctest-block {
 229   margin-left: 2em ;
 230   margin-right: 2em ;
 231   background-color: #eeeeee }
 232
 233 span.classifier {
 234   font-family: sans-serif ;
 235   font-style: oblique }
 236
 237 span.classifier-delimiter {
 238   font-family: sans-serif ;
 239   font-weight: bold }
 240
 241 span.interpreted {
 242   font-family: sans-serif }
 243
 244 span.option {
 245   white-space: nowrap }
 246
 247 span.pre {
 248   white-space: pre }
 249
 250 span.problematic {
 251   color: red }
 252
 253 span.section-subtitle {
 254   /* font-size relative to parent (h1..h6 element) */
 255   font-size: 80% }
 256
 257 table.citation {
 258   border-left: solid 1px gray;
 259   margin-left: 1px }
 260
 261 table.docinfo {
 262   margin: 2em 4em }
 263
 264 table.docutils {
 265   margin-top: 0.5em ;
 266   margin-bottom: 0.5em }
 267
 268 table.footnote {
 269   border-left: solid 1px black;
 270   margin-left: 1px }
 271
 272 table.docutils td, table.docutils th,
 273 table.docinfo td, table.docinfo th {
 274   padding-left: 0.5em ;
 275   padding-right: 0.5em ;
 276   vertical-align: top }
 277
 278 table.docutils th.field-name, table.docinfo th.docinfo-name {
 279   font-weight: bold ;
 280   text-align: left ;
 281   white-space: nowrap ;
 282   padding-left: 0 }
 283
 284 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 285 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 286   font-size: 100% }
 287
 288 tt.docutils {
 289   background-color: #eeeeee }
 290
 291 ul.auto-toc {
 292   list-style-type: none }
 293
 294 </style>
 295 </head>
 296 <body>
 297 <div class="document" id="the-wxpython-wx-package">
 298 <h1 class="title">The wxPython wx Package</h1>
 299 <h2 class="subtitle" id="or-how-to-survive-the-new-wx-namespace-changes">Or, how to survive the new wx namespace changes.</h2>
 300 <table class="docinfo" frame="void" rules="none">
 301 <col class="docinfo-name" />
 302 <col class="docinfo-content" />
 303 <tbody valign="top">
 304 <tr><th class="docinfo-name">Author:</th>
 305 <td>Patrick K. O'Brien</td></tr>
 306 <tr><th class="docinfo-name">Author:</th>
 307 <td>Robin Dunn</td></tr>
 308 <tr><th class="docinfo-name">Contact:</th>
 309 <td><a class="first last reference" href="mailto:pobrien&#64;orbtech.com">pobrien&#64;orbtech.com</a></td></tr>
 310 <tr><th class="docinfo-name">Organization:</th>
 311 <td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr>
 312 <tr><th class="docinfo-name">Date:</th>
 313 <td>2004-03-26</td></tr>
 314 <tr><th class="docinfo-name">Revision:</th>
 315 <td>1.4</td></tr>
 316 </tbody>
 317 </table>
 318 <div class="contents topic">
 319 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
 320 <ul class="simple">
 321 <li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li>
 322 <li><a class="reference" href="#why-change-anything" id="id3" name="id3">Why change anything?</a></li>
 323 <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>
 324 <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>
 325 <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>
 326 <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>
 327 <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>
 328 <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>
 329 </ul>
 330 </div>
 331 <div class="section">
 332 <h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1>
 333 <p>In the begining there was Python, and Python had modules, and Python
 334 was good.  But after a time Guido looked on Python and saw that Python
 335 needed organizational assistance, and so Guido took code from Python's
 336 side and created Packages and then Python was very good.  About this
 337 time wxPython was reborn, and wxPython used Packages, but being young
 338 and trying to use a new technology wxPython did not know how to use
 339 Packages effectivly.  wxPython was good, but dreamed of being much
 340 better...</p>
 341 <p>Now many years later, after tons of code reorganization and build
 342 hacking wxPython has reached that goal.  In version 2.4.1 a prototype
 343 of this new structure was introduced that dynamically built at import
 344 time a new toplevel package named simply &quot;wx&quot; that contained all the
 345 items from wxPython.wx but with the names edited to remove the wx
 346 prefix.  Now in 2.5 the final phase of that switcheroo has been
 347 completed and the <em>real</em> classes, functions and constants are now
 348 located in the wx package, leaving some compatibility modules in
 349 wxPython.wx.  This document should answer all the questions you might
 350 have concerning the new wx package.  Please also take a look at the
 351 <a class="reference" href="MigrationGuide.html">2.5 Migration Guide</a> to see notes about other big differences in
 352 this release.</p>
 353 </div>
 354 <div class="section">
 355 <h1><a class="toc-backref" href="#id3" id="why-change-anything" name="why-change-anything">Why change anything?</a></h1>
 356 <p>This change is being made for a couple of reasons.  The first reason
 357 is to discourage the use of <tt class="docutils literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous
 358 technique that can create name conflicts and bloated namespaces.</p>
 359 <p>The second reason is to remove what some perceive to be a &quot;wart.&quot;  For
 360 example, the following code is rather ugly in that the &quot;wx&quot; prefix on
 361 the wxFrame class name is no longer useful when you're using the wx
 362 module prefix:</p>
 363 <pre class="literal-block">
 364 from wxPython import wx
 365
 366 class Frame(wx.wxFrame)
 367 </pre>
 368 <p>The new wx package allows you to write code like this, instead:</p>
 369 <pre class="literal-block">
 370 import wx
 371
 372 class Frame(wx.Frame)
 373 </pre>
 374 <p>The third reason is that the wxWindows project has considered doing
 375 the same thing (implement a new wx namespace and drop the &quot;wx&quot; prefix)
 376 and we want wxPython to lead the way.</p>
 377 </div>
 378 <div class="section">
 379 <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>
 380 <p>As mentioned in the Introduction, wxPython 2.4.1 introduced a way of
 381 getting to this new syntax as quickly as possible.  It would import
 382 the old names (like &quot;wxFrame&quot;) from the old package and then create new
 383 names in the wx package  without the wx prefix, (like &quot;Frame&quot;.)
 384 Starting with wxPython 2.5 the renaming is moved up to the wxPython
 385 build step, so the real classes and etc. are actually named with the
 386 new name (like &quot;Frame&quot;) and are located in the new wx package.</p>
 387 <p>For compatibility the old wxPython package still exists, but now it is
 388 populated with modules that simply import the new names and then
 389 &quot;reverse-renames&quot; them to the old names.  It probably sounds a bit
 390 complicated, but it is mostly automated and so it  doesn't cause
 391 problems in most cases.</p>
 392 </div>
 393 <div class="section">
 394 <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>
 395 <p>No.  Your existing code will continue to work and be supported for
 396 some time.  It will be up to you to decide when to switch to the new
 397 syntax.  But all new documentation and code examples will use the new
 398 syntax.  So don't wait too long.  You wouldn't want anyone calling you
 399 old-fashioned, would you?</p>
 400 <p>When you import from wxPython.wx and use a class with the old name,
 401 such as wxButton, you are actually using the wx.Button class.  I
 402 expect that the vast majority of the existing code should work fine
 403 using this scheme.  The only things that may cause problems is if your
 404 old code is depending on some of the implemtation details, or if you
 405 are using other things that have changed in the API.  See the
 406 <a class="reference" href="MigrationGuide.html">Migration Guide</a> for more details.</p>
 407 </div>
 408 <div class="section">
 409 <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>
 410 <p>There's more to the old wxPython than just the wxPython.wx module.
 411 And we've got those extra modules covered as well.  Each of those
 412 modules (as well as the lib subpackage) has been moved to the new wx
 413 package and reverse-renamers have been placed in the wxPython package
 414 as needed.</p>
 415 </div>
 416 <div class="section">
 417 <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>
 418 <p>The wx package is automatically created when you install wxPython
 419 version 2.4.1 or higher.  So all you have to do is:</p>
 420 <pre class="literal-block">
 421 import wx
 422 </pre>
 423 </div>
 424 <div class="section">
 425 <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>
 426 <p>Obviously, you need to change your import statements from:</p>
 427 <pre class="literal-block">
 428 from wxPython import wx
 429 </pre>
 430 <p>or:</p>
 431 <pre class="literal-block">
 432 from wxPython.wx import *
 433 </pre>
 434 <p>to:</p>
 435 <pre class="literal-block">
 436 import wx
 437 </pre>
 438 <p>Then you need to refer to wx attributes without a &quot;wx&quot; prefix, such
 439 as:</p>
 440 <pre class="literal-block">
 441 class MyFrame(wx.Frame):
 442 </pre>
 443 <p>In most cases, existing code can be modified with a simple search and
 444 replace.</p>
 445 </div>
 446 <div class="section">
 447 <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>
 448 <p>The wxPython demo application and most of the sample apps have been
 449 converted to use the new <tt class="docutils literal"><span class="pre">import</span> <span class="pre">wx</span></tt> style of programming with
 450 wxPython, so there are lots of examples to look at and to play with.
 451 Here is one of them, it is the <tt class="docutils literal"><span class="pre">simple</span></tt> sample.</p>
 452 <pre class="literal-block">
 453 #----------------------------------------------------------------------
 454 # A very simple wxPython example.  Just a wx.Frame, wx.Panel,
 455 # wx.StaticText, wx.Button, and a wx.BoxSizer, but it shows the basic
 456 # structure of any wxPython application.
 457 #----------------------------------------------------------------------
 458
 459 import wx
 460
 461
 462 class MyFrame(wx.Frame):
 463     &quot;&quot;&quot;
 464     This is MyFrame.  It just shows a few controls on a wxPanel,
 465     and has a simple menu.
 466     &quot;&quot;&quot;
 467     def __init__(self, parent, title):
 468         wx.Frame.__init__(self, parent, -1, title,
 469                           pos=(150, 150), size=(350, 200))
 470
 471         # Create the menubar
 472         menuBar = wx.MenuBar()
 473
 474         # and a menu
 475         menu = wx.Menu()
 476
 477         # add an item to the menu, using \tKeyName automatically
 478         # creates an accelerator, the third param is some help text
 479         # that will show up in the statusbar
 480         menu.Append(wx.ID_EXIT, &quot;E&amp;xit\tAlt-X&quot;, &quot;Exit this simple sample&quot;)
 481
 482         # bind the menu event to an event handler
 483         self.Bind(wx.EVT_MENU, self.OnTimeToClose, id=wx.ID_EXIT)
 484
 485         # and put the menu on the menubar
 486         menuBar.Append(menu, &quot;&amp;File&quot;)
 487         self.SetMenuBar(menuBar)
 488
 489         self.CreateStatusBar()
 490
 491
 492         # Now create the Panel to put the other controls on.
 493         panel = wx.Panel(self)
 494
 495         # and a few controls
 496         text = wx.StaticText(panel, -1, &quot;Hello World!&quot;)
 497         text.SetFont(wx.Font(14, wx.SWISS, wx.NORMAL, wx.BOLD))
 498         text.SetSize(text.GetBestSize())
 499         btn = wx.Button(panel, -1, &quot;Close&quot;)
 500         funbtn = wx.Button(panel, -1, &quot;Just for fun...&quot;)
 501
 502         # bind the button events to handlers
 503         self.Bind(wx.EVT_BUTTON, self.OnTimeToClose, btn)
 504         self.Bind(wx.EVT_BUTTON, self.OnFunButton, funbtn)
 505
 506         # Use a sizer to layout the controls, stacked vertically and with
 507         # a 10 pixel border around each
 508         sizer = wx.BoxSizer(wx.VERTICAL)
 509         sizer.Add(text, 0, wx.ALL, 10)
 510         sizer.Add(btn, 0, wx.ALL, 10)
 511         sizer.Add(funbtn, 0, wx.ALL, 10)
 512         panel.SetSizer(sizer)
 513         panel.Layout()
 514
 515
 516     def OnTimeToClose(self, evt):
 517         &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
 518         print &quot;See ya later!&quot;
 519         self.Close()
 520
 521     def OnFunButton(self, evt):
 522         &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
 523         print &quot;Having fun yet?&quot;
 524
 525
 526 class MyApp(wx.App):
 527     def OnInit(self):
 528         frame = MyFrame(None, &quot;Simple wxPython App&quot;)
 529         self.SetTopWindow(frame)
 530
 531         print &quot;Print statements go to this stdout window by default.&quot;
 532
 533         frame.Show(True)
 534         return True
 535
 536 app = MyApp(redirect=True)
 537 app.MainLoop()
 538
 539
 540 </pre>
 541 </div>
 542 </div>
 543 </body>
 544 </html>