README.TXT for CUA'91 Skeleton 
==============================

Disclaimer:
    This sample code is intended solely to illustrate some of the 
    features of VX-REXX.  The code is provided "AS-IS" without 
    guarantee as to correctness or completeness.
    
Description:
    CUA91 demonstrates several VX-REXX features and programming 
    techniques relevant to developing CUA'91 compliant applications.
    It also demonstrates how to use subroutines contained in OBJMGR.VRS
    to simplify the process.
    
    This document consists of a description of these basic features 
    along with the coding techniques used to implement them.
    

Multiple Views of a Record
==========================

Description:
	Through the context menu each record can be viewed in detail
	(View A and View B).  Selecting a view for a record a second
	time moves the focus to the first view.  
	
	The icon of a viewed record is hatched to indicate it is in use.
	
Technique:
	When opening a record use the ObjectOpen(OBJMGR.VRS) function to
	do so.  ObjectOpen automatically handles window opening and hatching.
	When closing a window use the ObjectClosed(OBJMGR.VRS) function before
	destroying the window.  This automatically takes care of the hatching
	if the window happens to be the last view opened on an object.

Updating Views When Record Data Changed
=======================================

Description:
	Suppose we have several views open on an object.  If the user
	modifies the settings for that object, each of those views 
	(and the visual image of the record itself) should be updated.
	In the sample program this is done only when the user clicks
	Apply, but it could be done immediately as the setting is changed.
	
Technique:
	Store the record handle in the UserData of the settings Window.  
	When the user clicks Apply we can get at the record, which
	as mentioned above stores the windows of the views in global
	variable.  At this point we have the views of the record and the 
	new data, and must simply tell the views to update.  

	In the sample, we have created the several sections to handle 
	refreshes of each view.  These sections have the format 
	<windowname>_Refresh.  These sections tells the window what to
	do in case it needs to refresh.  And these routines are called
	by ObjectRefresh(OBJMGR.VRS) which is called by the application
	when ever data change takes place.  The reason why we need the
	<windowname>_Refresh sections is that ObjectRefresh actually
	created a pseudo-refresh-event which cause the application to 
	call <windowname>_Refresh.
	
INI Files
=========
	
Description:
	The position of the (main) window is saved in an INI file
	when quitting, and loaded (when present) to position the
	window when the program is restarted.  It also saves the objects
	informations and views opened for each of them at closing time
	and retore the state when the program is restarted. It is a short 
	step from here to a fully compliant CUA'91 program which would
	save and restore the entire environment (position of records 
	in the container, etc.)
	
Technique:
	We use the functions VRGetIni() and VRSetIni().  In the sample
	program the code is located in Init(), Fini(), CN_ObjectList_Init, 
	and CN_ObjectList_Fini.
	
	
Programming Tips
================

    -	Store all global data in a compound variable (eg Globals.)  
	
    -	Use ! to denote constant names in compound symbols (you would 
	therefore of course never start a variable with !)
	
    -	When working with multiple secondary windows (eg Settings windows
	for records), distinguish between the tools in each window by 
	using the toolname as a qualifier and the window id as a compound
	variable.  For example, instead of using
	
		call VRSet "LB_1", "Painting", 1
		
	use
	
		window = VRInfo( "Window" )
		call VRSet window || ".LB_1", "Painting", 1
		
	This will ensure you are setting the painting property of the
	list box in the current window.
	


Comments
========

    Please forward any comments to WATCOM VX-REXX Technical 
    Support Department:
    
        Phone:      (519) 886-3700
        Fax:        (519) 747-4547
        Internet:   tech@watcom.on.ca
        CIS:        GO WATCOM
