zListViewer
=============================================================================

	Summary  A view class for managing lists of items in full-screen mode.

	Remarks  zListViewer is a generic list box class that handles a
	         scrolling list of items. It supports multiple lines per item,
	         and the arrow keys for common usage. Its functionality has been
	         proven in the three recent Silicon Creations, Inc. releases
	         (mail-x, TopTagz, and Listerz) which use it. Because the source
	         code for these programs is available, no example is provided in
	         this package.

	Note     To use the list viewer, you should derive the zDoubleList
	         objects from the zListRecord class. This is a virtual class
	         which implements the common interface expected by zListViewer.
	         Specifically, you should create your own constructor to handle
	         the data setting, as well as the draw() and the select()
	         methods (required). You can also choose to implement the
	         toggleTag() method too. The three drawing functions will handle
	         the drawing of each of your records. It is up to you to
	         determine the appearance and the number of lines. You MUST
	         derive your list records from this base class for the whole
	         thing to work.


	ZLISTVIEWER::ZLISTVIEWER
	-------------------------------------------------------------------------

		Summary   Constructor for the list viewer.

		Syntax    zListViewer(const zRect &bounds, zDoubleList *aList);

		Remarks   Constructs (does not display) a list box and assigns
		          'aList' to it. You should construct the list before
		          creating the list box. The 'bounds' parameter defines
		          the location and size of the list box on the screen.

		Return    n/a


	ZLISTRECORD::ZLISTRECORD
	-------------------------------------------------------------------------

		Summary  Constructs a record for the list viewer's list.

		Syntax   zListRecord();

		Remarks  This is the default constructor for the items in the list
		         managed by the list viewer. It sets the number of rows for
		         the item to 1.

		Return   n/a


	ZLISTVIEWER::HANDLE
	-------------------------------------------------------------------------

		Summary   Handles a keystroke.

		Syntax    void handle(ushort &aKeyCode);

		Remarks   This is the principal event handler for the list box. Note
		          that the list box does not seek input, instead it expects
		          to be given keys to handle via this method. You can pass
		          any keystroke, but only the direction keys will be
		          recognized and interpreted. zListViewer will utilize left,
		          right, up, and down direction keys, as well as Home and
		          End. Also, the numbers '4', '6', '8', and '2' are mapped
		          to the corresponding direction keys (see the keypad) as
		          well as '7' and '1' to Home and End. Should you decide you
		          don't want this behavior, you can filter the keys before
		          handing them over to the list box. If the key was
		          recognized and interpreted, the aKeyCode reference will be
		          set to 0, otherwise, it will be left unchanged.

		Return    Nothing.


	ZLISTVIEWER::DRAW
	-------------------------------------------------------------------------

		Summary   Draws the list on the screen.

		Syntax    void draw();

		Remarks   Redraw a full screen of the list box. The actual appearance
		          is determined by your application (the TListRecord-derived
		          class' draw() method will be invoked for each item on the
		          list). This function supports multiple lines per record
		          (but if the line count exceeds the number of available
		          lines on the screen, it should be truncated).

		Return    Nothing.


	ZLISTVIEWER::SETFOCUS
	-------------------------------------------------------------------------

		Summary   Focus an item to make it visible.

		Syntax    void setFocus(void *item);

		Remarks   Sets the focus to the item pointed to by the 'item'
		          argument. This should be an item in the list. The list box
		          will be scrolled if necessary to bring the item into view.

		Return    Nothing.


	ZLISTVIEWER::DRAWFOCUS
	-------------------------------------------------------------------------

		Summary   Redraw the focused item.

		Syntax    void drawFocus();

		Remarks   Redisplays the focused item. This is very useful if you
		          made some changes in the data which will trigger a change
		          in the visual apearance. Instead of redrawing the whole
		          screen, you can choose to redraw the focused item only.

		Return    Nothing.


	ZLISTVIEWER::NEWLIST
	-------------------------------------------------------------------------

		Summary   Assigns a new list to the list box.

		Syntax    void newList(zDoubleList *aList);

		Remarks   Assigns a new list object to the list box. Note that the
		          old list will not be deleted by this function. You should
		          handle this yourself. Only a new list will be assigned.
		          This will not redraw the screen either. Use the draw()
		          method.

		Return    Nothing.


	ZLISTVIEWER::FOCUSED
	-------------------------------------------------------------------------

		Summary   Retrieve item's data.

		Syntax    void *focused();

		Remarks   Invokes the get() zDoubleList method on the focused item,
                  effectively returning the data associated with it.

		Return    Pointer to the item's data.


	ZLISTVIEWER::FIRSTITEM, ZLISTVIEWER::LASTITEM
	-------------------------------------------------------------------------

		Summary   Check if first/last items are visible.

		Syntax    Boolean firstItem() const;
                  Boolean lastItem() const;

		Remarks   This function checks to see if the last item from the list
		          is currently visible. Very useful for "more" prompts and
		          status lines. Returns True is the last item is visible and
		          False if not. firstItem() is the same as lastItem() except
		          it checks the visibility of the first item from the list.
		          Returns True if the item is currently visible and False if
		          not.

		Return    firstItem() returns True if first list item is visible
		          lastItem() returns True is last list item is visible


    ZLISTVIEWER::SETCLEARCOLOR
	-------------------------------------------------------------------------

	    Summary   Sets the color attribute used to clear the box.

	    Syntax    void setClearColor(uchar attrib);

	    Remarks   The default setting for the clear attribute is white on
	              black. This works fine if your items draw themselves on
	              a black background. However, if you want to use another
	              color, you need to explicitly set the attribute with this
	              function call. The format of the color atribute is the
	              standard PC conio.h layout.


	ZLISTRECORD::TOGGLETAG
	-------------------------------------------------------------------------

		Summary   Change the tagged status of an item (visually).

		Syntax    virtual void toggleTag();

		Remarks   By default does nothing. You can override it to force a
		          redraw of the item when the tag status changes.

		Return    Nothing.


	ZLISTRECORD::DRAW, ZLISTRECORD::SELECT
	------------------------------------------------------------------------

		Summary  Routines which control the appearance of the list viewer.

		Syntax   virtual void draw(const zPoint &origin, short maxlen) = 0;
                 virtual void select(const zPoint &origin, short maxlen,
                                     Boolean off) = 0;

		Remarks  The zListRecord virtual drawing methods. You must provide
		         those. draw() will be called by the zListViewer class
		         whenever it needs to display the item. select() will be
		         called whenever the selection bar moves over the item, and
		         whenever the item loses the selection focus. This is
		         implemented so that you can have partial redraws, where you
		         paint parts of the item without a whole redraw. Note that
		         it is your responsibility to draw at the correct location
		         on the screen. Before calling the routines, the viewer
		         will set the cursor to the origin point. This argument is
		         provided for the case when you need to draw multiline
		         items or do some advanced drawing. The 'maxlen' parameter
		         specifies the width of the area. You must make sure that
		         the whole area is filled. The 'off' parameter specifies
		         whether the item is to be highlighted (False) or not (True).

