/*
**      Newton Developer Technical Support Sample Code
**
**      slimPicker, A slimmer listPicker
**
**      by Jeremy Wyld, Newton Toolbox Engineering
**		   Maurice Sharp, Newton Developer Technical Support
**
**      Copyright © 1996 by Apple Computer, Inc.  All rights reserved.
**
**      You may incorporate this sample code into your applications without
**      restriction.  This sample code has been provided "AS IS" and the
**      responsibility for its operation is 100% yours.  You are not
**      permitted to modify and redistribute the source as "DTS Sample Code."
**      If you are going to re-distribute the source, we require that you
**      make it clear in the source that the code was descended from
**      Apple-provided sample code, but that you've made changes.
*/

This sample presents a simplified listPicker implemented from the ground up. It
does not have as many features as protoListPicker, but does perform faster and
takes less heap space. It is also easy to customize.

Two example uses of slimPicker are provided. One implements a slimPicker based
FaxPicker, the other implements peoplePicker.

For more information see the slimPicker article in Newton Technology Journal
Volume II, Number 4.


Documentation
-------------

Slots
-----

cursor

	This slot is required.

	The iterator for the data displayed by the slimPicker. Can be either a soup
	cursor or a developer defined object that implements the methods required
	by the cursor slot of protoOverview. See the Newton Programmers Guide or
	Newton 	Developer Technical Support Q&A for more information on the
	protoOverview cursor structure.


folderTabTitle

	The text to put into the protoFolderTab. This is used to identify the
	slimPicker that is open. The default is NIL (i.e., no title).

	You can use SetValue to change the value at runtime.


reviewSelections

	If true, the slimPicker will only display the selected items. If NIL, all
	items will be displayed. Corresponds to the "Selected Only" checkbox in the
	user interface of the slimPicker. The default is NIL.

	You can use SetValue to change the value at runtime.


viewLineSpacing

	An integer representing the height of each line of data in the slimPicker.
	This value must be at least the height of the checkbox. The default is 14.


visibleChildrenFlags

	Bit flags identifying which child views are to be visible.  The values are:

	Constant		Value		Shows/Hides
	vNewButton		(1 << 0)	New button for adding new data items
	vScrollers		(1 << 1)	Scrollers for scrolling the list
	vAZTabs			(1 << 2)	AZTabs for alphabetical navigation
	vFolderTab		(1 << 3)	Folder tab for filing
	vSelectionOnly	(1 << 4)	Selection Only checkbox
	vCloseBox		(1 << 5)	Close box for closing the slimPicker
	vCounter		(1 << 6)	Count of selected items

	The default is all views visible.


Methods
-------

slimPicker:Abstract(entry, bounds)

	This method is required.

	Returns the shape that represents the given entry in the slimPicker. The
	shape must not be larger than bounds. This is where the developer renders 
	an individual line of data. The returned shape must be one that DrawShape 
	can use.


slimPicker:AlphaCharacter(entry)

	This method is required if the AZTabs are visible.

	Returns a character representing the index value for the given entry. The
	character will be used to set the appropriate tab in the AZTabs.


slimPicker:CreateNewItem()

	This method is required if the New button is visible. The method is called
	with the user taps the "New" button. The developer is responsible for any
	work that needs to be done to add the new entry. This includes creating and
	opening any editing or data entry slip, adding the data to the cursor,
	selecting the new item, and refreshing the slimPicker (see RefreshPicker
	below).


slimPicker:GetHiliteShape(xcoord, bounds)

	This method is called to get the hilite box for a list item. The developer
	should provide this method if they wish to create a multiple column picker.

	This method should return something suitable for DrawShape. xcoord is the
	current x coordinate of the pen normalized to bounds. bounds is the 
	bounding box for the item being hilited.


slimPicker:GetNumSelected()

	This method is required if the counter is visible or UpdateSelectedText is
	called.

	Returns the number of selected items.


slimPicker:HitListItem(index, xcoord, ycoord)

	Called if a user has tapped on one of the items in the list. This method is
	called after the user has lifted the pen, not during the tracking of the
	hilite. It is only called if the tap occurred in the developer portion of 
	the line. It is not called if the tap occurred in the checkbox.

	The index is 0 based from the top of the displayed items. Note that
	cursor:Entry() corresponds to index 0. You can find the hit item by using
	cursor:Move(index).

	xcoord and ycoord are the pen coordinates of the pen just before it was
	lifted. If you are displaying multiple columns, you can use these values to
	determine which column was hit. These coordinates are normalized to the
	picker list. Note, the context of this call is the picklist embedded in the
	slimPicker proto.

	The default method does nothing.


slimPicker:IsSelected(entry)

	This method is required

	Return true if the given entry is selected, NIL if it is not. Note that
	tracking the selected items is up to the developer. slimPicker provides no
	mechanism to do this.


slimPicker:PickLetterScript(letter)

	This method is required if the AZTabs are displayed.

	Called by the AZTabs in the slimPicker when the user selects a given tab.
	Letter is a string containing a single character indicating which letter 
	was tapped in the AZTabs.

	This method should move the cursor to the appropriate entry and call
	RefreshPicker to update the displayed data.


slimPicker:RefreshPicker()

	This method forces an update of the items in the slimPicker. This includes
	the picker itself, the AZTabs, and the arrows.

	The data items will be redisplayed from the current cursor entry.


slimPicker:SelectItem(index)

	This method is required.

	The user has clicked on the checkbox of the index'th data item. The 
	developer should update their list of selected items accordingly. Note that 
	the implementation details of keeping track of the selected items is up to 
	the developer.

	See HitItem above for a discussion of how to find the index'th data item.


slimPicker:ToggleShowSelections(isOn)

	This method is required if the Selections Only checkbox is shown. Called 
	when the user taps on the "Selections Only" checkbox. isOn is true if the 
	checkbox is checked, NIL if it is clear.

	The developer should update the cursor to show either only selected items
	(isOn is true), or all items (isOn is nil). slimPicker will refresh based 
	on this new cursor.


slimPicker:UpdateSelectedText()

	Force the slimPicker to update the text that displays the number of 
	selected items. Call this if you programatically change the selected items 
	without user intervention.

