/*
**      Newton Developer Technical Support Sample Code
**
**      newtLabelPicker, a label picker for newtApps
**
**      by Maurice Sharp, Newton Developer Technical Support
**
**      Copyright © 1995 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 provides a user proto for a label picker that can be
used as a newtApp slot view. It also shows you the minimal slots
required to turn any proto into a slot view.

For more information about NewtApp Applications, check the chapter 
"NewtApp Applications" chapter of the Newton Programmer's Guide.  The
first section, "About the NewtApp Framework" gives a good overview.

The key code is all in the newtLabelPicker proto. All the rest is
newtApp scaffolding that shows the proto in use.

Creating a Slot View
--------------------

To create a more general slot view, you need to define the following
slots and methods:

// defaultValue slot - the default value for a data entry.
defaultValue := <some-default-value> ;


// inReTarget slot - used by ReTarget to prevent continual updating
inReTarget := nil ;


// jamSlot slot - used by the jamFromEntry method
jamSlot := nil ; // just an example, though highly likely


// path slot - used to find the correct slot in a data entry
path := 'wiggyFactor ; // just an example


// jamFromEntry method - used in conjunction with the smart input lines
jamFromEntry := func( otherEntry )
	begin
		if jamSlot then
			begin
				target.(path) := nil;
				if otherEntry then
					target.(path) := otherEntry.(jamSlot);
			end;
	end;


// ReTarget method - updates the slot view based on the
// data in the entry or some default value (see TargetData)
ReTarget := func()
	begin
		inReTarget := true;

		// SOME CALL THAT UPDATES THE DISPLAY
		// e.g. for a label picker
		// self:UpdateText(self:TargetData());
		// e.g. for a text based view
		// SetValue(self, 'text, self:TargetData()) ;

		inReTarget := nil;
	end


// TargetData method - returns either the value from
// your data entry or some defaultValue.

TargetData := func()
	begin
		// NOTE, this should return data appropriate to
		// the type of proto.
		if target AND path AND target.(path) then
			Clone(target.(path))
		else
			defaultValue;
	end


// textChanged method - updates the slot in the data entry
textChanged := func()
	begin
		if NOT inReTarget then
			begin
				// SOMETHING that sets the value of the
				// entry to the data in the proto
				// e.g. for a label picker:
				// target.(path) := Clone(self.entryLine.text);
				// e.g. for a checkbox or radiobutton
				// target.(path) := viewValue ;
				:StartFlush();
			end;
	end


// viewSetupDoneScript method - sets up the initial value for the slot view
viewSetupDoneScript := func()
begin
	inherited:?viewSetupDoneScript();
	self:Retarget();
end


Other Slots and Methods
-----------------------

The rest of the required slots and methods are as per whatever the basic type of
proto you are using.


newtLabelPicker Interface
-------------------------

The newtLabelPicker includes all the slots and methods of a protoLabelPicker
plus some new ones:

defaultValue
	default value if non specified in the current target
	
nilValueText
	text to show if target.(path) is NIL
	
path
	required
	path expression in the target for the data displayed in the picker.
	
showNILValue
	boolean value. Controls if the picker will be modified to allow the NIL
	value to be chosen. If this is true, the picker will be constructed
	by adding a seperator and the nilValueText to the labelCommands
	array.

Note that newtLabelPicker uses several of the labelPicker slots and methods
to implement its functionality:

pickerSetup
	used to add the nilValueText if showNILValue is true
	
textChanged
	used to update the displayed value, must check for inReTarget to avoid
	infinite loop of updating
	
viewSetupDoneScript
	see previous section.