Keys
Copyright  1993-95 Apple Computer, Inc. All rights reserved.
Maurice Sharp and Christopher Bell.

**      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 shows how to do a keyboard.

A keyboard really has 2 parts. One is a view to put the keys in, the other is
the keys themselves. The container view is usually a protoKeyboard. The keys
are defined using a protoKeyPad.


protoKeyboard
-------------

1. protoKeyboard is invisible by default.

That is what the text button is for. It will send the protoKeyboard a Toggle
message so that it will show up.

2. protoKeyboard has a saveBounds slot that will default to the viewBounds
   slot. This is done from the afterScript in the protoKeyboard.
   
3. protoKeyboard includes behavior for dragging the keyboard around and for
   moving itself off of the current key view (see Chap 16).

4. protoKeyboard does not include a closeBox, you need to include one if
   you want the Keyboard to go away.
   

protoKeyPad
-----------

This is the proto you use to construct the actual keys. In general, you will
draw this proto out in a protoKeyboard, but this is not required.

The important part of this proto is the keyDefinitions slot. This defines
what the keys look like (the keyLegend, i.e., what are the key caps), and what
gets typed when a key is pressed (keyResult). The manual documents the possible 
values (5-8..11).

The keyArrayIndex slot permits particular keys to display and print different 
values depending on an integer slot in this proto. For instance, to permit
two different values for a key, you can supply two-element arrays for both 
the keyLegend and keyResult. The keyboard will use the first element in the
array if keyArrayIndex is 1, or the second element if keyArrayIndex is 2. We
use a method defined as a slot in our keyPad view to actually do the toggling.
The SetValue call in :toggleCharacter() refreshes the view to reflect the
change, as well as change the value of the keyArrayIndex slot.

We call the :toggleCharacter method when the $b key is pressed.  This is done
in the keyPressScript.  Earlier versions of the sample called :toggleCharacter
in the keyResult function in the definition of the $b key.  This function is
called when the keypad is refreshed in addition to when a key is pressed, so
it is not suitable for using to call the toggle method.  In NewtonOS 2.0, a
feature has been added that allows both the keyPressScript to be called and
the normal keyboard handling to happen.  This feature is enabled by setting
a slot in the keypad called 'newt_feature to non-NIL. 

Other Bits to Look At
---------------------

The button is used to toggle the keyboard state (open or closed). It also sets
the current key view to the paraView if the keyboard is about to be opened.
