diff --git a/wxPython/docs/PyManual.html b/wxPython/docs/PyManual.html deleted file mode 100644 index ffcf29af43..0000000000 --- a/wxPython/docs/PyManual.html +++ /dev/null @@ -1,684 +0,0 @@ - - - - - - -The Py Manual - - - - - - -
-

The Py Manual

-

Py - Served Fresh Daily

- --- - - - - - - - - - - - -
Author:Patrick K. O'Brien
Contact:pobrien@orbtech.com
Organization:Orbtech
Date:2003-05-03
Revision:1.1.2.2
-
-

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.

-
-
-

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.

-
-
-

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").

-

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

-

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.

-
-

/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

- -
-
-

History of changes

-

This section lists all the changes that have been made to the Py -programs and modules, since the beginning.

-
-

0.9.2 (5/3/2003 to //2003)

-

Changed to the new prefix-less "wx" package:

-
-import wx
-
-

instead of:

-
-from wxPython import wx
-
-

Fixed typo in PyWrap.py:

-
-if __name__ == '__main__':
-    main(sys.argv)
-
-

should have been:

-
-if __name__ == '__main__':
-    main()
-
-

Added pretty-print Display tab to Crust, based on suggestion from -Jason Whitlark.

-

Improved Can* checks in EditWindow, since STC is too lenient, -particularly when it is set to read-only but returns True for -CanPaste() (seems like an STC bug to me):

-
-def CanCopy(self):
-    """Return True if text is selected and can be copied."""
-    return self.GetSelectionStart() != self.GetSelectionEnd()
-
-def CanCut(self):
-    """Return True if text is selected and can be cut."""
-    return self.CanCopy() and self.CanEdit()
-
-def CanEdit(self):
-    """Return True if editing should succeed."""
-    return not self.GetReadOnly()
-
-def CanPaste(self):
-    """Return True if pasting should succeed."""
-    return stc.StyledTextCtrl.CanPaste(self) and self.CanEdit()
-
-
-
-

0.9.1 (3/21/2003 to 5/2/2003)

-

PyCrust is dead! Long live Py!

-
    -
  • Renamed PyCrust package to py.
    • -
  • Moved code to wxPython's CVS repository.
    • -
-

Fixed bug in introspect.py on introspecting objects occurring -immediately after a secondary prompt, like this:

-
->>> l = [1, 2, 3]
->>> for n in range(3):
-...     l.  <-- failed to popup autocomplete list
-
-

Added documentation files:

-
    -
  • PyManual.txt
    • -
  • wxPythonManual.txt
    • -
  • wxPythonPackage.txt
    • -
  • wxPythonExamples.txt
    • -
-

Added PyAlaMode and PyAlaCarte code editors.

-

Major refactoring to support editor and shell from the same -base.

-

Renamed program files:

-
    -
  • PyCrustApp.py to PyCrust.py
    • -
  • PyFillingApp.py to PyFilling.py
    • -
  • PyShellApp.py to PyShell.py
    • -
  • wrap.py to PyWrap.py
    • -
-

Removed disabling of autocomplete for lists of 2000 items or more. -The current implementation of wxSTC can now handle lists this big.

-

Improved handling of sys.path to mimic the standard Python shell.

-
-
-

0.9 (2/27/2003 to 3/20/2003)

-

Added fontIncrease, fontDecrease, fontDefault signals, receivers and -keybindings:

-
-Ctrl+]            Increase font size.
-Ctrl+[            Decrease font size.
-Ctrl+=            Default font size.
-
-

Continued enhancement of the decorator capability to provide better -documentation and docstrings for wxPython classes and functions.

-

Introduced new tabbed interface:

-
    -
  • Namespace
    • -
  • Calltip
    • -
  • Session
    • -
  • Dispatcher
    • -
  • wxPython Docs
    • -
  • wxSTC Docs
    • -
-

Filling.tree now expands tuples as well as lists. (It should have -done this all along, I just never noticed this omission before.)

-

Added this True/False test to all modules:

-
-try:
-    True
-except NameError:
-    True = 1==1
-    False = 1==0
-
-

Added wxd directory with decoration classes.

-
-
-

0.8.2 (1/5/2003 to 2/26/2003)

-

Wrapped sys.ps1, sys.ps2, and sys.ps3 in str(). -(Thanks, Kieran Holland.)

-

Fixed minor things found by PyChecker.

-

Changed locals to use __main__.__dict__ and added code to clean up -the namespace, making it as close to the regular Python environment as -possible. This solves the problem of pickling and unpickling -instances of classes defined in the shell.

-

Made shell.PasteAndRun() a little more forgiving when it finds a -ps2 prompt line with no trailing space, such when you copy code from a -web page.

-

Improved autocomplete behavior by adding these to shell:

-
-self.AutoCompSetAutoHide(False)
-self.AutoCompStops(' .,;:([)]}\'"\\<>%^&+-=*/|`')
-
-

Added decor directory, decorator.py, stcDecor.py, and -stcConstants.py. These all serve the purpose of adding docstrings -to existing wxPython classes, in particular the wxStyledTextCtrl.

-

Added wrap.py, a command line utility for running a wxPython app -with additional runtime-tools loaded, such as PyCrust (the only tool -at this point).

-

Flushed the clipboard Cut/Copy operations so that selections will -exist in the clipboard even after PyCrust has been closed.

-

Improved the suppression of docstrings for simple data types appearing -in the namespace viewer.

-

Better handling of autocompletion with numeric types; no -autocompletion when typing a dot after an integer. If the -autocompletion is desired, type a space before the dot:

-
-func = 3 .
-
-

More Filling!!! The namespace tree is now dynamically updated.

-
-
-

0.8.1 (12/20/2002 to 12/25/2002)

-

Improved keyboard handling with Autocomplete active. You can now use -Enter as well as Tab to select an item from the list.

-

Disabled autocomplete for lists of 2000 items or more. The current -implementation of wxSTC can't handle lists this big.

-

Changed filling to always display docstrings for objects. This is -useful for objects whose docstrings have been decorated, rather than -coming directly from the source code. (Hmmm. Sounds like someone is -doing some decorating. I wonder where that would be helpful? <wink>)

-

Fixed handling of icon. Added images.py file.

-
-
-

0.8 (10/29/2002 to 12/16/2002)

-

Added "help" to startup banner info.

-

Made all wx and stc imports explicit. No more import *.

-

Replaced use of the wx module's true and false with -Python's True and False.

-

Changed introspect.getRoot() to use tokenize module. This -does a slightly better job than the previous parsing routine and the -code is clearer.

-

Improved handling of whitespace and empty types during introspection.

-

Fixed cut/copy clipboard problem under Linux. (Robin Dunn rocks!!!)

-

Added shell.about() which works like this:

-
->>> shell.about()
-PyCrust Version: 0.8
-Shell Revision: 1.80
-Interpreter Revision: 1.15
-Python Version: 2.2.2
-wxPython Version: 2.3.3.1
-Platform: linux2
-
-

Added copy plus and paste plus to shell menu.

-

Moved shell menu from shell.py to shellmenu.py.

-

Added sys.stdin.readlines() support.

-

Added time.sleep() in readline() and OnIdle() event -handler to free up the CPU.

-
-
-

0.7.2 (2/22/2002 to 8/27/2002)

-

Tweaked getAttributeNames() to pick up a few more attributes:

-
-'__bases__', '__class__', '__dict__', '__name__', 'func_closure',
-'func_code', 'func_defaults', 'func_dict', 'func_doc',
-'func_globals', 'func_name'
-
-

Added a tests directory and unit tests.

-

Improved support for empty types in the shell: [], () and -{} as far as when call tips and autocompletion are available.

-

Added support for the other triple string - ''''''.

-

Refactored introspect.py to improve testability.

-

Improved call tips for unbound methods by leaving the "self" -parameter, since unbound methods require an instance be passed.

-

Fixed call tip bug where a tip was displayed when a "(" was typed -after an object that wasn't callable.

-

Fixed getAllAttributeNames when str(object) fails.

-

Added brace highlighting. (Thank you, Kevin Altis.)

-

Fixed problem displaying unicode objects in PyFilling.

-

Changed how filling.py checks for expandable objects. Lists are -now expandable objects.

-

Made the key handling more robust when there is an active text -selection that includes text prior to the last primary prompt. Thanks -to Raul Cota for pointing this out.

-

Fixed wxSTC problem with brace highlighting and non-us keyboards. -(Thank you for the patch, Jean-Michel Fauth.)

-

Added busy = wxBusyCursor() to key points in shell and -filling.

-

Added OnCloseWindow handler to ShellFrame and CrustFrame.

-

Default to SetWrapMode(1) for shell and namespace viewer.

-

Added shell.wrap() and shell.zoom().

-

Added autoCompleteKeys hooks for Raul Cota.

-

Cleaned up various little key handling bugs.

-

Changed input methods to get values from shell, rather than dialog -boxes. Renamed readIn to readline and readRaw to -raw_input.

-
-
-

0.7.1 (12/12/2001 to 2/21/2002)

-

Fixed OnChar() issues effecting European keyboards, as reported by -Jean-Michel Fauth.

-

Fixed introspect.py issue with xmlrpc objects reported by Kevin -Altis.

-

Fixed some introspect/PyFilling issues with regard to Python 2.2.

-

Fixed font background color as reported by Keith J. Farmer. (Thanks)

-

Fixed problem with call tips and autocompletion inside multiline -commands as report by Kevin Altis.

-

Improved OnKeyDown handling of cut/copy/paste operations based on -feedback from Syver Enstad. (Thanks)

-

Added a shell.help() method to display some help info.

-

Changed sort of items in the namespace viewer to case insensitive.

-

Changed attributes.sort(lambda x, y: cmp(x.upper(), y.upper())) in -advance of an upcoming fix to an autocompletion matching bug in wxSTC.

-

Improved support for ZODB by allowing namespace drilldown into BTrees.

-

Added shell.PasteAndRun() to support pasting multiple commands into -the shell from the clipboard. Ctrl+Shift+V or v.

-

Enter now always processes a command (or copies down a previous one.) -To insert a line break, press Ctrl+Enter.

-

Escape key clears the current, unexecuted command.

-

History retrieval changed to replace current command. Added new keys -to insert from history - Shift+Up and Shift+Down.

-

Better call tips on objects with __call__ methods.

-

Improved call tip positioning calculation.

-
-
-

0.7 (10/15/2001 to 12/11/2001)

-

Changed how command history retrieval functions work. Added Alt-P, -Alt-N as keybindings for Retrieve-Previous, Retrieve-Next.

-

Added full support for multi-line commands, similar to IDLE.

-

Changed introspect.getAttributeNames() to do a case insensitive -sort.

-

Changed Cut/Copy/Paste to deal with prompts intelligently. Cut and -Copy remove all prompts. Paste can handle prompted or not-prompted -text.

-

Added CopyWithPrompts() method attached to Ctrl-Shift-C for those -times when you really do want all the prompts left intact.

-

Improved handling of the shell's read-only zone.

-

Changed CrustFrame.__init__ parameter spec to include all -parameters allowed by a wxFrame.

-

Changed FillingText to be read-only.

-

Renamed PyCrust.py to PyCrustApp.py to eliminate -package/module name conflicts that kept you from doing from PyCrust -import shell inside files located in the PyCrust directory.

-

Renamed PyFilling.py to PyFillingApp.py and PyShell.py to -PyShellApp.py to maintain consistency.

-

Removed the __date__ property from all modules.

-

Fixed bug in introspect.getCallTip(), reported by Kevin Altis.

-
-
-

0.6.1 (9/19/2001 to 10/12/2001)

-

Changed Shell.run() to always position to the end of existing -text, as suggested by Raul Cota.

-

Changed introspect.getAllAttributeNames() to break circular -references in object.__class__, which occurs in Zope/ZODB -extension classes.

-

Changed filling.FillingTree.getChildren() to introspect extension -classes.

-

Fixed minor bugs in introspect.getCallTip() that were interfering -with call tips for Zope/ZODB extension class methods.

-

In preparation for wxPython 2.3.2, added code to fix a font sizing -problem. Versions of wxPython prior to 2.3.2 had a sizing bug on Win -platform where the font was 2 points larger than what was specified.

-

Added a hack to introspect.getAllAttributeNames() to "wake up" -ZODB objects that are asleep - in a "ghost" state. Otherwise it -returns incomplete info.

-
-
-

0.6 (8/21/2001 to 9/12/2001)

-

Added PyFilling.py and filling.py.

-

PyShell.py and PyFilling.py can now be run standalone, as well -as PyCrust.py.

-

Added crust.py and moved some code from PyCrust.py to it.

-

Added command history retrieval features submitted by Richie Hindle.

-

Changed shell.write() to replace line endings with OS-specific -endings. Changed shell.py and interpreter.py to use -os.linesep in strings having hardcoded line endings.

-

Added shell.redirectStdin(), shell.redirectStdout() and -shell.redirectStderr() to allow the surrounding app to toggle -requests that the specified sys.std* be redirected to the shell. -These can also be run from within the shell itself, of course.

-

The shell now adds the current working directory "." to the search -path:

-
-sys.path.insert(0, os.curdir)
-
-

Added support for distutils installations.

-
-
-

0.5.4 (8/17/2001 to 8/20/2001)

-

Changed default font size under Linux to:

-
-'size'   : 12,
-'lnsize' : 10,
-
-

Changed Shell to expect a parameter referencing an Interpreter -class, rather than an intepreter instance, to facilitate subclassing -of Interpreter, which effectively broke when the Editor class was -eliminated.

-

Fixed PyCrustAlaCarte.py, which had been broken by previous -changes.

-

Created InterpreterAlaCarte class as an example for use in the -demo.

-

Split PyCrust.py into PyCrust.py and PyShell.py in -anticipation of PyFilling.py.

-
-
-

0.5.3 (8/16/2001)

-

Added patch to PyCrust.py to fix wxPython bug:

-
-wxID_SELECTALL = NewId() # This *should* be defined by wxPython.
-
-
-
-

0.5.2 (8/14/2001 to 8/15/2001)

-

Shortened module names by dropping "PyCrust" as a prefix.

-

Changed version to VERSION in version module.

-

Added Options menu to PyCrust application.

-

Eliminated the Editor class (and editor module) by merging with Shell. -This means that Shell "is a" wxStyledTextCtrl rather than "has a". -There just wasn't enough non-gui code to justify the separation. -Plus, Shell will be much easier for gui toolkits/designers to deal -with now.

-
-
-

0.5.1 (8/10/2001 to 8/14/2001)

-

Added introspect module.

-

Moved some functionality from PyCrustInterp to introspect.

-

Changed introspect.getRoot() to no longer remove whitespace from -the command. This was a remnant of a previous approach that, when -left as part of the current approach, turned out to be a really bad -thing.

-

Changed introspect.getRoot() to allow commands of '', "", -"""""", [], (), and {} to pass through. This allows -you to type them, followed by a dot, and get autocomplete options on -them.

-

Changed introspect.getRoot() to identify some situations where -strings shouldn't be considered roots. For example:

-
->>> import PyCrust  # To illustrate the potential problem.
->>> len('PyCrust.py')
-
-

Typing the dot at the end of "PyCrust" in the second line above should -NOT result in an autocompletion list because "PyCrust" is part of a -string in this context, not a reference to the PyCrust module object. -Similar reasoning applies to call tips. For example:

-
->>> len('dir(')
-
-

Typing the left paren at the end of "dir" should NOT result in a call -tip.

-

Both features now behave properly in the examples given. However, -there is still the case where whitespace precedes the potential root -and that is NOT handled properly. For example:

-
->>> len('this is a dir(')
-
-

and:

-
->>> len('This is PyCrust.py')
-
-

More code needs to be written to handle more complex situations.

-

Added locals=None parameter to Shell.__init__().

-

Added support for magic attribute retrieval. Users can change this -with:

-
->>> shell.editor.autoCompleteIncludeMagic = 0
-
-

Added the ability to set filters on auto completion to exclude -attributes prefixed with a single or double underscore. Users can -exclude one or the other or both with:

-
->>> shell.editor.autoCompleteExcludeSingle = 1
->>> shell.editor.autoCompleteExcludeDouble = 1
-
-
-
-

0.5 (8/8/2001)

-

Mostly just a final version change before creating a release.

-
-
-

0.4 (8/4/2001 to 8/7/2001)

-

Changed version/revision handling.

-

Fixed bugs.

-
-
-

0.3 (8/2/2001 to 8/3/2001)

-

Removed lots of cruft.

-

Added lots of docstrings.

-

Imported to CVS repository at SourceForge.

-

Added call tips.

-
-
-

0.2 (7/30/2001 to 8/2/2001)

-

Renamed several files.

-

Added command autocompletion.

-

Added menus to PyCrust.py: File, Edit and Help.

-

Added sample applications: PyCrustAlaCarte.py, -PyCrustAlaMode.py, and PyCrustMinimus.py.

-
-
-

0.1 (7/1/2001 to 7/19/2001)

-

Added basic syntax coloring much like Boa.

-

Added read-only logging much like IDLE.

-

Can retrieve a previous command by putting the cursor back on that -line and hitting enter.

-

Stdin and raw_input operate properly so you can now do help() and -license() without hanging.

-

Redefined "quit", "exit", and "close" to display a better-than-nothing -response.

-

Home key honors the prompt.

-

Created SourceForge account, but nothing was posted.

-
-
-

In the beginning, there was pie... (7/1/2001)

-

Blame it all on IDLE, Boa and PythonWin. I was using all three, got -frustrated with their dissimilarities, and began to let everyone know -how I felt. At the same time, Scintilla looked like an interesting -tool to build a shell around. And while I didn't receive much in the -way of positive feedback, let alone encouragement, I just couldn't let -go of the idea of a Scintilla-based Python shell. Then the PythonCard -project got to the point where they were talking about including a -shell in their development environment. That was all the incentive I -needed. PyCrust had to happen...

-
-
-
-
-
-View document source. -Generated on: 2003-05-04 19:39 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/wxPython/docs/wxPackage.html b/wxPython/docs/wxPackage.html deleted file mode 100644 index 4599362b09..0000000000 --- a/wxPython/docs/wxPackage.html +++ /dev/null @@ -1,255 +0,0 @@ - - - - - - -The wxPython wx Package - - - - - - -
-

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:2003-05-04
Revision:1.1.2.2
-
-

Contents

- -
-
-

Introduction

-

Big things sometimes come in small packages. This is certainly true -of the new wx package, which is being introduced as a way 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:

-
-"""wx package
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-from wxPython import wx
-
-import types
-
-d_new = globals()
-d_old = wx.__dict__
-
-for old, obj in d_old.items():
-    if type(obj) is types.ModuleType or old.startswith('_'):
-        # Skip modules and private names.
-        continue
-    new = old
-    if old.startswith('EVT_'):
-        # Leave name unmodified; add to the new wx namespace.
-        d_new[new] = obj
-    elif old.startswith('wxEVT_'):
-        # Leave name unmodified; add to the new wx namespace.
-        d_new[new] = obj
-    else:
-        if old.startswith('wx'):
-            # Remove the 'wx' prefix.
-            new = old[2:]
-        # Add to the new wx package namespace.
-        d_new[new] = obj
-
-del d_new
-del d_old
-del new
-del obj
-del old
-del types
-
-del wx
-
-
-

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:

-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython import html
-prefix.rename(d_new=globals(), d_old=html.__dict__)
-del html
-
-del prefix
-del wx
-
-
-

And here is lib/dialogs.py:

-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython.lib import dialogs
-prefix.rename(d_new=globals(), d_old=dialogs.__dict__)
-del dialogs
-
-del prefix
-del wx
-
-
-

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

-
-"""Renaming utility.
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import types
-
-def rename(d_new, d_old):
-    for old, obj in d_old.items():
-        if type(obj) is types.ModuleType or old.startswith('_'):
-            # Skip modules and private names.
-            continue
-##         mod = d_old['__name__']
-##         if hasattr(obj, '__module__') and not obj.__module__.startswith(mod):
-##             # Skip objects imported from other modules, except those
-##             # related to the current module, such as stc_.
-##             continue
-        new = old
-        if old.startswith('EVT_') or old.startswith('wxEVT_'):
-            # Leave these names unmodified.
-            pass 
-        elif old.startswith('wx'):
-            new = old[2:]
-        if new:
-            d_new[new] = d_old[old]
-
-
-

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

Example programs are included in the wxPython/samples/wx_examples -directory, and are documented in the wxPythonExamples documentation -file.

-

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

-
-
-
-
-View document source. -Generated on: 2003-05-04 19:38 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/wxPython/docs/wxPythonExamples.html b/wxPython/docs/wxPythonExamples.html deleted file mode 100644 index 0341f0c121..0000000000 --- a/wxPython/docs/wxPythonExamples.html +++ /dev/null @@ -1,226 +0,0 @@ - - - - - - -Example Programs Using wxPython - - - - - - -
-

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:2003-05-04
Revision:1.1.2.2
-
-

Contents

- -
-
-

Introduction

-

This document illustrates example programs using wxPython. All the -examples make use of the new wx package syntax, 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. 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.

-
-

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:

-
-#!/usr/bin/env python
-
-"""Basic frame class, with App for testing."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
-    """Frame class."""
-
-    def __init__(self, parent=None, id=-1, title='Title',
-                 pos=wx.DefaultPosition, size=(400, 200)):
-        """Create a Frame instance."""
-        wx.Frame.__init__(self, parent, id, title, pos, size)
-
-class App(wx.App):
-    """Application class."""
-
-    def OnInit(self):
-        self.frame = Frame()
-        self.frame.Show()
-        self.SetTopWindow(self.frame)
-        return True
-
-def main():
-    app = App()
-    app.MainLoop()
-
-if __name__ == '__main__':
-    main()
-
-
-

And here is the module (app.py) that defines the application class -and imports the frame from frame.py:

-
-#!/usr/bin/env python
-
-"""Basic application class."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-from frame import Frame
-
-class App(wx.App):
-    """Application class."""
-
-    def OnInit(self):
-        self.frame = Frame()
-        self.frame.Show()
-        self.SetTopWindow(self.frame)
-        return True
-
-def main():
-    app = App()
-    app.MainLoop()
-
-if __name__ == '__main__':
-    main()
-
-
-
-
-

Hello wxPython Example

-

This program displays an image file (wxPython.jpg) inside a frame -sized to match the graphic.

-
-

screenshots/hello-win98.png

-

Running hello.py on Windows.

-
-
-

screenshots/hello-linux.png

-

Running hello.py on Linux.

-
-
-

screenshots/hello-mac.png

-

Running hello.py on Mac OS X.

-
-

Here is the source code for hello.py:

-
-#!/usr/bin/env python
-
-"""Hello, wxPython! program."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
-    """Frame class that displays an image."""
-
-    def __init__(self, image, parent=None, id=-1,
-                 pos=wx.DefaultPosition, title='Hello, wxPython!'):
-        """Create a Frame instance and display image."""
-        temp = image.ConvertToBitmap()
-        size = temp.GetWidth(), temp.GetHeight()
-        wx.Frame.__init__(self, parent, id, title, pos, size)
-        self.bmp = wx.StaticBitmap(parent=self, id=-1, bitmap=temp)
-
-class App(wx.App):
-    """Application class."""
-
-    def OnInit(self):
-        wx.InitAllImageHandlers()
-        image = wx.Image('wxPython.jpg', wx.BITMAP_TYPE_JPEG)
-        self.frame = Frame(image)
-        self.frame.Show()
-        self.SetTopWindow(self.frame)
-        return True
-
-def main():
-    app = App()
-    app.MainLoop()
-
-if __name__ == '__main__':
-    main()
-
-
-
-
-
-
-View document source. -Generated on: 2003-05-04 19:37 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/wxPython/docs/wxPythonManual.html b/wxPython/docs/wxPythonManual.html deleted file mode 100644 index dc030ea315..0000000000 --- a/wxPython/docs/wxPythonManual.html +++ /dev/null @@ -1,1082 +0,0 @@ - - - - - - -The wxPython Manual - - - - - - -
-

The wxPython Manual

-

A guide to wxPython for Python programmers

- --- - - - - - - - - - - - - - -
Author:Patrick K. O'Brien
Contact:pobrien@orbtech.com
Organization:Orbtech
Date:2003-05-04
Revision:1.1.2.2
License:wxWindows Free Documentation Licence, Version 3
-
-

Contents

- -
-
-

Introduction

-

This is a guide to the wxPython GUI toolkit, written by a Python -programmer for his fellow Python programmers. It began as a -simple translation of the wxWindows documentation (which is written -for C++ programmers), and evolved from there. And while there's -nothing wrong with C++...

-

Okay, you got me there. I hate C++. That's why I use Python. If you -like C++, go read the wxWindows documentation. If you'd rather read a -guide that's written with Python programmers in mind, keep reading -this one. If you like it, feel free to send me freshly roasted coffee -beans, dark chocolate, and large denomination currency. Better yet, -buy huge quantities of my wxPython book (written with Robin Dunn) and -send one to each of your friends, relatives, and coworkers.

-
-
-

What is wxPython?

-

wxPython is a GUI toolkit for the Python programming language. It -allows Python programmers to create programs with a robust, highly -functional graphical user interface, simply and easily. It is -implemented as a Python extension module (native code) that wraps the -popular wxWindows cross platform GUI library, which is written in C++.

-

Like Python and wxWindows, wxPython is Open Source, which means that -it is free for anyone to use and the source code is available for -anyone to look at and modify. And anyone can contribute fixes or -enhnacments to the project.

-

wxPython is a cross-platform toolkit. This means that the same -program will run on multiple platforms without modification. -Currently supported platforms are 32-bit Microsoft Windows, most Unix -or unix-like systems, and Macintosh OS X.

-

Since the language is Python, wxPython programs are simple, easy to -write and easy to understand.

-
-
-

wxPython requirements

-

To make use of wxPython, you currently need one of the following -setups.

-
-

MS-Windows

-
    -
  • A 486 or higher PC running MS Windows.
    • -
  • At least ?? MB of disk space.
    • -
-
-
-

Linux or Unix

-
    -
  • Almost any C++ compiler, including GNU C++ (EGCS 1.1.1 or above).
    • -
  • Almost any Unix workstation, and one of: GTK+ 1.2, GTK+ 2.0, Motif -1.2 or higher, Lesstif.
    • -
  • At least ?? MB of disk space.
    • -
-
-
-

Mac OS X

-
    -
  • A PowerPC Mac running Mac OS X 10.x.
    • -
  • At least ?? MB of disk space.
    • -
-
-
-
-

What is wxWindows?

-

wxWindows is a C++ framework providing GUI (Graphical User Interface) -and other facilities on more than one platform. Version 2 currently -supports all desktop versions of MS Windows, Unix with GTK+, Unix with -Motif, and MacOS. An OS/2 port is in progress.

-

wxWindows was originally developed at the Artificial Intelligence -Applications Institute, University of Edinburgh, for internal use, and -was first made publicly available in 1992. Version 2 is a vastly -improved version written and maintained by Julian Smart, Robert -Roebling, Vadim Zeitlin, Vaclav Slavik and many others.

-

Please note that in the following, "MS Windows" often refers to all -platforms related to Microsoft Windows, including 16-bit and 32-bit -variants, unless otherwise stated. All trademarks are acknowledged.

-
-
-

Why another cross-platform development tool?

-

wxWindows was developed to provide a cheap and flexible way to -maximize investment in GUI application development. While a number of -commercial class libraries already existed for cross-platform -development, none met all of the following criteria:

- -

Since wxWindows was started, several other free or almost-free GUI -frameworks have emerged. However, none has the range of features, -flexibility, documentation and the well-established development team -that wxWindows has.

-

As open source software, wxWindows has benefited from comments, ideas, -bug fixes, enhancements and the sheer enthusiasm of users. This gives -wxWindows a certain advantage over its commercial competitors (and -over free libraries without an independent development team), plus a -robustness against the transience of one individual or company. This -openness and availability of source code is especially important when -the future of thousands of lines of application code may depend upon -the longevity of the underlying class library.

-

Version 2 goes much further than previous versions in terms of -generality and features, allowing applications to be produced that are -often indistinguishable from those produced using single-platform -toolkits such as Motif, GTK+ and MFC.

-

The importance of using a platform-independent class library cannot be -overstated, since GUI application development is very time-consuming, -and sustained popularity of particular GUIs cannot be guaranteed. -Code can very quickly become obsolete if it addresses the wrong -platform or audience. wxWindows helps to insulate the programmer from -these winds of change. Although wxWindows may not be suitable for -every application (such as an OLE-intensive program), it provides -access to most of the functionality a GUI program normally requires, -plus many extras such as network programming, PostScript output, and -HTML rendering; and it can of course be extended as needs dictate. As -a bonus, it provides a far cleaner and easier programming interface -than the native APIs. Programmers may find it worthwhile to use -wxWindows even if they are developing on only one platform.

-

It is impossible to sum up the functionality of wxWindows in a few -paragraphs, but here are some of the benefits:

- -
-
-

wxPython Overview

-

To set a wxPython application going, you will need to derive an App -class and override App.OnInit.

-

An application must have a top-level Frame or Dialog window. Each -frame may contain one or more instances of classes such as Panel, -SplitterWindow or other windows and controls.

-

A frame can have a MenuBar, a ToolBar, a status line, and an Icon for -when the frame is iconized.

-

A Panel is used to place controls (classes derived from Control) which -are used for user interaction. Examples of controls are Button, -CheckBox, Choice, ListBox, RadioBox, Slider.

-

Instances of Dialog can also be used for controls, and they have the -advantage of not requiring a separate frame.

-

Instead of creating a dialog box and populating it with items, it is -possible to choose one of the convenient common dialog classes, such -as MessageDialog and FileDialog.

-

You never draw directly onto a window. Instead, you use a device -context (DC). DC is the base for ClientDC, PaintDC, MemoryDC, -PostScriptDC, MemoryDC, MetafileDC and PrinterDC. If your drawing -functions have DC as a parameter, you can pass any of these DCs to the -function, and thus use the same code to draw to several different -devices. You can draw using the member functions of DC, such as -DC.DrawLine and DC.DrawText. Control colour on a window (Colour) with -brushes (Brush) and pens (Pen).

- -

Most modern applications will have an on-line, hypertext help system; -for this, you need Help and the HelpController class to control -Help.

-

GUI applications aren't all graphical wizardry. You'll also need -lists and hash tables. But since you're working with Python, you -should use the ones Python provides (list, tuple, dict), rather than -the wxWindows versions. Same goes for the database related classes. -The basic rule of thumb is this: If you can do it directly in Python, -you probably should. If there is a reason not to use a Python data -type, wxPython will provide a wrapper for the wxWindows class.

-

You will undoubtedly need some platform-independent file functions, -and you may find it handy to maintain and search a list of paths using -PathList. There's a miscellany of operating system and other -functions.

-

See also Classes by Category for a list of classes.

-
-
-

Utilities and libraries supplied with wxPython

-

In addition to the core wxWindows library, a number of further -libraries and utilities are supplied with each distribution.

-

[Need to list these.]

-
-
-

Creating and deleting wxPython objects

-

[This section needs to be reviewed.]

- - - - - -
-
-

App overview

-

Classes: wx.App

-
-

Application initialization

-

The OnInit method defined for a class derived from wx.App will usually -create a top window as a bare minimum.

-

OnInit must return a boolean value to indicate whether processing -should continue (True) or not (False). You call App.SetTopWindow to -let wxPython know about the top window.

-

An application closes by destroying all windows. Because all frames -must be destroyed for the application to exit, it is advisable to use -parent frames wherever possible when creating new frames, so that -deleting the top level frame will automatically delete child frames. -The alternative is to explicitly delete child frames in the top-level -frame's CloseEvent handler.

-

In emergencies the wx.Exit() function can be called to kill the -application, however, normally the application shuts down -automatically, see below.

-

An example of defining an application follows:

-
-import wx
-
-from frame import Frame
-
-class App(wx.App):
-    """Application class."""
-
-    def OnInit(self):
-        self.frame = Frame()
-        self.frame.Show()
-        self.SetTopWindow(self.frame)
-        return True
-
-def main():
-    app = App()
-    app.MainLoop()
-
-if __name__ == '__main__':
-    main()
-
-
-
-

Application shutdown

-

The application normally shuts down when the last of its top level -windows is closed. This is normally the expected behaviour and means -that it is enough to call Close() in response to the "Exit" menu -command if your program has a single top level window. If this -behaviour is not desirable, App.SetExitOnFrameDelete can be called to -change it. Note that such logic doesn't apply for the windows shown -before the program enters the main loop: in other words, you can -safely show a dialog from App.OnInit and not be afraid that your -application terminates when this dialog -- which is the last top level -window for the moment -- is closed.

-

Another aspect of the application shutdown is the OnExit which is -called when the application exits but before wxPython cleans up its -internal structures. You should delete all wxPython objects that you -created by the time OnExit finishes.

-

For example, this code may crash:

-

[Need examples of objects needing cleanup to keep app from crashing.]

-
-
-
-

Sizer overview

-

Classes: wx.Sizer, wx.GridSizer, wx.FlexGridSizer, wx.BoxSizer, -wx.StaticBoxSizer, wx.NotebookSizer, wx.CreateButtonSizer

- ---- - - - - - - - - - - - - - - - - - - - - -
SizerAbstract base class.
GridSizerA sizer for laying out windows in a grid with all -fields having the same size.
FlexGridSizerA sizer for laying out windows in a flexible grid.
BoxSizerA sizer for laying out windows in a row or column.
StaticBoxSizerSame as BoxSizer, but with a surrounding static box.
NotebookSizerSizer to use with the Notebook control.
-

Sizers, as represented by the wx.Sizer class and its descendants in -the wxPython class hierarchy, have become the method of choice to -define the layout of controls in dialogs in wxPython because of their -ability to create visually appealing dialogs independent of the -platform, taking into account the differences in size and style of the -individual controls. Editors such as wxDesigner, wxrcedit, XRCed and -wxWorkshop create dialogs based exclusively on sizers, practically -forcing the user to create platform independent layouts without -compromises.

-
-

The idea behind sizers

-

The layout algorithm used by sizers in wxPython is closely related to -layout systems in other GUI toolkits, such as Java's AWT, the GTK -toolkit or the Qt toolkit. It is based upon the idea of individual -subwindows reporting their minimal required size and their ability to -get stretched if the size of the parent window has changed. This will -most often mean that the programmer does not set the start-up size of -a dialog, the dialog will rather be assigned a sizer and this sizer -will be queried about the recommended size. This sizer in turn will -query its children (which can be normal windows, empty space or other -sizers) so that a hierarchy of sizers can be constructed. Note that -wx.Sizer does not derive from wx.Window and thus does not interfere -with tab ordering and requires very few resources compared to a real -window on screen.

-

What makes sizers so well fitted for use in wxPython is the fact that -every control reports its own minimal size and the algorithm can -handle differences in font sizes or different window (dialog item) -sizes on different platforms without problems. For example, if the -standard font as well as the overall design of Linux/GTK widgets -requires more space than on Windows, the initial dialog size will -automatically be bigger on Linux/GTK than on Windows.

-

There are currently five different kinds of sizers available in -wxPython. Each represents either a certain way to lay out dialog items -in a dialog or it fulfils a special task such as wrapping a static box -around a dialog item (or another sizer). These sizers will be -discussed one by one in the text below.

-
-
-

Common features

-

All sizers are containers, that is, they are used to lay out one -dialog item (or several dialog items), which they contain. Such items -are sometimes referred to as the children of the sizer. Independent -of how the individual sizers lay out their children, all children have -certain features in common:

-
-

A minimal size

-

This minimal size is usually identical to the initial size of the -controls and may either be set explicitly in the size field of the -control constructor or may be calculated by wxPython, typically by -setting the height and/or the width of the item to -1. Note that only -some controls can calculate their size (such as a checkbox) whereas -others (such as a listbox) don't have any natural width or height and -thus require an explicit size. Some controls can calculate their -height, but not their width (e.g. a single line text control):

-

[Need graphics]

-
-
-

A border

-

The border is just empty space and is used to separate dialog items in -a dialog. This border can either be all around, or at any combination -of sides such as only above and below the control. The thickness of -this border must be set explicitly, typically 5 points. The following -samples show dialogs with only one dialog item (a button) and a border -of 0, 5, and 10 pixels around the button:

-

[Need graphics]

-
-
-

An alignment

-

Often, a dialog item is given more space than its minimal size plus -its border. Depending on what flags are used for the respective dialog -item, the dialog item can be made to fill out the available space -entirely, i.e. it will grow to a size larger than the minimal size, or -it will be moved to either the centre of the available space or to -either side of the space. The following sample shows a listbox and -three buttons in a horizontal box sizer; one button is centred, one is -aligned at the top, one is aligned at the bottom:

-

[Need graphics]

-
-
-

A stretch factor

-

If a sizer contains more than one child and it is offered more space -than its children and their borders need, the question arises how to -distribute the surplus space among the children. For this purpose, a -stretch factor may be assigned to each child, where the default value -of 0 indicates that the child will not get more space than its -requested minimum size. A value of more than zero is interpreted in -relation to the sum of all stretch factors in the children of the -respective sizer, i.e. if two children get a stretch factor of 1, they -will get half the extra space each independent of whether one control -has a minimal sizer inferior to the other or not. The following -sample shows a dialog with three buttons, the first one has a stretch -factor of 1 and thus gets stretched, whereas the other two buttons -have a stretch factor of zero and keep their initial width:

-

[Need graphics]

-

Within wxDesigner, this stretch factor gets set from the Option menu.

-
-
-
-

BoxSizer

-

BoxSizer can lay out its children either vertically or horizontally, -depending on what flag is being used in its constructor. When using a -vertical sizer, each child can be centered, aligned to the right or -aligned to the left. Correspondingly, when using a horizontal sizer, -each child can be centered, aligned at the bottom or aligned at the -top. The stretch factor described in the last paragraph is used for -the main orientation, i.e. when using a horizontal box sizer, the -stretch factor determines how much the child can be stretched -horizontally. The following sample shows the same dialog as in the -last sample, only the box sizer is a vertical box sizer now:

-

[Need graphics]

-
-
-

StaticBoxSizer

-

StaticBoxSixer is the same as a BoxSizer, but surrounded by a static -box. Here is a sample:

-

[Need graphics]

-
-
-

GridSizer

-

GridSizer is a two-dimensional sizer. All children are given the same -size, which is the minimal size required by the biggest child, in this -case the text control in the left bottom border. Either the number of -columns or the number or rows is fixed and the grid sizer will grow in -the respectively other orientation if new children are added:

-

[Need graphics]

-
-
-

FlexGridSizer

-

Another two-dimensional sizer derived from GridSizer. The width of -each column and the height of each row are calculated individually -according the minimal requirements from the respectively biggest -child. Additionally, columns and rows can be declared to be -stretchable if the sizer is assigned a size different from that which -it requested. The following sample shows the same dialog as the one -above, but using a flex grid sizer:

-

[Need graphics]

-
-
-

NotebookSizer

-

NotebookSizer can be used with notebooks. It calculates the size of -each notebook page and sets the size of the notebook to the size of -the biggest page plus some extra space required for the notebook tabs -and decorations.

-

[Need graphics]

-
-
-

Programming with BoxSizer

-

The basic idea behind a BoxSizer is that windows will most often be -laid out in rather simple basic geometry, typically in a row or a -column or several hierarchies of either.

-

As an example, we will construct a dialog that will contain a text -field at the top and two buttons at the bottom. This can be seen as a -top-hierarchy column with the text at the top and buttons at the -bottom and a low-hierarchy row with an OK button to the left and a -Cancel button to the right. In many cases (particularly dialogs under -Unix and normal frames) the main window will be resizable by the user -and this change of size will have to get propagated to its children. -In our case, we want the text area to grow with the dialog, whereas -the button shall have a fixed size. In addition, there will be a thin -border around all controls to make the dialog look nice and - to make -matter worse - the buttons shall be centred as the width of the dialog -changes.

-

It is the unique feature of a box sizer, that it can grow in both -directions (height and width) but can distribute its growth in the -main direction (horizontal for a row) unevenly among its children. In -our example case, the vertical sizer is supposed to propagate all its -height changes to only the text area, not to the button area. This is -determined by the proportion parameter when adding a window (or -another sizer) to a sizer. It is interpreted as a weight factor, -i.e. it can be zero, indicating that the window may not be resized at -all, or above zero. If several windows have a value above zero, the -value is interpreted relative to the sum of all weight factors of the -sizer, so when adding two windows with a value of 1, they will both -get resized equally much and each half as much as the sizer owning -them.

-

Then what do we do when a column sizer changes its width? This -behaviour is controlled by flags (the second parameter of the Add() -function): zero or no flag indicates that the window will preserve it -is original size, wx.GROW flag (same as wx.EXPAND) forces the window -to grow with the sizer, and wx.SHAPED flag tells the window to change -it is size proportionally, preserving original aspect ratio. When -wx.GROW flag is not used, the item can be aligned within available -space. wx.ALIGN_LEFT, wx.ALIGN_TOP, wx.ALIGN_RIGHT, wx.ALIGN_BOTTOM, -wx.ALIGN_CENTER_HORIZONTAL and wx.ALIGN_CENTER_VERTICAL do what they -say. wx.ALIGN_CENTRE (same as wx.ALIGN_CENTER) is defined as -(wx.ALIGN_CENTER_HORIZONTAL | wx.ALIGN_CENTER_VERTICAL). Default -alignment is wx.ALIGN_LEFT | wx.ALIGN_TOP.

-

As mentioned above, any window belonging to a sizer may have border, -and it can be specified which of the four sides may have this border, -using the wx.TOP, wx.LEFT, wx.RIGHT and wx.BOTTOM constants or wx.ALL -for all directions (and you may also use wx.NORTH, wx.WEST etc -instead). These flags can be used in combination with the alignment -flags above as the second parameter of the Add() method using the -binary or operator (|). The sizer of the border also must be made -known, and it is the third parameter in the Add() method. This means, -that the entire behaviour of a sizer and its children can be -controlled by the three parameters of the Add() method.

-

[Show code and graphic here.]

-
-
-

Programming with GridSizer

-

GridSizer is a sizer which lays out its children in a two-dimensional -table with all table fields having the same size, i.e. the width of -each field is the width of the widest child, the height of each field -is the height of the tallest child.

-

[Show code and graphic here.]

-
-
-

Programming with FlexGridSizer

-

FlexGridSizer is a sizer which lays out its children in a -two-dimensional table with all table fields in one row having the same -height and all fields in one column having the same width, but all -rows or all columns are not necessarily the same height or width as in -the GridSizer.

-

[Show code and graphic here.]

-
-
-

Programming with NotebookSizer

-

NotebookSizer is a specialized sizer to make sizers work in connection -with using notebooks. This sizer is different from any other sizer as -you must not add any children to it - instead, it queries the notebook -class itself. The only thing this sizer does is to determine the size -of the biggest page of the notebook and report an adjusted minimal -size to a more toplevel sizer.

-

In order to query the size of notebook page, this page needs to have -its own sizer, otherwise the NotebookSizer will ignore it. Notebook -pages get their sizer by assigning one to them using SetSizer() and -setting the auto-layout option to True using SetAutoLayout(). Here is -one example showing how to add a notebook page that the notebook sizer -is aware of:

-

[Show code and graphic here.]

-
-
-

Programming with StaticBoxSizer

-

StaticBoxSizer is a sizer derived from BoxSizer but adds a static box -around the sizer. Note that this static box has to be created -separately.

-

[Show code and graphic here.]

-
-
-

Dialog.CreateButtonSizer

-

As a convenience, the Dialog class has a CreateButtonSizer(flags) -method that can be used to create a standard button sizer in which -standard buttons are displayed. The following flags can be passed to -this method:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
wx.YES_NOadd Yes/No subpanel
wx.YESreturn wx.ID_YES
wx.NOreturn wx.ID_NO
wx.NO_DEFAULTmake the wx.NO button the default, otherwise wx.YES or -wx.OK button will be default
wx.OKreturn wx.ID_OK
wx.CANCELreturn wx.ID_CANCEL
wx.HELPreturn wx.ID_HELP
wx.FORWARDreturn wx.ID_FORWARD
wx.BACKWARDreturn wx.ID_BACKWARD
wx.SETUPreturn wx.ID_SETUP
wx.MOREreturn wx.ID_MORE
-
-
-
-

Date and time classes overview

-

wxPython provides a set of powerful classes to work with dates and -times. Some of the supported features of the DateTime class are:

- ---- - - - - - - - - - - - - - - -
Wide rangeThe range of supported dates goes from about 4714 B.C. to -some 480 million years in the future.
PrecisionNot using floating point calculations anywhere ensures that -the date calculations don't suffer from rounding -errors.
Many featuresNot only all usual calculations with dates are -supported, but also more exotic week and year day -calculations, work day testing, standard astronomical -functions, conversion to and from strings in either -strict or free format.
EfficiencyObjects of DateTime are small (8 bytes) and working -with them is fast
-
-

All date/time classes at a glance

-

There are 3 main classes: except DateTime itself which represents an -absolute moment in time, there are also two classes - TimeSpan and -DateSpan which represent the intervals of time.

-

There are also helper classes which are used together with DateTime: -DateTimeHolidayAuthority which is used to determine whether a given -date is a holiday or not and DateTimeWorkDays which is a derivation of -this class for which (only) Saturdays and Sundays are the holidays. -See more about these classes in the discussion of the holidays.

-
-
-

DateTime characteristics

-

DateTime stores the time as a signed number of milliseconds since the -Epoch which is fixed, by convention, to Jan 1, 1970 - however this is -not visible to the class users (in particular, dates prior to the -Epoch are handled just as well (or as bad) as the dates after it). -But it does mean that the best resolution which can be achieved with -this class is 1 millisecond.

-

The size of DateTime object is 8 bytes because it is represented as a -64 bit integer. The resulting range of supported dates is thus -approximatively 580 million years, but due to the current limitations -in the Gregorian calendar support, only dates from Nov 24, 4714BC are -supported (this is subject to change if there is sufficient interest -in doing it).

-

Finally, the internal representation is time zone independent (always -in GMT) and the time zones only come into play when a date is broken -into year/month/day components. See more about timezones below.

-

Currently, the only supported calendar is Gregorian one (which is used -even for the dates prior to the historic introduction of this calendar -which was first done on Oct 15, 1582 but is, generally speaking, -country, and even region, dependent). Future versions will probably -have Julian calendar support as well and support for other calendars -(Maya, Hebrew, Chinese...) is not ruled out.

-
-
-

Difference between DateSpan and TimeSpan

-

While there is only one logical way to represent an absolute moment in -the time (and hence only one DateTime class), there are at least two -methods to describe a time interval.

-

First, there is the direct and self-explaining way implemented by -TimeSpan: it is just a difference in milliseconds between two moments -in time. Adding or subtracting such an interval to DateTime is always -well-defined and is a fast operation.

-

But in daily life other, calendar-dependent time interval -specifications are used. For example, 'one month later' is commonly -used. However, it is clear that this is not the same as TimeSpan of -60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not -Mar 17 or Mar 16 (depending on whether the year is leap or not).

-

This is why there is another class for representing such intervals -called DateSpan. It handles these sort of operations in the most -natural way possible, but note that manipulating with intervals of -this kind is not always well-defined. Consider, for example, Jan 31 + -'1 month': this will give Feb 28 (or 29), i.e. the last day of -February and not the non-existent Feb 31. Of course, this is what is -usually wanted, but you still might be surprised to notice that now -subtracting back the same interval from Feb 28 will result in Jan 28 -and not Jan 31 we started with!

-

So, unless you plan to implement some kind of natural language parsing -in the program, you should probably use TimeSpan instead of DateSpan -(which is also more efficient). However, DateSpan may be very useful -in situations when you do need to understand what 'in a month' means -(of course, it is just DateTime.Now() + DateSpan.Month()).

-
-
-

Date arithmetics

-

Many different operations may be performed with the dates, however not -all of them make sense. For example, multiplying a date by a number -is an invalid operation, even though multiplying either of the time -span classes by a number is perfectly valid.

-

Here is what can be done:

- ---- - - - - - - - - - - - - - - -
Additiona TimeSpan or DateSpan can be added to DateTime resulting in -a new DateTime object and also 2 objects of the same -span class can be added together giving another object -of the same class.
Subtractionthe same types of operations as above are allowed and, -additionally, a difference between two DateTime -objects can be taken and this will yield TimeSpan.
Multiplicationa TimeSpan or DateSpan object can be multiplied by an -integer number resulting in an object of the same -type.
Unary minusa TimeSpan or DateSpan object may finally be negated -giving an interval of the same magnitude but of -opposite time direction.
-
-
-

Time zone considerations

-

Although the time is always stored internally in GMT, you will usually -work in the local time zone. Because of this, all DateTime -constructors and setters which take the broken down date assume that -these values are for the local time zone. Thus, DateTime(1, -DateTime.Jan, 1970) will not correspond to the DateTime Epoch unless -you happen to live in the UK.

-

All methods returning the date components (year, month, day, hour, -minute, second...) will also return the correct values for the local -time zone by default. So, generally, doing the natural things will -lead to natural and correct results.

-

If you only want to do this, you may safely skip the rest of this -section. However, if you want to work with different time zones, you -should read it to the end.

-

In this (rare) case, you are still limited to the local time zone when -constructing DateTime objects, i.e. there is no way to construct a -DateTime corresponding to the given date in, say, Pacific Standard -Time. To do it, you will need to call ToTimezone or MakeTimezone -methods to adjust the date for the target time zone. There are also -special versions of these functions ToGMT and MakeGMT for the most -common case - when the date should be constructed in GMT.

-

You also can just retrieve the value for some time zone without -converting the object to it first. For this you may pass TimeZone -argument to any of the methods which are affected by the time zone -(all methods getting date components and the date formatting ones, for -example). In particular, the Format() family of methods accepts a -TimeZone parameter and this allows to simply print time in any time -zone.

-

To see how to do it, the last issue to address is how to construct a -TimeZone object which must be passed to all these methods. First of -all, you may construct it manually by specifying the time zone offset -in seconds from GMT, but usually you will just use one of the symbolic -time zone names and let the conversion constructor do the -job. I.e. you would just write

-

wxDateTime dt(...whatever...); -printf("The time is %s in local time zone", dt.FormatTime().c_str()); -printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());

-
-
-

Daylight saving time (DST)

-

DST (a.k.a. 'summer time') handling is always a delicate task which is -better left to the operating system which is supposed to be configured -by the administrator to behave correctly. Unfortunately, when doing -calculations with date outside of the range supported by the standard -library, we are forced to deal with these issues ourselves.

-

Several functions are provided to calculate the beginning and end of -DST in the given year and to determine whether it is in effect at the -given moment or not, but they should not be considered as absolutely -correct because, first of all, they only work more or less correctly -for only a handful of countries (any information about other ones -appreciated!) and even for them the rules may perfectly well change in -the future.

-

The time zone handling methods use these functions too, so they are -subject to the same limitations.

-
- -
-
-

Classes by category

-

Not done yet.

-
-
-

ID constants

-

wxPython provides the following predefined ID constants:

-

ID_ABORT -ID_ABOUT -ID_ANY -ID_APPLY -ID_BACKWARD -ID_CANCEL -ID_CLEAR -ID_CLOSE -ID_CLOSE_ALL -ID_CONTEXT_HELP -ID_COPY -ID_CUT -ID_DEFAULT -ID_DUPLICATE -ID_EXIT -ID_FILE1 -ID_FILE2 -ID_FILE3 -ID_FILE4 -ID_FILE5 -ID_FILE6 -ID_FILE7 -ID_FILE8 -ID_FILE9 -ID_FILTERLISTCTRL -ID_FIND -ID_FORWARD -ID_HELP -ID_HELP_COMMANDS -ID_HELP_CONTENTS -ID_HELP_CONTEXT -ID_HELP_PROCEDURES -ID_IGNORE -ID_MORE -ID_NEW -ID_NO -ID_NOTOALL -ID_OK -ID_OPEN -ID_PASTE -ID_PREVIEW -ID_PRINT -ID_PRINT_SETUP -ID_REDO -ID_RESET -ID_RETRY -ID_REVERT -ID_SAVE -ID_SAVEAS -ID_SELECTALL -ID_SEPARATOR -ID_SETUP -ID_STATIC -ID_TREECTRL -ID_UNDO -ID_YES -ID_YESTOALL

-
-
-

Source document

-

The source document is named wxPythonManual.txt and can be found by -clicking the link at the bottom of this page (assuming you are viewing -the html file). It is written using a fantastic formatting convention -called reStructuredText. The wxPythonManual.html file is created -using the Docutils utilities, which can turn reStructuredText -documents into html, xml, pdf, and even OpenOffice files.

-
-
-

Submitting changes to the source document

-

Some items in the source text file look like this:

-
-.. This is text from the wxWindows documentation that needs to be
-   translated into something appropriate for the wxPython version.
-   The two dots followed by uniformly indented text turns this
-   paragraph into a reStructuredText comment, so it doesn't appear
-   in any output file, such as the html file.
-
-

They have been commented out and are awaiting editorial review and a -rewrite so that they make sense in the context of wxPython. Feel free -to send me suggestions for rewording these, or any other parts of this -document that you think need improving. I will be eternally grateful -to you and will show my gratitude by adding your name to the list of -contributors. (Contributors who also send me gifts of coffee, -chocolate, or currency will have their names listed in bold.)

-
-
-

Contributors

-

Individuals who contributed to this documentation (in order by last -name):

- -
-
-

License

-

This document began as a translation of the wxWindows documentation. -As such, it adheres to the same license, which is provided here:

-
-                wxWindows Free Documentation Licence, Version 3
-                ===============================================
-
-  Copyright (c) 1998 Julian Smart, Robert Roebling et al
-
-  Everyone is permitted to copy and distribute verbatim copies
-  of this licence document, but changing it is not allowed.
-   
-                   WXWINDOWS FREE DOCUMENTATION LICENCE
-     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  1. Permission is granted to make and distribute verbatim copies of this
-  manual or piece of documentation provided any copyright notice and this
-  permission notice are preserved on all copies.
-
-  2. Permission is granted to process this file or document through a
-  document processing system and, at your option and the option of any third
-  party, print the results, provided a printed document carries a copying
-  permission notice identical to this one.
-
-  3. Permission is granted to copy and distribute modified versions of this
-  manual or piece of documentation under the conditions for verbatim
-  copying, provided also that any sections describing licensing conditions
-  for this manual, such as, in particular, the GNU General Public Licence,
-  the GNU Library General Public Licence, and any wxWindows Licence are
-  included exactly as in the original, and provided that the entire
-  resulting derived work is distributed under the terms of a permission
-  notice identical to this one.
-
-  4. Permission is granted to copy and distribute translations of this
-  manual or piece of documentation into another language, under the above
-  conditions for modified versions, except that sections related to
-  licensing, including this paragraph, may also be included in translations
-  approved by the copyright holders of the respective licence documents in
-  addition to the original English.
-
-                            WARRANTY DISCLAIMER
-
-  5. BECAUSE THIS MANUAL OR PIECE OF DOCUMENTATION IS LICENSED FREE OF CHARGE,
-  THERE IS NO WARRANTY FOR IT, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 
-  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
-  PARTIES PROVIDE THIS MANUAL OR PIECE OF DOCUMENTATION "AS IS" WITHOUT
-  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
-  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-  PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
-  THE MANUAL OR PIECE OF DOCUMENTATION IS WITH YOU.  SHOULD THE MANUAL OR
-  PIECE OF DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
-  NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  6. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
-  ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-  REDISTRIBUTE THE MANUAL OR PIECE OF DOCUMENTATION AS PERMITTED ABOVE, BE
-  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
-  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
-  MANUAL OR PIECE OF DOCUMENTATION (INCLUDING BUT NOT LIMITED TO LOSS OF
-  DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-  PARTIES OR A FAILURE OF A PROGRAM BASED ON THE MANUAL OR PIECE OF
-  DOCUMENTATION TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
-  OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-
-
-
-
-
-
-View document source. -Generated on: 2003-05-04 19:38 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/wxPython/docs/wxPythonTutorial.html b/wxPython/docs/wxPythonTutorial.html deleted file mode 100644 index 70a892df9b..0000000000 --- a/wxPython/docs/wxPythonTutorial.html +++ /dev/null @@ -1,129 +0,0 @@ - - - - - - -The wxPython Tutorial - - - - - - -
-

The wxPython Tutorial

-

How to get up and running with wxPython

- --- - - - - - - - - - - - - - -
Author:Patrick K. O'Brien
Contact:pobrien@orbtech.com
Organization:Orbtech
Date:2003-05-04
Revision:1.1.2.2
License:wxWindows Free Documentation Licence, Version 3
-
-

Contents

- -
-
-

Introduction

-

This is a tutorial for the wxPython GUI toolkit.

-
-
-

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:

-
-                wxWindows Free Documentation Licence, Version 3
-                ===============================================
-
-  Copyright (c) 1998 Julian Smart, Robert Roebling et al
-
-  Everyone is permitted to copy and distribute verbatim copies
-  of this licence document, but changing it is not allowed.
-   
-                   WXWINDOWS FREE DOCUMENTATION LICENCE
-     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  1. Permission is granted to make and distribute verbatim copies of this
-  manual or piece of documentation provided any copyright notice and this
-  permission notice are preserved on all copies.
-
-  2. Permission is granted to process this file or document through a
-  document processing system and, at your option and the option of any third
-  party, print the results, provided a printed document carries a copying
-  permission notice identical to this one.
-
-  3. Permission is granted to copy and distribute modified versions of this
-  manual or piece of documentation under the conditions for verbatim
-  copying, provided also that any sections describing licensing conditions
-  for this manual, such as, in particular, the GNU General Public Licence,
-  the GNU Library General Public Licence, and any wxWindows Licence are
-  included exactly as in the original, and provided that the entire
-  resulting derived work is distributed under the terms of a permission
-  notice identical to this one.
-
-  4. Permission is granted to copy and distribute translations of this
-  manual or piece of documentation into another language, under the above
-  conditions for modified versions, except that sections related to
-  licensing, including this paragraph, may also be included in translations
-  approved by the copyright holders of the respective licence documents in
-  addition to the original English.
-
-                            WARRANTY DISCLAIMER
-
-  5. BECAUSE THIS MANUAL OR PIECE OF DOCUMENTATION IS LICENSED FREE OF CHARGE,
-  THERE IS NO WARRANTY FOR IT, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 
-  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
-  PARTIES PROVIDE THIS MANUAL OR PIECE OF DOCUMENTATION "AS IS" WITHOUT
-  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
-  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-  PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
-  THE MANUAL OR PIECE OF DOCUMENTATION IS WITH YOU.  SHOULD THE MANUAL OR
-  PIECE OF DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
-  NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  6. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
-  ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-  REDISTRIBUTE THE MANUAL OR PIECE OF DOCUMENTATION AS PERMITTED ABOVE, BE
-  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
-  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
-  MANUAL OR PIECE OF DOCUMENTATION (INCLUDING BUT NOT LIMITED TO LOSS OF
-  DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-  PARTIES OR A FAILURE OF A PROGRAM BASED ON THE MANUAL OR PIECE OF
-  DOCUMENTATION TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
-  OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-
-
-
-
-
-
-View document source. -Generated on: 2003-05-04 19:38 UTC. -Generated by Docutils from reStructuredText source. -
- -