               -----------------------------------------
               wxWorkshop's v-0.6 Tutorial (in progress)
               -----------------------------------------

Version: 0.1
Updated: 2001/02/15
Authors: Aleksandras Gluchovas
 E-mail: <alex@soften.ktu.lt>
    URL: http://www.soften.ktu.lt/~alex/


Content
=======

The tutorial and sample demonstrates and explains
the following features:

1. Linked UI
2. Matrix-agl. guarded item layout
3. In-place switchable UI (wxCardCtrl)
4. Specifying custom classes to be instantiated
   instead of standard ones for handling particular 
   UI items ("UI-subclassing").
6. RAD Overview.
7. WSPP widgets

Each of these items will be described with
respect to the sample's source code and it's resource
structure, as well as by explaining how these items can
be created and manipulated via wxWorkshop's UI-editor and RAD.

1. Linked UI
============

The purpose of Linked UI is to enable reuse of
distinct UI-elements in different places/contexts
of the same resource. Effectively, prevents Cut&Paste
practice used to cope with repeating UI compositions. 
In resource file, reference to linked UI element
is placed using "object_ref" tag instead of "object":

	<object_ref name="panel1">
		<pos>15,15</pos>
		<size>315,85</size>
	</object_ref>

(look for this fragment in demo.xrc)

Where the "panel1" resource itself is described
separately as top-level resource:

	<object class="wxMatrixPanel" name="panel1" subclass="MyPanel">
		<pos>0,0</pos>
		<size>185,90</size>
		<style>wxSUNKEN_BORDER</style>
		<object class="wxButton" name="hello">
			<pos>10,10</pos>
			<size>70,25</size>
			<label>Hello!</label>
		</object>
		.....................
	</object>

In the sample's main frame, the "panel1" item is linked twice:
once in the top-right corner of the frame, another time into
the "Link Page" of the notebook.

Another example of linking is "DbCard" resource, which is
linked into "Query Page 1" and "Query Page 2" pages
of the notebook.

From UI-Editor, linking is done by selecting "Item | Insert Link to Item",
then selecting top-level resource to be linked, and clicking on the
target UI item, into which the selected resource should be linked.

2. Matrix-agl. guarded item layout
==================================

If you are not familiar with Matrix's concepts, read
about it on http://wxWorkshop.sourceforge.net

The following UI items are supported with Matrix guard:

wxPanel
wxFrame
wxDialog

When creating any of these items, they can be created
either with or w/o matrix guard, the guard is on when
the selected resource for creation is prefixed with
"wxMatrix", e.g. wxMatrixPanel or wxMatrixFrame, otherwise
the resource is not matrix-guarded.

After guarded resource is created, in it's property-sheet,
there is "autosize" option, which specifies if these
initial size of control should be automatically adjusted
to fit it's best size calculated by matrix alg. If the
object is not checked, the control will appear in the
size set in the UI-Editor. The "autosize" feature is
only useful for top-level windows, such as frames,
since the child windows are usually constrained
by extent of their parent.

Sample's main "MyFrameRes" and "panel1" resources are matrix-guared,
where "MyFrameRes" has also "autosize" option set to
make the frame best-fit in it's contents. The effect
of this can be seen by comparing the size of "Quit" button
on the mainframe when the frame is shown in preview
(or by running the sample) versus it's design representation.
It's designed size purposely made too small, but matrix
alg. correct's its size and additionally makes the
frame larger (regards "autosize" option) to fit in
corrections made.

4. In-place switchable UI (wxCardCtrl)
======================================

wxCardCtrl is a UI-item which contains any number
of child items, of which only one is shown at a time.
Workshop supports editing of this item together
with it's child-items in design mode, by providing
"switching-hints" area, showing which child item
is currently showing (edited), and allowing to switch
editable item by clicking on a different cell within
the "hints" control.

To switch "cards" at run-time, user-code may invoke
ShowCard( wxWindowID id ) method of wxCardCtrl.

Sample has "DbCard" resource which contains two,
cards, the first for setting up ODBC parameters,
and another for displaying results of the specified
query. In the sample's code run-time switching is done 
as follows:

void DbCard::OnButtonRun( wxCommandEvent& event )
{
	ExchangeValues( FALSE );

	m_pDblist->SetODBCDataSource( m_Dsn, m_User, m_Password );

	if ( m_Sortcol.Length() )

		m_pDblist->Sort( m_Sortcol, !m_Descending );

	m_pDblist->RunQuery( m_Query );

	ShowCard( XMLID( "resultspanel" ) );
}

Note, that instead of integer wxWindowID, XMLID(..)
macro is used to translate string-literal based
id of the card into it's numeric value.


5. Specifying custom classes to be instantiated
   instead of standard ones for handling particular 
   UI items ("UI-subclassing").
   =================================================

Subclassing UI-Item is a feature allows specifying
user-written classes to be instantiated for particular
UI-items. In the UI-Editor, there is "subclass" field
for each item, which can be seen and modified in the
property-pane. Default value of this field is an empty
string, which tells resource system to use "standard"
class for instantiating UI-Item at run-time, e.g. for
"wxTextCtrl" UI-item "wxTextCtrl" class will be used.
Otherwise, if the field is not empty, resource system
will try to instantiate the specified "subclass" dynamically.
If the given class name is not found within the list
of dynamic classes, error with occur. Therefore any
custom-class which was meant to replace standard
classes within UI resource, should be declared as
dynamic class, e.g. in the sample:

class MyTextCtrl : public wxTextCtrl
{
public:
	MyTextCtrl();
	~MyTextCtrl();
	..........
	DECLARE_DYNAMIC_CLASS( MyTextCtrl )	
}

and in the mytext.cpp:

...
IMPLEMENT_DYNAMIC_CLASS( MyTextCtrl, wxTextCtrl )
...

Class MyTextCtrl is used for creating "textctrl1" item
within sample's main frame. This class also demonstrates
how custom class can change appearance or behavior
of particular widget, e.g. MyTextCtrl intercepts
"wxPaintEvent" and draws rounded rectangle around
the text-entry area of "textctrl1" UI-item.

6. RAD Overview
===============

TBD:: some intor...

All RAD features are accessible through workshop's "Source"
menu. At any time it has "New" item enabled, which allows
generating new source files for UI-items, other items in
this menu are only when particular RAD-generated source
file is opened. Workshop automatically distinguishes
between normal and RAD-generated files by scanning
their content and finding it's special tags placed
within source's comment lines.

.......


7. WSPP widgets
===============

...............

l8er
