wxPython Merge #2 of 2.4 branch --> HEAD (branch tag: wxPy_2_4_merge_2)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@21593 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/docs/wxPythonExamples.txt

@@ -0,0 +1,118 @@
+=================================
+ Example Programs Using wxPython
+=================================
+
+--------------------------------------------------
+ A survival guide for the post-wx-prefixed world.
+--------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Organization: Orbtech_
+:Date: $Date$
+:Revision: $Revision$
+
+.. _Orbtech: http://www.orbtech.com/
+
+.. contents::
+
+
+Introduction
+============
+
+This document illustrates example programs using wxPython.  All the
+examples make use of the new wx package syntax introduced in wxPython
+2.4.1, which is a bit different than older examples you might come
+across.
+
+
+Background (with tongue firmly in cheek)
+========================================
+
+If something hits you on the head, don't run around screaming that the
+sky is falling.  Instead, take a close look and see if it wasn't a
+"wx" prefix that hit you.  Apparently, they're dropping off wxPython
+class names like flies dropping dead in the scorching heat of a
+summer's day.
+
+Yes, the world is changing, and even our little wxPython world must
+change with it.  Then again, I'm not fond of pesky summertime flies,
+and I'm not too upset that the "wx" prefixes are going to bite the
+dust.  I think it's for the best.  But, being the kind, considerate
+person that I am, I decided to write this guide to make the wx
+namespace transition easier for everyone, even Chicken Little.
+
+.. note:: Say what?
+
+   If you have no idea what I mean by the "wx namespace transition,"
+   consider yourself lucky.  You can simply use these examples to
+   learn wxPython in its current state (beginning with wxPython
+   version 2.4.1).  All you need to know is that previous wxPython
+   code used a slightly different syntax that some folks (including
+   me) considered ugly.  So we changed it.  And that's when the sky
+   starting falling...
+
+   If you want more of the technical details, read the `wx package
+   documentation`_.
+
+   .. _wx package documentation: wxPackage.html
+
+
+Rather than simply **tell** you that everything will be okay, I
+decided to **show** you that everything will be okay.  To do that,
+I've created a bunch of example programs using the new wx package.  I
+hope you like them.
+
+
+Basic Program Example
+=====================
+
+It doesn't get much simpler than this.  Every wxPython program needs
+an application and a frame.  To encourage good coding habits, I've
+split them into separate modules.  They don't do much, but they're a
+good starting point.
+
+I include a simple App class in the frame module because the PyWrap
+"wrapper" utility (``pywrap``) only works with modules that contain an
+application class.  So including a simple one in each of your frame
+modules allows you to use the PyWrap runtime wrapper and debug your
+frames independent of your full application.
+
+Here is the module (``frame.py``) that defines the frame class:
+
+.. include:: ../samples/wx_examples/basic/frame.py
+   :literal:
+
+And here is the module (``app.py``) that defines the application class
+and imports the frame from ``frame.py``:
+
+.. include:: ../samples/wx_examples/basic/app.py
+   :literal:
+
+
+Hello wxPython Example
+======================
+
+This program displays an image file (``wxPython.jpg``) inside a frame
+sized to match the graphic.
+
+.. figure:: screenshots/hello-win98.png
+   :scale: 100
+
+   Running ``hello.py`` on Windows.
+
+.. figure:: screenshots/hello-linux.png
+   :scale: 100
+
+   Running ``hello.py`` on Linux.
+
+.. figure:: screenshots/hello-mac.png
+   :scale: 100
+
+   Running ``hello.py`` on Mac OS X.
+
+Here is the source code for ``hello.py``:
+
+.. include:: ../samples/wx_examples/hello/hello.py
+   :literal:
+