W i t t y K e y s
=================
Version 1.00e - 21.12.97, by Thorsten Lange, Hamburg, Germany
copyright 1997 Thorsten Lange and his licensors.
All rights reserved.

Preface
-------
Just a note before we get startet: This program is shareware and must be
registered for only US$15 if used after a trial period. Although the
functions of this version are not limited in any way, registered users have
a couple of advantages (for details see the chapters "Shareware" and
"Registration"; there you'll also find details about a special bundle
offer!).

Please note: WittyKeys requieres Newton OS2.1 (MP2x00, eMate) or higher! I
really would like to support previous OS versions too, but for keyboard
commands OS2.1 is absolutely necessary. Sorry. 

Any suggestions or error reports are welcome (even from unregistered
users). My postal and email address can be found in the chapter
"Registration". Since English is not my native language I apologize for
possible "non-idiomatic expressions" and errors. So any corrections in this
respect are welcome, too.

I hope you will enjoy this program - so much that you gladly register your
copy :-)

BTW: Please visit my homepage at "http://www.antopia.com/thorsten" for new
versions of WittyKeys and for other Newton stuff that I have written (i.e.
"i++", "AddressAccess").


Functional description
----------------------
WittyKeys gives you a significantly enhanced control over your Newton from
your keyboard. 

With WittyKeys you can define your own key commands (sometimes called
"keyboard equivalent" or "shortcut"). You like to open "Dates" with with
"Command+D"? Just define it in WittyKeys. Or switch between running
applications with "Command+Tab"? No problem. There are lots of possible
actions you can assign to any shortcut you like (unless the sequence is
already defined): rotate the screen, turn the Newton off, open a pop-up
with all packages in a folder of Extras, ... 

Note: WittyKeys is compatible with SPI add-ons. This is an interface to
allow developers (including me ;-) to extend i++, WittyKeys or Backyard. If
you like to develop SPI additions you'll find the documentation at my
homepage http://www.antopia.com/thorsten. It is really easy to use when you
are a little familiar with deveoping for the Newton.


Installation
------------
WittyKey.pkg
To install WittyKeys just transfer "WittyKey.pkg" to your Newton with OS2.1
or better. Afterwards you can define your own individual key commands in
the WittyKeys Main Menu - just open WittyKeys in Extras (more about this in
the chapter "Defining Key Commands").

TL_Lib01.pkg
WittyKeys itselfs allows you to open applications using the keyboard. To
obtain the full benefit of WittyKeys please install "TL_Lib01.pkg" as well
(01 is the version number and might vary, so in the following I will call
it "TL_Libxx.pkg" or just "TL Lib"). This package will add plenty of
actions to the specials section. Note that this library is the same as the
one that comes with i++ and Backyard. Therefore you have to install it only
once - this saves you quite some storage space. Just make sure that you
always use the latest version available.

Note:
WittyKeys requires an external keyboard for using it with a MessagePad
2x00. Remember to connect the keyboard before turning on your Newton!


Defining Key Commands
---------------------
Defining key commands is easy: At first open "Witty Keys" in Extras. You
will see two lists: "Programs and Books" with packages currently installed
in the extras drawer and "Specials" which offers a selection of special
purpose commands. At the right hand side there are on-screen arrows for
scrolling pagewise in these lists.

To assign a shortcut to any of these actions just tap on the item in the
list. Now a dialog box opens where you enter the shortcut on the external
keyboard.

General notes:
- A valid shortcut must contain the command key ("Apple key")
   and one character key (or Tab, Escape, Return, Backspace, even the
function keys of an eMate ...).

- Additionnaly you can use "Shift" and/or "Alt" as well.

- A shortcut must NOT contain the control key ("Cntrl").

- Your shortcut will be a global one. That means it will be available in
every application but if the currently key receiving application defines
the same shortcut yours will be temporarely unavailable.

- For letter-based commands I would recommend that you use
Command+Alt+Letter to make sure that this command isn't in use by another
application.

- You cannot redefine an existing global key command.

- The dialog to define a shortcut can be used to undefine an existing key
command . Just press on the "No Key" button.

- When defining a keyboard shortcut  the cursor must be located within the
input field of the definition dialog. This will normally be the case
(unless you move the cursor somewhere else manually).

- If you remove an application, an attached key command will not
automatically be removed. To remove commands to applications that aren't
available anymore, just press "Verify" in the status bar and all
unresolveable aliases will be removed. This also verifies special actions
added by other applications.

- You can change the size of the lists by simply dragging the seperator bar
between them.


Description of available "Specials"
-----------------------------------
NOTE: If you don't find these specials in your list you'll have most likely
not installed "TL_Libxx.pkg" (see chapter Installation").

There are two kinds of specials available: submenus and actions. 
1.) Submenus (beginning with a "diammond")
When you assign a submenu to a shortcut a popup will be displayed in the
lower left corner of the screen. Within this popup you can navigate with
the up and down keys or by entering the first letters of the item you want
to select.
  - >Specials< will opens submenu with all special actions available 

  - >Active Applications< Opens a submenu with all applications currently
    running (open). This allows you to switch between active packages
    (including the backdrop app!).
  
- The rest will list the packages located in the corresponding folder
  in Extras.

2.) Actions
  - Rotate: changes the screen orientation (please note the settings in
    preferences (see below))
  
  - Rotate 180: turns the screen upside down

  - Record: starts a new sound recording. After closing the dialog
    the recorded sound will be added to the notepad
  
  - Align Pen: Opens the standard pen alignment dialog
  
  - Sleep: turns your Newton off (like using the power switch)
 
  - Reset: reboots your Newton (like pressing "Reset" in the battery
    compartment). Newton will (optionally) ask you whether you really
    want to reset.

  - Default-Store: toggles the store on which new items will be stored.

  - Backlight Control: is a light switch.

  - Sound Toggle: Turns the sound on and off

  - System Info: tells you about the state of the batteries and memory
    (heap, internal, card) together with the OS version and time/date.
    A garbage collection will be performed automatically to free up as
    much heap as possible.
  
  - New meeting: opens the dates application and a slip for entering
    a new meeting
  - Keyboard: opens the typewriter keyboard (there are specials for
    other built-in keyboards as well)
  
  - Next App: brings the next, already open app to the front. That means
    the one that is currently the frontmost app will move to the back
    making the second one the new at the top. There are two variations:
    "excl. Backdrop" means that the backdrop app will stay the backdrop and
    "incl. Backdrop" means that the backdrop app will be treated just like
    any other open application.

  - Prev App: is similar to "Next App" but moves the applications in the
    opposite direction. So the app from the bottom will become the
    frontmost one.

WittyKeys is extendable using the new plug-in architure "SPI". Since
Backyard and i++ V2.x also support SPI, those specials will appear in their
list as well. The first third-party tool supporting SPI is CoolKit which
adds items usefull for developers. A description of how to support SPI will
be available at my homepage http://www.antopia.com/thorsten. I intend to
release SPI based extensions in 1998, which will be available there as
well.


Preferences
-----------
In WittyKeys there are a few options that you can set. To do so, open
"Preferences" in WittyKeys (tap "WittyKeys" in Extras, then tap "i" then
"Prefs").

> Activate "Freezing" <
"Freezing" is a hidden feature in the Newton OS2 - ROM. It allows the
deactivation of packages without removing them from your Newton. If this
feature is enabled you can freeze a selected application in Extras: Just
select a package in Extras (i.e. in overview mode by setting a checkmark
before it) and then tap the routing button. Now selected the new "Freeze"
item in the routing menu. 

After freezing a package the icon turns into a snowflake. As far as the
Newton OS is aware, the package isn't installed anymore - so it cannot be
opened (or cause conflicts). A frozen application doesn't use up any heap
memory (every installed application occupies some heap memory, so releasing
heap can make "no memory - restart" messages less frequent).

WittyKeys can open frozen applications as if they are installed: just open
it with a command sequence you have defined for it and it will be thawed
before opening (this takes a little extra time, of course). After closing
the package, it will be frozen automatically. 

> Ask before "Reset" <
If checked WittyKeys will ask you before resetting your Newton. This will
only be available if "TL_Libxx.pkg" is installed (see chapter
"Installation").
 
> Rotate Options <
Here you can select the 2 orientations between which the rotate item should
switch. This option is needed to provide the rotate command as a single,
one-tap item (and I believe most people will use their Newton in only one
landscape and one portrait mode). This will only be available if
"TL_Libxx.pkg" is installed (see chapter "Installation").

There might be additional preferences added by some SPI add-ons.


Known Errors/Limitations
------------------------
-If you reinstall a package (i.e. an updated version) for which a command
key is defined this package will show up in the application list as if
having no key command attached. But the command is still available and when
you execute it this broken link will be fixed automatically.

- Currently the "active Apps" option only recognizes real applications and
not floating dialogs like "Assist", "Find" or the calculator. 

- Currently you can only define up to 29 key commands ... but I hope this
will be suffient for most users.


Version history
---------------
V1.00 / TL Lib V1
initial release


Shareware
---------
This program is shareware. You may try it for free for about four weeks.
After this trial period you have to pay a (little) fee for using it on a
regular basis.

Since you should be able to really try this program there are no functional
limitations when using an unregistered copy!

However, some people need a "motivation" to register their copy which is
very easy  and cheap - see chapter "Registration" for details. So
registered users have the following advantages:

1.) Email support for questions/problems

2.) For the present I will maintain an email list of registered users to
notify them when a new version is available at my homepage
http://www.antopia.com/thorsten.

3.) When using this program a reminder will be displayed that you have to
register your copy. The more you use this program the more often the
notifications are displayed. After entering the registration code no more
messages are displayed.

And everybody benefits because I will continue improving the program.


Registration
------------
Registration costs US$15 and is a license for one person.

Note that there are two special bundle offers:
 - For US$25 you can register WittyKeys along with Backyard and i++
   (saving US$20).

 - If you registered one of these packages (i++, Backyard or WittyKeys)
   and register another one later you will receive the third code for
   free (saving US$15) automatically.

Registered users receive a code that depends on the name as written in the
owner info. To enter the code just press the "Code"-button in the "About"-
box and fill in the code at the lower left corner. Afterwards your copy is
registered and the advantages mentioned above will take effect. The code
will be valid for all future shareware-versions of WittyKeys.

If your name changes (i.e. marriage) just send me an email with the new
name and I will return the new code number. If you switch between two
different owner names (i.e. official and private) just send me both - the
program supports two codes at the same time.

There are four different ways to pay for WittyKeys:
1.) SWREG
If you are a Compuserve member (or have a friend who is) you can use 
GO SWREG, ID 16249 to register for US$15.
(or use ID 16321 for the bundle mentioned above for US$25)
Please use the exact owner name (for the registration code) in the SWREG
procedure.

2.) Sending Cash
Send US$15 (or US$25 for the bundle) as cash or the equivalent amount in
your local currency in a letter to 
Thorsten Lange
Tivoliweg 7
21079 Hamburg
GERMANY
*** please send only cash and not a cheque ***
Be sure to include your exact owner name and your email address! It's best
to wrap the money in some thick paper and send me an email note that the
money is on it's way. Sending cash has really worked without any problems,
so far!
 
3.) Web-base (Kagi)
You can pay by credit card by simply filling in a web form at
<http://order.kagi.com/?LT> or
<http://kagi.direct.net/cgi-bin/register1.cgi?LT>.
 The registration will be processed by Kagi. If you want to know more about
Kagi and the web-based registration please visit their homepage
<http://www.kagi.com/> where all common question will be answered in a
really great FAQ.

You will receive a confirmation email by Kagi at the same time I will be
notified of your registration. After receiving the notification I will send
you the registration code.

Only contact Kagi if you have a question about the payment. Don't bother
them about my utilities or a non-working code. Kagi only collects the fees
but does not know anything about my packages. 
 
4.) Newton Register / Kagi (credit cards, US cheques, ...)
You can pay by credit card, US cheques, ...  using "Newton Register":
- Install "Newton Register" on your Newton. The latest version can be found
  at ftp://ftp.rahul.net/pub/flasheridn/Register.sit.hqx
- Open "Register" on your Newton and select "WittyKeys:TAL!" as the program
- Select the kind of payment and fill out the apropriate fields
- Select "Mail" from the envelope button
- Double-check the form generated by the program then press "Mail". If you
can't send email from your Newton you will have to retype the mail into
your host's email program. Tap the "Show Text" button in the email slip. It
isn't very long. Retype the data exactly as it appears in the email
message. Then send the email message to shareware@kagi.com

NOTEs about using Newton Register / Kagi:
- If you want to send a cheque or cash select "Query", mail that form and
wait until you receive a registration number. Please don't send cash or
cheques until you have received a registration number!!!

- Only contact Kagi if you have a question about the payment. Don't bother
them about WittyKeys or a non-working code. Kagi only collects the fees but
does not know anything about WittyKeys. My (the author's) email address can
be found below.

- If you have comments about "Newton Register" please contact the author:
FlaSheridn@kagi.com.

- "Newton Register" encodes your credit card data when sending it as email
to discourage casual sniffers, but it is not as secure as PGP. The package
only sets up a mail message. The responsibility for actually executing it
is yours!


For further informations please contact
Thorsten_Lange@kagi.com (or 101353.2024@compuserve.com)   


More Newton Stuff from Thorsten Lange
-------------------------------------
Check out my Homepage http://www.antopia.com/thorsten for the actual list
of my applications together with more information about them
(screenshots,...)


Copyright notice
----------------
WittyKeys is copyright 1997 Thorsten Lange and his licensors.
All rights reserved.

This program is shareware - IT IS NOT FOR FREE.

You are allowed to try out WittyKeys for four weeks for free. If you
continue using it you have to register your copy. For more information see
chapter "registration" above.

Please support development of cheap and reliable software for the Newton
and pay for shareware you use regularly!


Restrictions
------------
You may not decompile, reverse engineer, disassemble or otherwise reduce
the software to a human-perceivable form. You may not modify the software
or the documentation.


Disclaimer
----------
You expressly acknowledge and agree that use of WittyKeys is at your sole
risk. The software and related documentation are provided "AS IS" and
without warranty of any kind.

I make no warranty of the performance of this program, expressed or
implied. In no event will I be held responsible for any damages or loss as
a result of using WittyKeys. When this disclaimer does not apply, my
liability will be limited to the amount paid for the product.


Famous last words ...
---------------------
Newton, MessagePad and eMate are trademarks of Apple Computer, Inc.,
registered in the United States and other countries. 
