This is the first public release of wxPython.  I consider this alpha
code, as nobody but myself has ever tried wxPython.  Hopefully this
will serve as a good 'proof of concept.'

------------------------------------------------------------------------


Table of Contents

1. Introduction
2. Design and supported Classes
3. Implementation
4. Example programs
5. Installation
6. Known Bugs
7. Future
8. Copyrights

------------------------------------------------------------------------
1. Introduction

wxPython is a marriage of Python and wxWindows. Python is a neat
little object oriented language complete with classes, inheritance,
etc.  wxWindows is a portable GUI class library written in C++. It
supports Xview, Motif, MS-Windows as targets.  There is some support
for Macs and curses as well.  wxWindows preserves the look and feel of
the underlying graphics toolkit.

So with wxPython it is possible to write portable Python programs with a
GUI.  It is quite good for rapid prototyping.

The shortest possible hello world program in wxPython:

	from wxwin import *
	print 'Hello World'

For more information on Python, see 
	http://www.cwi.nl/cwi/people/Guido.van.Rossum/Python.html
For more information on wxWindows, see 
	http://www.aiai.ed.ac.uk/~jacs/wxwin.html


Why another GUI interface to Python?
The advantages over STDWIN, vpApp and tkInter are the following:

- Portable GUI
- Preserves native look an feel
- wxWindows has a quite large and active user base, and active 
  development
- With this tool you can write programs for your non-programming
  MS-Weenie friends, without ever leaving your belowed Unix
  environment ;-).

------------------------------------------------------------------------
2. Design

I attempted to mirror the class hierarchy of wxWindows in Python.
It would have been possible to implement some things in a more
natural way than wxWindows does, but I opted not to.  For one, now the
user can use the existing wxWindows documentation to use wxPython
classes.  wxPython can be used as a prototyping tool, and the code can
later be converted to C++ only, if so desired.  If more powerful
functions and classes are needed, those can be easily coded in Python
on top of the existing ones.
 

------------------------------------------------------------------------
3. Implementation

I borrowed a lot from the wxClips implementation, which is also quite
evident from the code.  In the implementation I have used python 1.1.1
and wxWindows 1.60pl7.

wxWindows is not really embedded in Python. As the main() function
comes from the wxWindows library, it is more like Python is embedded
in wxWindows.  As a default it launches a very minimal IDE, from
which you can edit and run python programs.  However, it is also
possible to run the programs without the IDE.

The following classes are supported in wxPython:

class wxWindow:
class wxFrame(wxWindow):
class wxMenu:
class wxMenuBar:
class wxPanel(wxWindow):
class wxCanvas(wxWindow):
class wxPen:
class wxBrush:
class wxFont:
class wxBitmap:
class wxIcon:
class wxMessage:
class wxSlider:
class wxText:
class wxListBox:
class wxChoice:
class wxRadioBox:
class wxButton:
class wxCheckBox:
class wxMultiText:
class wxTextWindow:

Not every wxWindows method of the above classes is supported, see
wxwin.py for more details.

Additionally, the file selection box function wxFileSelector() is
there, as is the wxMessageBox() function.


------------------------------------------------------------------------
4. Example programs

You invoke wxPython in one of the three ways:

wxp			; just runs the IDE
wxp -e demo1.py		; runs the IDE and load demo1.py to the editor
wxp hello.py		; does not run the IDE, but executes the hello.py


4.1 demo1.py

Here is the entire application

from wxwin import *	

class demoApp(wxFrame):
    def __init__(self):
	wxFrame.__init__(self, 
			 None, "A Small wxPython App", 50, 50, 200, 150)
	self.panel = wxPanel(self, 0, 0, 400, 300)
	wxButton(self.panel,self.ButtonCB, "Hello")
	self.panel.NewLine()
	self.icon = wxIcon("python.xbm")
	wxFrame.SetIcon(self, self.icon)
	self.Show(1)
    def ButtonCB(self):
	print "This is a message to stdout"
	wxMessageBox("Hello to you too!")

demoApp()

You run the demo by loading the file 'demo1.py' to wxPython IDE, and
then clicking on 'Execute' button.  Note, you cannot run this directly
with 'wxp demo1.py', as it does not define a main window.

The demo pops up a window with a button, and a message box once you press
the button.  

4.2 demo2.py

This demostrates the use of wxButton, wxChoice (optionmenu),  and
wxListBox.

You can run this demo directly with the 'wxp demo2.py' command-line.

4.3 chartdemo.py

This runs a simple pie chart using wxCanvas.  You can set the pie
slices interactively.


4.4 hello.py

This demonstrates pretty much everything wxPython can currently do.
It corresponds to the hello.cc demo found in wxWindows distribution.
Note that all the menu items are not supposed to work.

------------------------------------------------------------------------
5. Installation

If you want to compile wxp yourself, you need to have both Python and
wxWindows installed in your machine. 

If you just want to have a test-drive, I have provided two
binary distributions.

5.1 Binaries

There are pre-built binaries for Linux+Xview and MS-Windows.
These are self-contained packages, as both wxp-msw.tgz and wxp-linux.tgz
contain a small part of the Python library code in addition to wxPython
code.  The archives will unpack to wxp-0.1 directory. 

The linux binary is linked shared on my oldish setup, with X11R5.
It should run on most Slackware based linux systems that have Xview
installed.

# ldd wxp
	libxv3.so.3 (DLL Jump 3.0) => /usr/openwin/lib/libxv3.so.3.0
	libolg.so.3 (DLL Jump 3.0) => /usr/openwin/lib/libolg.so.3.0
	libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
	libm.so.4 (DLL Jump 4.5pl24) => /lib/libm.so.4.5.24
	libc.so.4 (DLL Jump 4.5pl24) => /lib/libc.so.4.5.24

If you like the binaries and don't wish to recompile, I strongly
suggest that you install the full Python libraries, as those contain
many goodies.


5.2 Compiling

Besides wxWindows and Python distributions, you only need
wxp01src.tgz.  The source is the same for both Unix and MS-Windows
versions.  The source archive is included in the binary distribution
as well, as it is only about 50K.


5.2.1 Unix

You can build wxPython like a Python extension.
It will unpack itself to Extensions/wx.

Edit Makefile.pre.in, and follow the instructions in it.

Note, you must delete frozenmain.o from libPython.a, otherwise there
is a conflict with the main function in the wxWindows library.

ar ds libPython.a frozenmain.o 

does the trick on Linux.


5.2.2 MS-Windows

First of all, I haven't tested the MS-Windows version of Python much
at all, so you are on your own there.  All the example wxPython
programs work for me, that's all I can say.

The dos makefiles are a bit odd, since I modified them from the
makefiles I had for building Python with Turbo C 2.0.
So the make I used is the old Turbo C make.  It should be straight
forward to modify the makefiles to work under nmake, or some other
make.

The compiler I used is Visual C++ v1.5.

Build sequence:

1. untar Python source
2. cd python-1.1, untar wxp source
3. move all the .cc and .h files in Extensions/wx to 'python-1.1/modules'
4. untar dosmake.tar from the Extensions/wx directory in python-1.1
   directory.  (cd python-1.1; tar xvf Extensions\wx\dosmake.tar)
5. run makeall.bat
6. proceed to fix all the makefiles, as you probably don't have the Turbo
C 2.0 make around, :(.  


------------------------------------------------------------------------
6. Known bugs

MS-Windows version does not know how to load bitmaps or icons.

My DOS build of python may be broken, it seems that some things in
standard Python library do not run.

Running the hello.py demo from the IDE twice does not work.

All in all, I've developed this under Linux+Xview, so it should be the
most stable platform.  

It may leak memory somewhere, haven't checked yet. Remember, this is
alpha code.  Bug reports are welcome. 

------------------------------------------------------------------------
7. Future


I plan to encompass more of the wxWindows functionality, top four:

- Printing support
- Toolbar support
- Cursor support
- Python debugger support

There is also wxWindows 1.61 beta out, and Python 1.2 looming in the
near horizon.

I've been doing this on my own, usually late at night after tucking in
the kids, so the going has been slow.  I welcome any help, especially 
under the MS-Windows side, which I'm not terribly fond of.


Harri Pasanen

Harri.Pasanen@tekla.fi



------------------------------------------------------------------------
8. Copyrights


8.1 Python

Copyright Notice
----------------

The Python source is copyrighted, but you can freely use and copy it
as long as you don't change or remove the copyright:

Copyright 1991, 1992, 1993, 1994 by Stichting Mathematisch Centrum,
Amsterdam, The Netherlands.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


Signature
---------

--Guido van Rossum, CWI, Amsterdam <Guido.van.Rossum@cwi.nl>
<URL:http://www.cwi.nl/cwi/people/Guido.van.Rossum.html>


8.2 wxWindows


Copyright (c) 1994 Artificial Intelligence Applications Institute,
The University of Edinburgh

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice, author statement and this permission notice appear in
all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR THE
UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF
DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH
THE USE OR PERFORMANCE OF THIS SOFTWARE.


8.3 wxPython

(I hope Python's copyright notice is not copyrighted :))


Copyright Notice
----------------

The wxPython source is copyrighted, but you can freely use and copy it
as long as you don't change or remove the copyright:

Copyright 1995 by Harri Pasanen, Espoo, Finland.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Harri Pasanen will not
be used in advertising or publicity pertaining to distribution of the 
software without specific, written prior permission.

HARRI PASANEN DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


Harri Pasanen

Harri.Pasanen@tekla.fi
