-*- mode:outline; -*-

wxWindows Xt port v1.64
=======================

* Copyright
-----------
Please refer to COPYING

* Motivation
------------
I've begun with the port because the binaries of wxWindows for XView
were enormously large. I'm working at home on a PC (i486 33 MHz 8MB)
and the binary of the wxWindows demo was around 480KB large (debug info
stripped of) PLUS the size of the shared XView library, which is about
1.3MB large.
  Besides I was interested in Widget programming and so I started with
it. The same demo has now a size of about 320KB, but it needs only the
standard X libraries, which are needed nearly by every X program. So
The size remains effektive 320KB and not 1.8MB. (The size of the demo
becomes larger, when you use WX resources, memory debugging, etc.)
  And: I liked the idea of a cross platform GUI development toolkit that
is in the public domain. As every other Linux user I had a lot of profit
from the Internet and I thought it was time to give something back.

* Documentation
---------------
Sorry, I didn't include the wxWindows manual in this distribution, but
this will be changed in the next release. Please look on the original
site (ftp.aiai.ed.ac.uk, /pub/packages/wxwin).

* Requirements
--------------
This wxWindows port should work on any X Windows system. Following
libraries are used:
	- libX11	; XLib
	- libXt		; XToolkit
	- libXaw	; Athena Widget set
	- libXmu	; Xmu functions
	- libiostream	; or any C++ library with stream classes
The Athena library is used for the text widgets and for the VendorShell.
At first I planned to search for a different text widget and to remove
the dependence on the Athena library, but it would be to much work. So
I've added 3D scrollbars to the text widgets and the dependence will
remain.
The other widgets are based on the FWF-library (Free Widget Foundation,
ftp.let.rug.nl, /pub/FWF). Most of them are heavily modified to fit to
my necessaries. Based on the xfwfCommon widget class I developed a 
canvas widget (a bit like the motif drawing area), a menu widget (now
with stay up menus and keyboard accelerators) and a new scrollbar widget
(based on the xfwfSlider widget).
  The keyboard traversal is done with TAB and Shift-TAB like with every
other widget set. Additionally one can use the cursor keys (home, up, down,
left, right). These are overriden, if the widget uses them itself (e.g.
the wxText uses home, left, and right). If you need to type a TAB into
a widget (text widgets or canvas widget) you have to quote it, i.e.
press "Ctrl-Q TAB" like in Emacs.

* Class Inheritances
--------------------
I've changed a few inheritances. In original wxWindows wxTextWindow,
wxCanvas, wxPanel, and wxFrame are derived from wxWindow. I changed it
to:
	wxWindow <- wxItem  <- wxCanvas
	wxWindow <- wxItem  <- wxText   <- wxTextWindow
	wxWindow <- wxPanel <- wxFrame

The idea is that panels contain something and even frames may contain
different items (panels, canvases, text windows). I allow panel in
panel placement by default - it doesn't mess up tab traversal. I'm
working on a solution for the default button setting.

* Event Handling
----------------
I've extended the eventhandling. Following methods
    - ENCAPSULATE the widget's default actions	     \
	-- OnChar()				      | This allows the   
	-- OnEvent()				      | replacement of    
	-- OnPaint()				      | default behaviour.
	-- OnScroll()				     /
    - are called BEFORE the widget's default actions \
	-- OnKillFocus()			      | This only allowes to
	-- OnMove()				      | add something - but
	-- OnSetFocus()				      | not to replace it!
	-- OnSize()				     /
If OnChar is called by a descendant, it is possible to change the values of
the wxKeyEvent-structure. It will be translated back to a XEvent structure
and executes afterwards the translations.
  Currently I don't the same thing for OnEvent and OnScroll, because there is
not much sense in translation the mouse events and if another scroll
behaviour is desired, the moving should be done by the wxWindow::Scroll
method.
  OnPaint doesn't encapsulate the drawing for the following widgets:
wxMenuBar, wxListBox, wxMultiText, wxText, wxTextWindow - for this widgets
OnPaint is called AFTER the standard expose method. For some widgets the
result will be another than desired (e.g. wxRadioBox).
  In original wxWindows these methods ar restricted to a few methods like
wxCanvas, wxPanel, and wxTextWindow. Remind that for compatibility!
  OnLeftClick and OnRightClick are called by the standard OnEvent method. There
is no sense in overriding both types of event handlers. This is consistent with
the way OnLeftClick and OnRightClick are handled for toolbars an for panel
item placement.
  The OnItem... event handlers are only called for wxPanel.

* wxWindow as a device context
------------------------------
I'd mostly appereciate to derive wxWindow from wxEvtHandler AND wxWindowDC
(wxWindowDC, wxCanvasDC, and wxPanelDC are handled for the Xt port as
aliases). But this leads to two different problems for which I don't have a
solution:
    - since wxWindowDC and wxEvtHandler are both derived from wxObject, the
      virtual destructor is ambiguous => the delete operator doesn't work
      correctly.
    - if you resolve the ambiguousity by deriving wxDC and wxEvtHandler
      virtually from wxObject (wxWindow : public virtual wxObject). But now
      the compiler comlains about casts e.g. from wxObject to wxWindow:
      wxWindow *win = (wxWindow*)(node->Date()).
One solution may be, if wxDC would not be derived from wxObject, but this
would contradict to the meaning of wxObject as a common root of all
wxWindows classes.
  Therefore I derive wxWindow from wxEvtHandler and implement all wxDC
methods inside wxWindow. The original methods are called by something like
if (dc) do_func;.
  To reduce memory usage I don't create a wxWindowDC by default (only for
wxCanvas and for wxPanel). But it can created and destroyed dynamically by
wxWindow::CreateDC and wxWindow::DestroyDC.

* GDI classes
-------------
I've added for those classes, that have a direct XWindows representation
reference counting. These classes are:
    wxBitmap, wxCursor, wxIcon
    wxColour, wxColourMap
    wxFont
    wxPen, wxBrush
All class member definitions are changed from pointers to instances, e.g.
wxColour *bg to wxColour bg. This allows to count the assignments and the
copy contructions (e.g. wxFont(wxFont& ref)). When ALL references are deleted,
the representation will be deleted too. This allows to free the resources
WHILE the application is running.
  Objects that are created using the GDI lists (wxTheFontList, etc.) are
persistent for the complete running time and will be deleted on application
exit.

* Application Frame
-------------------
The Xt port doesn't use a real application shell. I liked to implement
the behaviour e.g. used by XEmacs: the application exits, when the LAST
toplevel frame is deleted.

* Include files
---------------
I've tried to include as few include files as possible. The X include files
(X11/Xlib.h X11/XtIntrinsic X11/Xaw/*.h) are needed ONLY to build the
library. For the use of the library they are unnecessary. But some standard
header files are nontheless ever included:
    #include <stdio.h>
    #include <stdlib.h>
    #include <fstream.h>
This may be not compatible to standard wxWindows but it decreases the
compilation time; and the programmer has to know what he needs - to my opinion.
  I've introduced another include scheme - don't worry, there are AIAI compatible
include too. I've borrowed it from the Borland Turbo Vision library. The
following is from wb_form.cpp:

    standard wxWindows     |   wxWindows Xt port
    -----------------------------------------------------
    #include "common.h"    |   #define  Uses_wxItem       
    #include "wx_setup.h"  |   #define  Uses_wxButton     
    #include "wx_utils.h"  |   #define  Uses_wxMessage    
    #include "wx_dialg.h"  |   #define  Uses_wxChoice     
    #include "wx_item.h"   |   #define  Uses_wxCheckBox   
    #include "wx_buttn.h"  |   #define  Uses_wxText       
    #include "wx_messg.h"  |   #define  Uses_wxMultiText  
    #include "wx_choic.h"  |   #define  Uses_wxSlider     
    #include "wx_check.h"  |   #define  Uses_wxListBox    
    #include "wx_menu.h"   |   #define  Uses_wxRadioBox   
    #include "wx_txt.h"    |   #define  Uses_wxHashTable  
    #include "wx_mtxt.h"   |   #define  Uses_wxForm       
    #include "wx_slidr.h"  |   #include "wx.h"            
    #include "wx_lbox.h"   |   #include <ctype.h>         
    #include "wx_rbox.h"   |   #include <stdarg.h>        
    #include "wx_hash.h"   |
    #include "wx_mgstr.h"  |
    #include "wx_cmdlg.h"  |
    #include <stdlib.h>    |
    #include <stdio.h>     |
    #include <ctype.h>     |
    #include <stdarg.h>    |
    #include "wx_form.h"   |

Inside wx.h there is a dependency checking that cares for all further needed
header files. If you like the standard including more add following options
to your Makefile:
    -DNO_USES_DEFINES -IAIAI-include
All samples/utils are compiled this way - look for the Makefiles.

* XPM
-----
Since the XPM library is available on the most XWindows systems I do not
include it in the wxWindows library. You have to link it seperately to your
applications (-lXpm). You find in src/wxSetup.h a line like
	#define XPM_INCLUDE <X11/xpm.h>
Change it, if "xpm.h" is in a different directory.
  For those, who don't have the XPM library on their systems I've included
the library to this distribution (contrib/xpm). Follow the instructions in
contrib/xpm/README. I do NOT depend on this version of XPM (3.4g) - everything
should work as of version 3.4b.

* Debug Ouput
-------------
I've added to command line options to enable different debugging outputs.
  -debugOutput: Does the same as wantDebugOutput = TRUE, i.e. prints all messages
		using wxDebugMsg.
  -debugEvents: Traces all X events that arrive to the application: the name
		of the wxWindow/XWidget is displayed and the event-type.
		Sometimes it is really nice to know, which events arrive to
		the application and e.g. to know which event causes an error.
		(Only, if DEBUG=1)
		Since all events are diplayed, try s.th. like
		  ./app -debugEvents | grep -i "focus"
		This will display FocusIn/FocusOut events only. The used event
		names are the same as used by Xlib. For more detail view
		src/xt/APP_app.cpp: wxApp::MainLoop().
  -debugMemory: (if DEBUG=1, USE_MEMORY_TRACING=1, USE_GLOBAL_MEMORY_OPERATORS=1)
		switch memory debugging on and trace all new and delete functions.
		  It traces non-Objects allocations too, if compiled in. It is not
		recommenable to use SetDebugMode(TRUE, FALSE) during the
		application flow, since memory allocated using the debugging mode
		MUST be freed using the debugging mode - the same for not using
		the debugging mode.
		  TRACE is not affected by this option.
		  At application exit a memory dump and memory statistics are
		printed. This is done twice:
		  - the first output prints everything allocated after the start
		    of the main function without the GDI-classes that are inserted
		    in the GDI-lists (wxFontList, wxPenList, etc.) since they are
		    freed at application exit.
		  - the second output prints "globally" allocated memory too, since
		    it is possible too allocate memory outside a function body or
		    inside a class constructor (these are called BEFORE main).

* Bugs and an exhortation
-------------------------
wxWindows, like most other software, has the occasional buglet
(BUGS contains a list of some of them). I would be grateful for
bug reports (even better, fixes) though I can't guarantee to integrate
them.  Meanwhile, please do join the growing wxWindows community: it's
fun, and it's going places. The more contributors, the stronger
the chances that it will be the best toolkit of its type within
the next year or so.

* wxWindows discussion forum
----------------------------
There is a mailing list for users or potential users of wxWindows. Send
a request to wxwin-users-request@aiai.ed.ac.uk or J.Smart@ed.ac.uk to
subscribe to (or unsubscribe from) the mailing list. Note that these
messages go to Julian, it's not yet automated.

General discussions take place on wxwin-users@aiai.ed.ac.uk;
wxwin-announce is for people preferring lower bandwidth, and I will
always send announcements to wxwin-users as well as wxwin-announce. So
there's not usually a need to subscribe to both. wxwin-dev is for
discussion about future developments for wxWindows.

-------------------------------------------------------------------------------
Markus Holzem
Schlossparkstrasse 3
D-52072 Aachen
GERMANY

VOICE: +49 (241) 14145
EMAIL: mho@comnets.rwth-aachen.de
