[PyCrust-cvs] wx wx.txt,NONE,1.1 default.css,NONE,1.1

[<po...@us...>]

Update of /cvsroot/pycrust/wx
In directory sc8-pr-cvs1:/tmp/cvs-serv11793

Added Files:
	wx.txt default.css 
Log Message:
Documentation


--- NEW FILE: wx.txt ---
=========================
 The wxPython wx Package
=========================

----------------------------------------------
 How to survive the new wx namespace changes.
----------------------------------------------

:Author: Patrick K. O'Brien
:Contact: po...@or...
:Date: $Date: 2003/03/21 18:17:57 $
:Revision: $Revision: 1.1 $

.. contents::


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:: __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:: html.py
   :literal:

And here is ``lib/dialogs.py``:

.. include:: lib/dialogs.py
   :literal:

As you can see, they both rely on the ``prefix.rename()`` function
defined in ``prefix.py``:

.. include:: 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:: examples/hello/hello.py
   :literal:

Good luck.  I hope you like the new wx package as much as I do.

Pat

--- NEW FILE: default.css ---
/*
:Author: David Goodger
:Contact: go...@us...
:date: $Date: 2003/03/21 18:17:58 $
:version: $Revision: 1.1 $
: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 }