/****************************************************************************
 File: readme.txt

 (C) Copyright 1992 by GO Corporation, All Rights Reserved.

 $Revision:   1.1  $
   $Author:   cbazzare  $
     $Date:   17 Mar 1992 13:56:58  $

 List Box demo is yet another sample application meant to help developers 
 learn how to use some of the features of PenPoint. This demo does not 
 implement a whole application. Instead, it shows, in an clear way, how 
 to organize and program an application incrementally. In fact, List Box
 demo was the starting point for a richer sample application called
 Video Player.

 List Box demo tries NOT to show lots of functionality, which makes it 
 hard for developers to reuse and learn from the sample code. This release 
 shows how to set up a window using U.I toolkits, including a list box. 
 The menu bar supports standard menus. The more interesting code is related
 to the list box. The list box window supports the copy/move protocol
 to move (shuffle) and copy rows among itself or other window that supports
 the transfer of text. The list box also handles some gestures such as 
 the caret gesture to insert a row  and the scratch out or cross
 gesture to delete a row from the list box.  

****************************************************************************/

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *	     			Objectives	 			   							   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
 This sample application shows how to:

	-:	embed data in the list box such as list contents and row state
	-:	save and restore the list contents (filing)
	-:	handle gestures in a list box
	-:	support the copy/move protocol
	-:	deal with theSelectionManager
	-:	create a graphical interface with the U.I toolkit, including
		a list box.
	-:	add application-specific menus to the standard menus.

*/

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *   				Class Overview	 			   						   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
 List Box demo defines two classes: clsLBdemo and clsLBList.
 It makes use of the following classes:

	clsApp
 	clsAppMgr
	clsClass
	clsLabel
	clsListBox
	clsMenu
	clsObject
	clsXferList

*/

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *   				Files Used	       			   						   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* 
 The files for List Box demo are:

	MAKEFILE		the watcom compatible make file
	METHODS.TBL		contains the method tables for the two
					classes used in List Box demo.
	LBDEMO.C		contains the List Box demo application class
					and the code to build the interface from
					the U.I toolkit
	LBDEMO.H		header file for the application class.
					Defines the instance data held by the
					application and my list box class.
	LBLIST.C		contains the definition of my list box and
					support methods for gesture processing and
					list manipulation.
	LBLIST.H		header file of my list box.
	LBXFER.C		contains code to support the copy/move of
					rows. Text is the tranfer type.
*/ 

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *		     		Architecture   				   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* 
 List Box demo creates 2 classes. One is the application class which supports 
 the application framework. The other is for a generic list box manipulating
 class. Both have instance data that points to the following data structure
 that is allocated and freed by the application class. 

typedef struct LBDEMO_APP_DATA {
	OBJECT				lbdemoWin;
	OBJECT				headerWin;
	OBJECT				swWin;			    ^
	OBJECT				menuBar;		    | 1
------------------------------------------------------------------      
	BOOLEAN				deselect;		    | 2
	WIN			   		previousSelWin;	    v
	U16			   		previousPos;
} LBDEMO_APP_DATA, * P_LBDEMO_APP_DATA, ** PP_LBDEMO_APP_DATA;

 This data structure is divided into 2 parts. Part 1 has the object uid
 of some of the major U.I components and Part 2 has some data needed by
 my list box to keep track of the selected row. The following are the reasons
 why I decided to use such an arrangement.

 1 : Don't need to ObjectWrite every time I change instance data.
 2 : Instance data grows easily and is in one place
 3 : makes setting clients and parent relations easier.
 4 : avoid the need to have to send messages to get a visual object uid.
 5 : only allocates memory once, thus it does not fragment memory
 6 : makes code shuffling and U.I sub-classing easier

 Notes on my list box class :

 My list keeps all rows live and does not dispose unseen rows. This is not
 bad for now since I only have one label window per row but it probably 
 would need to be changed if you were concerned about optimizing your
 memory usage. This is what has to be done: Overwrite the method for 
 the message "msgListBoxDestroyEntry" so when a row is not seen and is
 deleted you save its label in the "data" field of the entry. This field
 can then be used to regenerate the label when the row is shown again, by
 the message "msgListBoxProvideEntry". If you do this, don't forget to
 free this pointer when the list is destroyed.

*/

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *		     		Compiling   				   						   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* 
 To compile List Box demo, just 
	wmake

 This compiles the application and creates its executable
 in  \PENPOINT\APP\LBDEMO.
*/

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *  				Running	  	   			   							   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* 
 After compiling List Box demo, you can run it by
    1) Adding \\boot\penpoint\app\List Box Demo to \PENPOINT\BOOT\APP.INI
    2) Booting PenPoint
    3) Creating a new List Box demo document, and turning to it.
 
 Alternatively, you can boot PenPoint and then install List Box demo
 via the Connections Notebook.
*/

