[wxWidgets.git] / wxPython / docs / wxPackage.html

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>The wxPython wx Package</title>
<meta name="author" content="Patrick K. O'Brien" />
<meta name="author" content="Robin Dunn" />
<meta name="organization" content="Orbtech" />
<meta name="date" content="2004-03-26" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="the-wxpython-wx-package">
<h1 class="title">The wxPython wx Package</h1>
<h2 class="subtitle" id="or-how-to-survive-the-new-wx-namespace-changes">Or, how to survive the new wx namespace changes.</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Patrick K. O'Brien</td></tr>
<tr><th class="docinfo-name">Author:</th>
<td>Robin Dunn</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:pobrien&#64;orbtech.com">pobrien&#64;orbtech.com</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-03-26</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>1.4</td></tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li>
<li><a class="reference" href="#why-change-anything" id="id3" name="id3">Why change anything?</a></li>
<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>
<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>
<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>
<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>
<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>
<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>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1>
<p>In the begining there was Python, and Python had modules, and Python
was good.  But after a time Guido looked on Python and saw that Python
needed organizational assistance, and so Guido took code from Python's
side and created Packages and then Python was very good.  About this
time wxPython was reborn, and wxPython used Packages, but being young
and trying to use a new technology wxPython did not know how to use
Packages effectivly.  wxPython was good, but dreamed of being much
better...</p>
<p>Now many years later, after tons of code reorganization and build
hacking wxPython has reached that goal.  In version 2.4.1 a prototype
of this new structure was introduced that dynamically built at import
time a new toplevel package named simply &quot;wx&quot; that contained all the
items from wxPython.wx but with the names edited to remove the wx
prefix.  Now in 2.5 the final phase of that switcheroo has been
completed and the <em>real</em> classes, functions and constants are now
located in the wx package, leaving some compatibility modules in
wxPython.wx.  This document should answer all the questions you might
have concerning the new wx package.  Please also take a look at the
<a class="reference" href="MigrationGuide.html">2.5 Migration Guide</a> to see notes about other big differences in
this release.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="why-change-anything" name="why-change-anything">Why change anything?</a></h1>
<p>This change is being made for a couple of reasons.  The first reason
is to discourage the use of <tt class="docutils literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous
technique that can create name conflicts and bloated namespaces.</p>
<p>The second reason is to remove what some perceive to be a &quot;wart.&quot;  For
example, the following code is rather ugly in that the &quot;wx&quot; prefix on
the wxFrame class name is no longer useful when you're using the wx
module prefix:</p>
<pre class="literal-block">
from wxPython import wx

class Frame(wx.wxFrame)
</pre>
<p>The new wx package allows you to write code like this, instead:</p>
<pre class="literal-block">
import wx

class Frame(wx.Frame)
</pre>
<p>The third reason is that the wxWindows project has considered doing
the same thing (implement a new wx namespace and drop the &quot;wx&quot; prefix)
and we want wxPython to lead the way.</p>
</div>
<div class="section">
<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>
<p>As mentioned in the Introduction, wxPython 2.4.1 introduced a way of
getting to this new syntax as quickly as possible.  It would import
the old names (like &quot;wxFrame&quot;) from the old package and then create new
names in the wx package  without the wx prefix, (like &quot;Frame&quot;.)
Starting with wxPython 2.5 the renaming is moved up to the wxPython
build step, so the real classes and etc. are actually named with the
new name (like &quot;Frame&quot;) and are located in the new wx package.</p>
<p>For compatibility the old wxPython package still exists, but now it is
populated with modules that simply import the new names and then
&quot;reverse-renames&quot; them to the old names.  It probably sounds a bit
complicated, but it is mostly automated and so it  doesn't cause
problems in most cases.</p>
</div>
<div class="section">
<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>
<p>No.  Your existing code will continue to work and be supported for
some time.  It will be up to you to decide when to switch to the new
syntax.  But all new documentation and code examples will use the new
syntax.  So don't wait too long.  You wouldn't want anyone calling you
old-fashioned, would you?</p>
<p>When you import from wxPython.wx and use a class with the old name,
such as wxButton, you are actually using the wx.Button class.  I
expect that the vast majority of the existing code should work fine
using this scheme.  The only things that may cause problems is if your
old code is depending on some of the implemtation details, or if you
are using other things that have changed in the API.  See the
<a class="reference" href="MigrationGuide.html">Migration Guide</a> for more details.</p>
</div>
<div class="section">
<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>
<p>There's more to the old wxPython than just the wxPython.wx module.
And we've got those extra modules covered as well.  Each of those
modules (as well as the lib subpackage) has been moved to the new wx
package and reverse-renamers have been placed in the wxPython package
as needed.</p>
</div>
<div class="section">
<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>
<p>The wx package is automatically created when you install wxPython
version 2.4.1 or higher.  So all you have to do is:</p>
<pre class="literal-block">
import wx
</pre>
</div>
<div class="section">
<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>
<p>Obviously, you need to change your import statements from:</p>
<pre class="literal-block">
from wxPython import wx
</pre>
<p>or:</p>
<pre class="literal-block">
from wxPython.wx import *
</pre>
<p>to:</p>
<pre class="literal-block">
import wx
</pre>
<p>Then you need to refer to wx attributes without a &quot;wx&quot; prefix, such
as:</p>
<pre class="literal-block">
class MyFrame(wx.Frame):
</pre>
<p>In most cases, existing code can be modified with a simple search and
replace.</p>
</div>
<div class="section">
<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>
<p>The wxPython demo application and most of the sample apps have been
converted to use the new <tt class="docutils literal"><span class="pre">import</span> <span class="pre">wx</span></tt> style of programming with
wxPython, so there are lots of examples to look at and to play with.
Here is one of them, it is the <tt class="docutils literal"><span class="pre">simple</span></tt> sample.</p>
<pre class="literal-block">
#----------------------------------------------------------------------
# A very simple wxPython example.  Just a wx.Frame, wx.Panel,
# wx.StaticText, wx.Button, and a wx.BoxSizer, but it shows the basic
# structure of any wxPython application.
#----------------------------------------------------------------------

import wx


class MyFrame(wx.Frame):
    &quot;&quot;&quot;
    This is MyFrame.  It just shows a few controls on a wxPanel,
    and has a simple menu.
    &quot;&quot;&quot;
    def __init__(self, parent, title):
        wx.Frame.__init__(self, parent, -1, title,
                          pos=(150, 150), size=(350, 200))

        # Create the menubar
        menuBar = wx.MenuBar()

        # and a menu 
        menu = wx.Menu()

        # add an item to the menu, using \tKeyName automatically
        # creates an accelerator, the third param is some help text
        # that will show up in the statusbar
        menu.Append(wx.ID_EXIT, &quot;E&amp;xit\tAlt-X&quot;, &quot;Exit this simple sample&quot;)

        # bind the menu event to an event handler
        self.Bind(wx.EVT_MENU, self.OnTimeToClose, id=wx.ID_EXIT)

        # and put the menu on the menubar
        menuBar.Append(menu, &quot;&amp;File&quot;)
        self.SetMenuBar(menuBar)

        self.CreateStatusBar()
        

        # Now create the Panel to put the other controls on.
        panel = wx.Panel(self)

        # and a few controls
        text = wx.StaticText(panel, -1, &quot;Hello World!&quot;)
        text.SetFont(wx.Font(14, wx.SWISS, wx.NORMAL, wx.BOLD))
        text.SetSize(text.GetBestSize())
        btn = wx.Button(panel, -1, &quot;Close&quot;)
        funbtn = wx.Button(panel, -1, &quot;Just for fun...&quot;)

        # bind the button events to handlers
        self.Bind(wx.EVT_BUTTON, self.OnTimeToClose, btn)
        self.Bind(wx.EVT_BUTTON, self.OnFunButton, funbtn)

        # Use a sizer to layout the controls, stacked vertically and with
        # a 10 pixel border around each
        sizer = wx.BoxSizer(wx.VERTICAL)
        sizer.Add(text, 0, wx.ALL, 10)
        sizer.Add(btn, 0, wx.ALL, 10)
        sizer.Add(funbtn, 0, wx.ALL, 10)
        panel.SetSizer(sizer)
        panel.Layout()


    def OnTimeToClose(self, evt):
        &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
        print &quot;See ya later!&quot;
        self.Close()

    def OnFunButton(self, evt):
        &quot;&quot;&quot;Event handler for the button click.&quot;&quot;&quot;
        print &quot;Having fun yet?&quot;


class MyApp(wx.App):
    def OnInit(self):
        frame = MyFrame(None, &quot;Simple wxPython App&quot;)
        self.SetTopWindow(frame)

        print &quot;Print statements go to this stdout window by default.&quot;

        frame.Show(True)
        return True
        
app = MyApp(redirect=True)
app.MainLoop()


</pre>
</div>
</div>
</body>
</html>
Commit	Line	Data
8eda5e35 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" />
974a50f1	6	<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8eda5e35 RD	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" />
7fa23c09	11	<meta name="date" content="2004-03-26" />
974a50f1 RD	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>
8eda5e35 RD	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@orbtech.com">pobrien@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>
7fa23c09	313	<td>2004-03-26</td></tr>
8eda5e35	314	<tr><th class="docinfo-name">Revision:</th>
7fa23c09	315	<td>1.4</td></tr>
8eda5e35 RD	316	</tbody>
8eda5e35 RD	317	</table>
974a50f1 RD	318	<div class="contents topic">
974a50f1 RD	319	<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
8eda5e35 RD	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>
974a50f1 RD	331	<div class="section">
974a50f1 RD	332	<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1>
8eda5e35 RD	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 "wx" 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>
974a50f1 RD	354	<div class="section">
974a50f1 RD	355	<h1><a class="toc-backref" href="#id3" id="why-change-anything" name="why-change-anything">Why change anything?</a></h1>
8eda5e35	356	<p>This change is being made for a couple of reasons. The first reason
c66cd08a	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
8eda5e35 RD	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 "wart." For
	360	example, the following code is rather ugly in that the "wx" 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 "wx" prefix)
	376	and we want wxPython to lead the way.</p>
	377	</div>
974a50f1 RD	378	<div class="section">
974a50f1 RD	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>
8eda5e35 RD	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 "wxFrame") from the old package and then create new
	383	names in the wx package without the wx prefix, (like "Frame".)
	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 "Frame") 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	"reverse-renames" 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>
974a50f1 RD	393	<div class="section">
974a50f1 RD	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>
8eda5e35 RD	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>
974a50f1 RD	408	<div class="section">
974a50f1 RD	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>
8eda5e35 RD	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>
974a50f1 RD	416	<div class="section">
974a50f1 RD	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>
8eda5e35 RD	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>
974a50f1 RD	424	<div class="section">
974a50f1 RD	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>
8eda5e35 RD	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 "wx" 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>
974a50f1 RD	446	<div class="section">
974a50f1 RD	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>
90805926	448	<p>The wxPython demo application and most of the sample apps have been
c66cd08a	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
90805926	450	wxPython, so there are lots of examples to look at and to play with.
c66cd08a	451	Here is one of them, it is the <tt class="docutils literal"><span class="pre">simple</span></tt> sample.</p>
90805926 RD	452	<pre class="literal-block">
90805926 RD	453	#----------------------------------------------------------------------
60b517c1 RD	454	# A very simple wxPython example. Just a wx.Frame, wx.Panel,
60b517c1 RD	455	# wx.StaticText, wx.Button, and a wx.BoxSizer, but it shows the basic
90805926 RD	456	# structure of any wxPython application.
	457	#----------------------------------------------------------------------
	458
	459	import wx
	460
	461
	462	class MyFrame(wx.Frame):
	463	"""
	464	This is MyFrame. It just shows a few controls on a wxPanel,
	465	and has a simple menu.
	466	"""
	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, "E&xit\tAlt-X", "Exit this simple sample")
	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, "&File")
	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, "Hello World!")
	497	text.SetFont(wx.Font(14, wx.SWISS, wx.NORMAL, wx.BOLD))
	498	text.SetSize(text.GetBestSize())
	499	btn = wx.Button(panel, -1, "Close")
	500	funbtn = wx.Button(panel, -1, "Just for fun...")
	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	"""Event handler for the button click."""
	518	print "See ya later!"
	519	self.Close()
520
521	def OnFunButton(self, evt):
522	"""Event handler for the button click."""
523	print "Having fun yet?"
524
525
526	class MyApp(wx.App):
527	def OnInit(self):
528	frame = MyFrame(None, "Simple wxPython App")
90805926	529	self.SetTopWindow(frame)
60b517c1 RD	530
	531	print "Print statements go to this stdout window by default."
	532
	533	frame.Show(True)
90805926 RD	534	return True
90805926 RD	535
60b517c1	536	app = MyApp(redirect=True)
90805926 RD	537	app.MainLoop()
	538
	539
	540	</pre>
8eda5e35 RD	541	</div>
8eda5e35 RD	542	</div>
8eda5e35 RD	543	</body>
8eda5e35 RD	544	</html>