This commit was manufactured by cvs2svn to create tag 'WX_2_4_1'.

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

wxPython/docs/PyManual.txt

@@ -0,0 +1,225 @@
+===============
+ The Py Manual
+===============
+
+-------------------------
+ Py - Served Fresh Daily 
+-------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Organization: Orbtech_
+:Date: $Date$
+:Revision: $Revision$
+
+.. _Orbtech: http://www.orbtech.com/
+
+.. contents::
+
+
+Introduction
+============
+
+This document will show you how to use the Py programs and the Py
+library of Python source code modules.  Py is the new name for the
+project that began as PyCrust.  Py is officially part of wxPython_,
+and includes PyCrust, so PyCrust is no longer distributed separately.
+
+.. _wxPython: http://www.wxpython.org/
+
+
+Developer Reference
+===================
+
+Source code documentation for developers is available at:
+
+http://www.orbtech.com/www/wx/epydoc/public/wx.py-module.html
+
+
+What is Py?
+===========
+
+Besides being `a delicious dessert`_, Py is the name for a collection
+of whimsically-named Python programs and modules that began as the
+PyCrust project.  So Py is really several things: a set of standalone
+programs, including the original PyCrust program, a library of Python
+source code modules that can be used in your own programs, a set of
+decorator classes that enhance the wxPython class library, and as many
+examples of bad "pie" puns as I can come up with.  (If you're going to
+do something, you might as well do it all the way, right?)  Py uses
+Python and wxPython, so it works equally well on Windows, Linux and
+Mac OS X.
+
+.. _a delicious dessert: http://www.wikipedia.org/wiki/Pie
+
+
+PyCrust is dead! Long live Py!
+==============================
+
+This project began with a program I created called PyCrust - an
+interactive, graphical Python shell, developed using the wxPython GUI
+toolkit.  For about two years, PyCrust was hosted on SourceForge_.
+Shortly after I created PyCrust, the wxPython folks started including
+it in their distribution.  As the PyCrust project grew, it reached a
+point where I thought the original PyCrust name was too confining.  I
+was using the PyCrust code base to develop programs that weren't just
+Python shells any more.
+
+Around that same time, the wxPython folks asked me if I'd be willing
+to move all my wxPython-related projects into the `wxPython CVS
+repository`_, and become part of the wxPython_/wxWindows_ developer team.
+I decided the time was right to restructure the PyCrust project.
+During the move, the PyCrust package was renamed to "py" (lowercase
+"p") and the collection of programs and modules as a whole became
+known as "Py" (with a capital "P").
+
+.. _wxPython CVS repository: http://cvs.wxwindows.org
+.. _SourceForge: http://www.sf.net/projects/pycrust/
+.. _wxWindows: http://www.wxwindows.org/
+
+The original goal of PyCrust was to be the best interactive, graphical
+Python shell (of course, I claimed it was the "flakiest" Python
+shell).  And that was all I wanted it to be.  But little by little I
+found myself developing a wider variety of tools for wxPython
+applications.  Eventually I'll create a debugger (PySlice, perhaps)
+and whatever else is needed to one day become a complete wxPython
+application development environment (PyFactory?).  In the mean time,
+PyCrust is still the flakiest Python shell, and the other Py programs
+are equally tasty.
+
+At this point, Py has standalone programs that include Python code
+editors (PyAlaCarte and PyAlaMode), interactive Python shells (PyCrust
+and PyShell), and a runtime wrapper (PyWrap).  The runtime wrapper
+utility provides you with runtime introspection capabilities for your
+wxPython programs without having to include PyCrust or PyShell in your
+program, and without having to alter one line of your source code.
+
+Py also contains a collection of modules that you can use in your own
+wxPython applications to provide similar services, either for your own
+use during development, or as an interface for users of your programs.
+These modules are the same ones used by all the Py programs.  In
+addition, Py contains a set of decorator classes that enhance the
+wxPython class library, by dynamically attaching docstrings and call
+signatures at runtime.
+
+
+Py standalone programs
+======================
+
+These are the standalone applications in the Py collection:
+
+* PyAlaCarte
+* PyAlaMode
+* PyCrust
+* PyFilling
+* PyShell
+* PyWrap
+
+
+PyAlaCarte
+==========
+
+PyAlaCarte is a Python source code editor.  It is designed to have a
+simple, single-file interface.  As a standalone application, it is
+good for simple, short editing tasks.  But it is really meant to be
+more of an example of how to embed the Py editor into a wxPython
+application.
+
+
+PyAlaMode
+=========
+
+PyAlaMode is a Python source code editor.  
+
+
+PyCrust
+=======
+
+PyCrust is an interactive, Python shell.  But it's more than just a
+shell.  It includes a tabbed notebook containing a namespace tree
+(PyFilling), and several other things.
+
+
+PyFilling
+=========
+
+PyFilling is a namespace viewer.  It isn't really useful as a
+standalone program, but it does illustrate how to make use of the
+underlying ``filling`` module.
+
+
+PyShell
+=======
+
+PyShell is an interactive, Python shell.  It shares the same base code
+as PyCrust, but doesn't have any of the extra features that appear in
+the PyCrust notebook interface.
+
+.. figure:: /screenshots/PyShell.png
+
+   PyShell running on Mandrake Linux 9.1.
+
+
+PyWrap
+======
+
+PyWrap is a runtime utility that lets you run an existing wxPython
+program with a PyCrust frame at the same time.  Inside the PyCrust
+shell namespace, the local variable ``app`` is assigned to your
+application instance.  In this way you can introspect your entire
+application within the PyCrust shell, as well as the PyFilling
+namespace viewer.  And through the use of the Py decorator classes,
+PyCrust can display wxPython function and method signatures as well as
+docstrings for the entire wxPython library.
+
+
+Py modules
+==========
+
+Py was designed to be modular.  That means graphical code is kept
+separate from non-graphical code, and many of the Py modules can be
+used by other programs.  Likewise, other programs can supply some of
+the modules needed by Py.  For example, you could supply a customized
+interpreter module and plug it in to the PyCrust standalone
+application.  As long as it supports the minimum functionality
+required, PyCrust will work just as well with your interpreter as with
+its default interpreter.
+
+
+Decorator classes
+=================
+
+Py contains a set of decorator classes that enhance the wxPython class
+library, by dynamically attaching docstrings and call signatures at
+runtime.
+
+
+Projects using Py
+=================
+
+* `Conflict Solver`_
+* Gnumed_
+* PyGist
+* PythonCard_
+* RPy_
+* SciPy_
+* Sim42_
+* wxGasp_
+
+.. _Conflict Solver: http://conflictsolver.sourceforge.net/
+.. _Gnumed: http://www.gnumed.org/
+.. _PythonCard: http://www.pythoncard.org/
+.. _RPy: http://rpy.sourceforge.net/
+.. _SciPy: http://www.scipy.org/
+.. _Sim42: http://www.sim42.org/
+.. _wxGasp: http://linus.yorktown.arlington.k12.va.us/CS/APCSC/student_sites/David_Mayo/wxGasp
+
+
+History of changes
+==================
+
+This section lists all the changes that have been made to the Py
+programs and modules, since the beginning.
+
+.. include:: ../wxPython/py/CHANGES.txt
+

wxPython/docs/default.css

@@ -0,0 +1,208 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+.first {
+  margin-top: 0 }
+
+.last {
+  margin-bottom: 0 }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+dd {
+  margin-bottom: 0.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+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.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 }
+
+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.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 }
+
+div.footer, div.header {
+  font-size: smaller }
+
+div.sidebar {
+  margin-left: 1em ;
+  border: medium outset ;
+  padding: 0em 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right }
+
+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.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr {
+  width: 75% }
+
+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.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+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.line-block {
+  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.option-argument {
+  font-style: italic }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+table {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.citation {
+  border-left: solid thin gray ;
+  padding-left: 0.5ex }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.footnote {
+  border-left: solid thin black ;
+  padding-left: 0.5ex }
+
+td, th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+th.docinfo-name, th.field-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+  font-size: 100% }
+
+tt {
+  background-color: #eeeeee }
+
+ul.auto-toc {
+  list-style-type: none }

wxPython/docs/docutils.conf

@@ -0,0 +1,6 @@
+[options]
+
+output_encoding: iso-8859-1
+source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1

wxPython/docs/wxPackage.txt

@@ -0,0 +1,180 @@
+=========================
+ The wxPython wx Package
+=========================
+
+--------------------------------------------------
+ Or, how to survive the new wx namespace changes.
+--------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Organization: Orbtech_
+:Date: $Date$
+:Revision: $Revision$
+
+.. _Orbtech: http://www.orbtech.com/
+
+.. contents::
+
+
+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.
+
+
+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 this new wx package?
+=================================
+
+The wx package is automatically created when you install wxPython
+version 2.4.1 or higher.  So all you have to do is::
+
+    import wx
+
+
+What are the issues with converting old code to use the new wx package?
+======================================================================= 
+
+Obviously, you need to change your import statements from::
+
+    from wxPython import wx
+
+or::
+
+    from wxPython.wx import *
+
+to::
+
+    import wx
+
+Then you need to refer to wx attributes without a "wx" prefix, such
+as::
+
+    class MyFrame(wx.Frame):
+
+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?
+==========================================================
+
+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_.
+
+.. _wxPythonExamples: wxPythonExamples.html
+.. _PyManual: PyManual.html

wxPython/docs/wxPythonDocs.txt

@@ -0,0 +1,77 @@
+========================
+ wxPython Documentation
+========================
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Organization: Orbtech_
+:Date: $Date$
+:Revision: $Revision$
+
+.. _Orbtech: http://www.orbtech.com/
+
+
+wxPython Manual
+===============
+
+`The wxPython Manual`_ is a reference to the wxPython toolkit.
+
+.. _The wxPython Manual: wxPythonManual.html
+
+
+wxPython Developer Reference
+============================
+
+`The wxPython source code documentation`_ is for developers, and was
+created using the Epydoc tool.
+
+.. _The wxPython source code documentation: http://www.orbtech.com/www/wx/epydoc/
+
+
+wxPython Tutorial
+=================
+
+`The wxPython Tutorial`_ will help get you started with wxPython.
+
+.. _The wxPython Tutorial:  wxPythonTutorial.html
+
+
+wxPython Examples
+=================
+
+`The wxPython Examples`_ illustrates example programs using wxPython.
+
+.. _The wxPython Examples: wxPythonExamples.html
+
+
+wx Package
+==========
+
+`The wxPython wx Package`_ explains the new prefix-less wx package.
+
+.. _The wxPython wx Package: wxPackage.html
+
+
+Py Manual
+=========
+
+`The Py Manual`_ documents the Py collection of programs and source
+code modules, including:
+
+* PyAlaCarte
+* PyAlaMode
+* PyCrust
+* PyFilling
+* PyShell
+* PyWrap
+
+.. _The Py Manual: PyManual.html
+
+
+Py Developer Reference
+======================
+
+`The Py source code documentation`_ is for developers, and was created
+using the Epydoc tool.
+
+.. _The Py source code documentation: http://www.orbtech.com/www/wx/epydoc/public/wx.py-module.html

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:
+

wxPython/docs/wxPythonTutorial.txt

@@ -0,0 +1,43 @@
+=======================
+ The wxPython Tutorial
+=======================
+
+-----------------------------------------
+ How to get up and running with wxPython
+-----------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Organization: Orbtech_
+:Date: $Date$
+:Revision: $Revision$
+:License: wxWindows Free Documentation Licence, Version 3
+
+.. _Orbtech: http://www.orbtech.com/
+
+.. contents::
+
+
+Introduction
+============
+
+This is a tutorial for the wxPython GUI toolkit.  It uses the new wx
+package syntax that was introduced in wxPython 2.4.1.
+
+
+What is wxPython?
+=================
+
+wxPython is a GUI toolkit for the Python programming language.  It
+allows Python programmers to create programs with a graphical user
+interface for Windows, Linux, and Mac OS X.
+
+
+License
+=======
+
+This document adheres to the same license as the other documentation
+that comes with wxWindows:
+
+.. include:: ../licence/licendoc.txt
+   :literal: