New documentation directory.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@20357 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
144
wxPython/docs/wxPackage.txt
Normal file
144
wxPython/docs/wxPackage.txt
Normal file
@@ -0,0 +1,144 @@
|
||||
=========================
|
||||
The wxPython wx Package
|
||||
=========================
|
||||
|
||||
--------------------------------------------------
|
||||
Or, how to survive the new wx namespace changes.
|
||||
--------------------------------------------------
|
||||
|
||||
:Author: Patrick K. O'Brien
|
||||
:Contact: pobrien@orbtech.com
|
||||
:Date: $Date$
|
||||
:Revision: $Revision$
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
.. Add a link to wxExamples.html
|
||||
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Big things sometimes come in small packages. This is certainly true
|
||||
of the new wx package, which is being introduced as a transition to
|
||||
allow the "wx" prefix to be dropped from the names of all wxPython
|
||||
classes, functions, and constants.
|
||||
|
||||
|
||||
Why change anything?
|
||||
====================
|
||||
|
||||
This change is being made for a couple of reasons. The first reason
|
||||
is to discourage the use of ``import *``, which is a dangerous
|
||||
technique that can create name conflicts and bloated namespaces.
|
||||
|
||||
The second reason is to remove what some perceive to be a "wart." For
|
||||
example, the following code is rather ugly in that the "wx" prefix on
|
||||
the wxFrame class name is no longer useful when you're using the wx
|
||||
module prefix::
|
||||
|
||||
from wxPython import wx
|
||||
|
||||
class Frame(wx.wxFrame)
|
||||
|
||||
The new wx package allows you to write code like this, instead::
|
||||
|
||||
import wx
|
||||
|
||||
class Frame(wx.Frame)
|
||||
|
||||
The third reason is that the wxWindows project intends to do the same
|
||||
thing (implement a new wx namespace and drop the "wx" prefix) and we
|
||||
want wxPython to lead the way.
|
||||
|
||||
|
||||
What does the new wx package do?
|
||||
================================
|
||||
|
||||
As a way of getting to this new syntax as quickly as possible, the
|
||||
code in this new wx package was created. What it does is alter the
|
||||
existing wx namespace dynamically. By making the changes on-the-fly
|
||||
at runtime, we can try out the new syntax before any permanent changes
|
||||
are made to the underlying class library. The downside of making
|
||||
these changes at runtime is that there is a slight delay when you
|
||||
``import wx``; the upside is that you can start using the new syntax
|
||||
now.
|
||||
|
||||
|
||||
Will any of this effect my existing code?
|
||||
=========================================
|
||||
|
||||
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?
|
||||
|
||||
|
||||
How does the new wx package work?
|
||||
=================================
|
||||
|
||||
It's pretty simple, and pretty clever. The wx directory contains an
|
||||
``__init__.py`` file, making it a Python package. (In contrast, the
|
||||
old wxPython.wx module is a module, not a package.) When you ``import
|
||||
wx`` the code in the ``__init__.py`` file is executed, and that's
|
||||
where all the magic takes place. Let's take a look at the code inside
|
||||
the ``__init__.py`` file:
|
||||
|
||||
.. include:: ../wx/__init__.py
|
||||
:literal:
|
||||
|
||||
Namespaces in Python are implemented as dictionaries. The dictionary
|
||||
used to create the wx package's namespace is accessible using the
|
||||
``globals()`` function. The dictionary used to create the old
|
||||
wxPython.wx module's namespace is ``wx.__dict__``. Once we have these
|
||||
two dictionaries, it's a simple matter of iterating through one,
|
||||
changing the names, adding the renamed object to the other dictionary,
|
||||
and cleaning up a few local variables and imported modules. Voila!
|
||||
|
||||
|
||||
What about all the other modules, like grid, html, and stc?
|
||||
===========================================================
|
||||
|
||||
There's more to wxPython than just the wx namespace. And we've got
|
||||
those extra modules covered as well. For each of those modules (as
|
||||
well as the lib package) we've got matching modules in the new wx
|
||||
package. Let's take a look at a few of them.
|
||||
|
||||
Here is ``html.py``:
|
||||
|
||||
.. include:: ../wx/html.py
|
||||
:literal:
|
||||
|
||||
And here is ``lib/dialogs.py``:
|
||||
|
||||
.. include:: ../wx/lib/dialogs.py
|
||||
:literal:
|
||||
|
||||
As you can see, they both rely on the ``prefix.rename()`` function
|
||||
defined in ``prefix.py``:
|
||||
|
||||
.. include:: ../wx/prefix.py
|
||||
:literal:
|
||||
|
||||
Again, the technique is very similar to the one used by the wx
|
||||
package.
|
||||
|
||||
|
||||
How do I use it?
|
||||
================
|
||||
|
||||
The wx package is created when you install wxPython. So you can start
|
||||
using it now. Examples are included in the wx/examples directory,
|
||||
which includes an examples.txt documentation file. Here is the source
|
||||
code for ``hello.py``, a simple program that displays a wxPython
|
||||
graphic inside a frame:
|
||||
|
||||
.. include:: ../samples/wx_examples/hello/hello.py
|
||||
:literal:
|
||||
|
||||
Good luck. I hope you like the new wx package as much as I do.
|
||||
|
||||
Pat
|
Reference in New Issue
Block a user