SpicyKeys 1.00
--------------

This is the first version of my hotkeys utility, SpicyKeys.
It lets you launch any application or display any directory by 
pressing a hotkey.

SpicyKeys requires BeOS R4 or higher.

SpiceKeys consists of two executables: 

SpicyKeyCatcher - an input_server add-on that watches for "hot"
                  keystrokes, and takes action when it sees them.

SpicyKeys - a preferences applet that lets you configure which
            key-combinations trigger which actions.           


Installation
------------

To install SpicyKeys, just execute InstallSpicyKeys.sh from a Terminal
window.  After executing this script, the SpicyKeys preferences panel
will appear in your Preferences directory.  

Usage
-----

The SpicyKeys preferences panel is arranged as a table with six
columns.  Each row in the table corresponds to one hot key.  You
can add or remove rows from the table by clicking on the 
"Add New SpicyKey" or "Remove Selected SpicyKey" buttons at the
bottom of the table.  Once you have added some rows to the table,
you can select a row by clicking on it.  Once the row is selected,
you can modify the selected cell by clicking on it again, or by
typing.  The arrow keys are also usable to navigate around the
table.

The table's columns look like this on a PC:

Shift   Control   Alt   Windows         Key      Application          

Or, on a Mac, they look like this:

Shift   Control   Command   Option      Key      Application

The first four columns correspond to the meta-keys on your
keyboard.  Entries in these columns specify rules about what
the state of that meta-key must be in order to activate
the hotkey combination.  For example, if your hotkey's entry
in the "Control" column specifies "Left", then the Left Control
key must be held down when the key is pressed in order for
the associated application to be launched.  You can cycle through
the various rules for a meta-key by clicking on the cell repeatedly,
or by pressing one of the following keys while the cell is selected:

  'L'  - Sets the cell to "Left", meaning left key only
  'R'  - Sets the cell to "Right", meaning right key only
  'E'  - Sets the cell to "Either", meaning at least one of
         the two keys must be held down.
  'B'  - Sets the cell to "Both", meaning both keys must be
         held down.
  space - Cycles through to the next setting.
  enter - Cycles back to the previous setting.
  backspace - Clears the cell.

The next column, 'Key', lets you choose which key must be
pressed to activate the hotkey application.  To set this
cell, simple highlight it with the mouse, and then press
the key that you prefer.  The cell should now reflect your choice.

The last column, 'Application', lets you specify what will happen
when the hotkey combination is pressed.  Highlighting this column
will cause a text cursor to appear, and you can type the command
or application that you want to be executed into the cell.  Remember
that all commands must have fully qualified path names!  If the 
string you type in is a valid file, an appropriate icon will appear
next to the path text.

An easier way to set the application string is to just drag the
application's icon into the SpicyKeys window.  This will cause
a new row to be created, with that application already set in the
Application column.

Once you have your settings the way you like them, click on the
"Save & Apply" button to save them.  They should take effect
immediately after this.


Menus
-----

SpicyKey's only has one menu right now, the File menu.  It contains
the following items:

Open KeySet...

   Brings up a file requrester to allow you to replace the currently 
   loaded set of hotkeys with one from a saved file.  The file you
   choose should be one that was previously saved by this program.

Append KeySet...

   Same as "Open Keyset", but adds the new hotkeys to the end of
   the current list, rather than replacing the current list.

Save a Copy of Keyset As...
  
   Brings up a file requester to allow you to save the current set 
   of hotkeys to a specified location.  Note that the "active"
   keyset is always /boot/home/config/settings/spicykeys_settings,
   so this option is only useful if you want to keep multiple keysets
   around and switch between them.

About SpicyKeys

   Brings up an "About" Requester.

Quit

   Closes the SpicyKeys preferences panel.  Hotkey presses will continue
   to be processed, however.


SpicyKeyCatcher
---------------

SpicyKeyCatcher is an input_server add-on that watches the input
stream and launches applications when it detects a match with one
of the specified hotkey combinations.  Once installed, it is active
continuously.  It has no direct user interface, but it can be controlled
interactively.  SpicyKeyCatcher uses the BeOS node monitor to "watch"
the file /boot/home/config/settings/spicykeys_settings.  Any time this
file is modified, SpicyKeyCatcher will re-load it and use the new
settings.  This means you can programatically modify your hotkey settings
by copying different settings files to this location, if you want to.


Known Problems
--------------

- The prefs panel doesn't display the proper key labels for
  non-American key layouts.  That is, it's all hard-coded for now.
  Shame on me!
- The GUI isn't as easy to use as it could be.  In particular, it
  would be nice to just press the hotkey combination and have the
  columns' settings all set appropriately.
- Some key combinations don't work--on my PC, the right-control
  and right-windows keys don't seem to be mapped correctly.
  I think this is a bug in the keymap, which Be will have to fix.
- The documentation is a plain-text README file, instead of nice HTML.


Future Features
---------------

- Allow other actions to be tied to hot keys, such as closing the current
  window, moving it around, sending a BMessage, etc.

- "Syntax highlighting" to gently notify you when your settings may
  have problems (such as when you've got two hotkey actions tied to the
  same key).

- Fix all the Known Problems.  :)


Acknowledgements
----------------

Most of the GUI for SpicyKeys is based on Brian Tietz's 
ColumnListView classes, from his Santa's Gift Bag package.
Brian Tietz can be reached at btietz@biomail.ucsd.edu.  Thanks, Brian!


Lawyer Stuff
------------

SpicyKeys is FreeWare.  Do whatever you want with it, although
if you redistribute it, please keep the archive intact.  If you
want the source code, email me and I'll send it to you.


Author
------

SpicyKeys is written by Jeremy Friesner.  You can reach me at one
of the following addresses:

   jfriesne@ucsd.edu
   jaf@chem.ucsd.edu
   jaf@praja.com
