Use TranslateAccelerator so that TAB, Return, etc. keys are properly processed by...

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

diff --git a/wxPython/docs/wxPackage.txt b/wxPython/docs/wxPackage.txt
index 6c68831424e1302dd47995e016d54fe026d58794..35e6e0b64e1e4ff01b749b9784bfbb4076fe156f 100644 (file)
--- a/wxPython/docs/wxPackage.txt
+++ b/wxPython/docs/wxPackage.txt
@@ -7,6 +7,7 @@
 --------------------------------------------------
 
 :Author: Patrick K. O'Brien
 --------------------------------------------------
 
 :Author: Patrick K. O'Brien

+:Author: Robin Dunn

 :Contact: pobrien@orbtech.com
 :Organization: Orbtech_
 :Date: $Date$
 :Contact: pobrien@orbtech.com
 :Organization: Orbtech_
 :Date: $Date$


@@ -20,14 +21,29 @@
 Introduction
 ============
 
 Introduction
 ============
 

-Big things sometimes come in small packages.  This is certainly true
-of the new wx package, which is being introduced in wxPython 2.4.1 as
-a way to allow the "wx" prefix to be dropped from the names of all
-wxPython classes, functions, and constants.  This document should
-answer all the questions you might have concerning the new wx package.
-If not, feel free to contact the author.  I hope you like the new wx
-package as much as I do.
-
+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...
+
+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 "wx" 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 *real* 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
+`2.5 Migration Guide`_ to see notes about other big differences in
+this release.
+
+.. _2.5 Migration Guide: MigrationGuide.html

 
 Why change anything?
 ====================
 
 Why change anything?
 ====================


@@ -51,22 +67,27 @@ The new wx package allows you to write code like this, instead::
 
     class Frame(wx.Frame)
 
 
     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.
+The third reason is that the wxWindows project has considered doing
+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?
 ================================
 
 
 
 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.
+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 "wxFrame") from the old package and then create new
+names in the wx package  without the wx prefix, (like "Frame".)
+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 "Frame") and are located in the new wx package.
+
+For compatibility the old wxPython package still exists, but now it is
+populated with modules that simply import the new names and then
+"reverse-renames" 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.

 
 
 Will any of this effect my existing code?
 
 
 Will any of this effect my existing code?


@@ -78,55 +99,25 @@ 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?
 
 syntax.  So don't wait too long.  You wouldn't want anyone calling you
 old-fashioned, would you?
 

+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
+`Migration Guide`_ for more details.

 
 

-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!
+.. _Migration Guide: MigrationGuide.html

 
 
 What about all the other modules, like grid, html, and stc?
 ===========================================================
 
 
 
 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.
+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.

 
 
 How do I use this new wx package?
 
 
 How do I use this new wx package?


@@ -161,20 +152,17 @@ as::
 In most cases, existing code can be modified with a simple search and
 replace.
 
 In most cases, existing code can be modified with a simple search and
 replace.
 

-One extra issue you might run into when converting existing code is
-that the wx.__version__ attribute is no longer available, since the
-new wx namespace doesn't include any private attributes from the old
-wxPython.wx namespace.  The solution is to use the wx.VERSION_STRING
-attribute, which was introduced in wxPython 2.4.1.

 
 
 Where can I find example programs using the new wx syntax?
 ==========================================================
 
 
 
 Where can I find example programs using the new wx syntax?
 ==========================================================
 

-Example programs are included in the wxPython/samples/wx_examples
-directory, and are documented in the wxPythonExamples_ documentation
-file.  Also, all the code in the py package uses the new wx syntax.
-You can learn more about these in the PyManual_.
+The wxPython demo application and most of the sample apps have been
+converted to use the new ``import wx`` 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 ``simple`` sample.
+
+
+.. include:: ../samples/simple/simple.py
+   :literal:

 
 

-.. _wxPythonExamples: wxPythonExamples.html
-.. _PyManual: PyManual.html