
               ----------------------------------
               Overview for AWT-Layout's contrib.
               ----------------------------------

Version: 0.1
Updated: 2000/01/19
Authors: Aleksandras Gluchovas
 E-mail: <alex@soften.ktu.lt>
    URL: http://soften.ktu.lt/~alex/bugtracker/

Updates

1. Interface-level complience with Java's AWT
2. "Two-pahse layouting" feature
3. Concept of "Component's Peer"
4. Building this contrib.
5. Problems runing it with wxGtk
6. Tips for trying it

Abstract
--------

contrib. contains wxWindows based C++ classes
which try to mimic functionality and interfaces
of AWT layout managers in the corresponding classes
of JDK 1.0-1.2 ( in javax.awt and javax.swing packages)

Interface-level complience with Java's AWT
------------------------------------------

The strength was to make C++ versions of theres classes
similar to AWT ones in behaviour and also at level
of their public-interfaces. Initially, it seamed
reasonable to derive thse classes from wxSizer class, 
but later on it appeared that this way interface-complience 
cannot be fully maintained, e.g.:

in wxWIndows we don't have containers which are not bound
to native window, therefor we use netsing of wxSizers inside
each other, that is - one layout mgr. directly contains another.
but in AWT has a logical separation between container and 
layout-manager, thus it makes "derivation from wxSizer" approach
tricky or even impossible.

Thus, the design was turned to follow full interface-complience 
with AWT, additionally it allows for easier conversion of geneated
java GUI-code designed using powerfull GUI-designers for java, and
then use this converted code in C++, e.g.

java code:

	Container panel = new java.awt.Container();
	ponel.setLayout( new java.awt.FlowLayout();
	
	panel.add( new JButton("Hello" );
	
could be converted to C++:

	Container* panel = new Container( this );
	ponel->setLayout( new FlowLayout() );
	
	panel.add( new wxButton( this,-1, "Hello" ) );

As you notice, there beside layout-managers there are
other classes introduced for AWT-complience, they form
a mini-framework which wraps native wxWindow classes
the way "awt.dll" Java VM does for every platform.
Further this fmw. is refered as AWT-Emulation-Framework (AWTEF)

For info on how to use these layouts in your wxWin. apps, 
download docs. of JDK 1.1 or 1.2, and learn about layout managers.
Also look at the layout_test.cpp which contains sections for
each testing each C++ based layout manager.

"Two-pahse layouting" feature
-----------------------------

This feature is NOT present in AWT, in fact, this is AWT's lack
i've noticed long ago, and now it's elimiated in this "C++ version".

The problem is, that when a composite component is requested to give
it's prefered size, at this point it does not know the dimensions
of the parent which is asking him now... the lack of info about 
parent's dimensions cuases e.g. flow-layout to give calc. it's pref
dimensions in the "unconstrainted" way, i.e. not wrapping it's
items around the edges of the parent, thus giving not really correct
*prefered-height*. 

To obtain the necessery parent-size info, we lay out the container
twice, first to see how parent lays out it's children and what
sizes do they get, second to get the right pref. sizes (when 
sizes of all parent are already calculated form Phase-I) and
relayout the children with "awearness" of parent's size

Concept of "Component's Peer"
-----------------------------

Each compoenet in AWTEF (like in AWT) may have it's corresponding
native window, the class which wraps-up this native window is
called "peer", and is derived from java.awt.ComponentPeer. 
In the case of AWTEF, there componentpeer is simply typedef'ed
to wxWindow. 

Also, in the case when component's peer == NULL, the component
is considered light-weight (i.e. without it's native equivalent),
and is rendered using it's paint() method.

Building this contrib.
----------------------

You'd have to copy The source of distribution into "awtlayouts"
directory in you "wxgtk/samples/" or "$(WXWIN)\samples\" (on Windows)

If unix, then run configure to any other means to process Makefile.in.

then make it.

The makefiles may be buggy, please report them to me (alex@soften.ktu.lt),
i'll try to fix them and post on wx-developers list.

Problems runing it with wxGtk
-----------------------------

the library i am using is rather old one (perhaps 2.0.1), thus
there are things like wxMenuBar slipping over main panel,
double-buffering does not work (because of auto-erasing of
background under X). The wxgtk, that i have crashes when
i try to create wxStaticText, there for it is #ifdef'ed to
wxPanel for non-windows plaftroms.

Also, if you rand from differenet directory then the one
containing .cpp files (e.g. form ./Linux), then copy 
"layout_test.cpp" to that directory, otherwise the you'll
not be able to see the source code for each layout

Tips for trying it
==================

Try to choosing different fonts (size/face/etc).

Settings dialog may be keept on top if you press
"Apply" buttton (not "Apply and Exit"), that way
you can see how different settings affect layout
without leaving the settings-dialog. The feautre
i've used very well myself, while "hunting" bugs... :)