💾 Archived View for mirrors.apple2.org.za › archive › ground.icaen.uiowa.edu › upl1997 › Aug97 › FKe… captured on 2024-08-19 at 02:40:32.

View Raw

More Information

⬅️ Previous capture (2023-01-29)

-=-=-=-=-=-=-

+                    Documentation for FKey v0.1b

+ Distribution:

This product is classified "Jesus-A-ware". It is the equivalent of FreeWare.
It is distributed the same as God's Love.  That means it's free to anyone
who'll accept it.  It will be given to anyone, regardless of who or what
you are, or have been. It's not where you've been, but where you're going!

Everyone is free to use the "JesusAware" name.  Spreading the Gospel message
through Software.  This product is free.  Give it to everyone, even if
they don't have a computer!  This work is a labor of love for my Lord and
Savior Jesus Christ!

America Online:   DAVE L32 
GEnie:            D.LEFFLER
Snail Mail:       Dave Leffler 
		14 I Cape Drive
		Fort Walton Beach, FL 32548


+ What it does:

Here is a Control Panel NDA Device (CDev) that adds function keys to the IIGS.
FKeys are similar to NDA's, CDA's, or CDev's.  They are mini programs stored
on disk and loaded when you boot your computer.  These programs are called up
inside of other programs at the press of a key sequence, something like a
macro.  Several utilities already use this method.  FKey is written as a
standard environment to prevent conflicts between these types of programs,
reduce memory and disk space requirements, and improve the overall efficiency
of the IIGS with many utilities installed.  FKey takes advantage of a IIGS
with an extended keyboard.

Included with the FKey CDev are several FKey files that: Blank the Screen,
Save the Screen, Change the TransWarp GS speed, Zoom a Window or Send it to
the back, Change the Key Translation, and Eject Disks.  Each of these FKeys
can be called up with a simple keystroke sequence to immediatly give you the
results you desire, when that option seemed to be left out of the program
you're running.

The CDev manages the FKey environment by allowing you to change the keystroke
sequence assigned to the FKey (both on disk and in memory), make the FKey
file Inactive, Configure the FKey (if required), and choose the location that
the FKey files are kept if you don't have enough room on your boot disk.
The FKey application will create a list of all FKeys in memory and save it
as a text file or print it.


+ How to Install FKey:

Copy the file "FKey.CDev" to the "CDEVS" folder found in the "SYSTEM" folder
of your boot disk.  Next copy the "FKeys" folder with the FKey files into
the "SYSTEM" folder (it will be there with the Desk.Accs, System.Setup, and
CDevs folders).  FKey is initially configured to look for the FKey files in
this location.  If you don't have enough room, please read further to learn
how to change this setting.  You MUST do this with the Finder or another
GS/OS compatible utility program or it will not copy correctly.  There are
extended files.  You should also copy the "FKey.Icons" and "FKey.FType" files
to the "Icons" folder in the main directory of your boot volume, or any
volume online.  These files are not required, but make it easier to find
FKey files.  The NEXT time you open the Control Panel NDA, you'll see the
"FKey Manager" button icon.  You do not have to reboot your computer to
start configuring FKey files!  You WILL have to reboot it to get the effects
of FKey though.  The CDev installs a routine to patch GS/OS at boot time.
Did you think it was magic?  I've also included a Permanent Initialization
file version of FKey.  YOU DO NOT NEED AND SHOULDN'T EVEN INSTALL THE INIT
FILE UNLESS YOU READ THE TECHNICAL INFORMATION BELOW.

FKey files are only loaded when you boot you computer, so you must reboot
your computer after installing FKey to get the effects.  If you have the
graphics enabled while booting you computer, you'll notice the FKey icon
remains on screen for a while.  Don't be alarmed, it is loading the FKey
files at this time.  Now that you've rebooted the computer, you're ready
to use FKey.


+ How to Use it:

Once FKey is installed you may call up an FKey at any time from within a IIGS
desktop program (with menu bar and graphics screen).  This includes from
within a CDA that was called up from within a desktop program. Simply press
the function's assigned key sequence and the action will take place.  Please
see the accompanying note for details as to what each included FKey file does
and it's default key sequence.  For example, pressing "Option Open-Apple B"
should send the topmost open window to the back of the other windows
(providing there was more than one window open).  It's as easy as pressing
the assigned key sequence to run that FKey function.  If you choose to change
the assigned key sequence, please see the configuration information below.

If you wish to disable FKeys, press the key sequence for disabling FKeys.
Once you've done this, the only FKey keystroke sequence that FKey will
recognize is the one to enable it.


+ How to Configure FKey Functions:

This is where the Control Panel NDA comes in.  Bring it up and select the
'FKey Manager' Icon.  You'll initially be set to configure the Internal
functions of FKey, so you see the name "Internal" after the FKey File:
button.  You cannot make the internal function "Inactive", so that check
box is dimmed.  In the list you should find two functions, one to disable
FKey and one to disable the 'click' on keypresses.  Select one of these to
work with that function.  Below the list is a message that tells you if
the function was loaded at boot time or if FKey Manager was unable to find
it in memory (which may mean that it wasn't loaded at boot time).  Below
that is the keypress required to activate this function.  Below that is
a set of check boxes that will be checked if that modifier key is used
with the keypress.  Modifier (keys) do not generate a keypress by them-
selves, but are used in conjunction with the other keys.  Below that is
a button to set the location that you are keeping your FKey files at.
The other button is used when an FKey may need configuring.  That button
may be dimmed, which means that particular FKey requires no configuration.

To change the keypress required for that FKey, simply press the desired
key sequence.  You will see the visual representation of what keys were
pressed.  As soon as you enter the keypress, that function is updated on
disk and also in memory if the function was found.  THERE ARE NO KEY
EQUIVALENTS FOR ANY OF THE CONTROLS IN FKEY MANAGER CDEV.  ALSO, KEY
TRANSLATION IS TURNED OFF WITHIN FKEY MANAGER.

Keep in mind that the special labeled keys are in fact built-in control
key sequences, i.e., Return is Control-M, Tab is Control-I, etc...  See
the table below.  So, Control-M and Control-Return are the same and will
be displayed as Control-Return.  You may click in the Option and Command
check boxes to select or deselect those modifiers.  The Option is the
same as the Solid Apple and the Command Key is the Open Apple key.  You
may not toggle the other modifier check boxes.  This is because the logic
required to update the keystroke sequence would make the program much
larger (and probably wrong).  Please use some common sense when selecting
a keystroke sequence.  For example, if you set a function to activate
whenever 'Return' is pressed, you'll never be able to use the Return key
to end a line.  It is suggested that you use one or more of the modifiers
in a key sequence.  When you enter the FKey Manager CDev, FKeys are disabled.
BUT, YOU MUST NEVER PRESS THE CURRENTLY ASSIGNED KEYPRESS FOR THE FKEY
DISABLE FUNCTION, OR YOU WILL ENABLE FKEYs!  If you will be using the
FKey disable keypress, enter it without the Command or Option key being
pressed, then click in that check box.

To change one of the FKey files, click in the 'FKey File:' button.  You'll
initially be taken to the location that your FKeys are located, but you
may move to other folders/devices.  When you select a file, its functions
will be placed in the list and its Active/InActive status will be displayed
in that check box.  You may change those keystroke sequences as above.  In
addition, you may make this FKey 'Inactive' to prevent its being loaded the
next time you boot your IIGS.  Likewise, you may also make an Inactive FKey
Active so it will be loaded during the next boot.  If any configuration can
be done to this FKey file, the Configure button will not be dimmed.  Click
in the Configure button to perform some FKey file specific configuration.
Most FKeys will not require configuration, hence it will not be available.

If you would like to change the location where you will be keeping FKey
files used when booting the IIGS, click in the 'Location' button.  Then
just select an FKey file in the directory where they are located.  This
would primarily be of interest to people without a hard drive that may
have to keep FKey files on a second disk.  If you are just installing
FKey and you know you won't have enough room on your boot disk, you can
go ahead and change the location before you reboot the first time.  Once
a CDev file is dragged into the CDev folder, it can be called up by the
Control Panel NDA immediately.


+ Making a List of Loaded FKeys

If you would like a list of all the loaded FKey functions and their assigned
keystrokes, you must use the FKey Application.  This feature was not added
to FKey Manager CDev, because it would make that file twice as large.  The
two main commands are self-explanitory.  'Make List' will create a text file
of all the FKeys in memory and their keystrokes, and then display that list.
To get a good display, you must have COURIER.10 in you Fonts folder.  'Print
List' will send the list to your printer instead of creating a disk file.  You
may look at a list (or any text file) with the 'Open List' command.

The list may be helpful in deconflicting FKeys and applications.  FKeys are
loaded in the order they appear in the FKey directory.  FKey functions get
keystrokes on a first come, first serve basis.  If two functions have the
same keystroke sequence, the one closest to the top of the list will be
the one executed.


+ Errors

Some programs may patch the vector that FKey Manager looks at to find FKey.
If you bring up FKey Manager CDev and get a message saying that it couldn't
find FKey in memory, you will only be modifying FKey keystrokes in the FKey
files, NOT in memory.

The same error can occur in the FKey Application.  Although it is doubtful
that it will, this error will effectively render the application useless.
It can't make a list of loaded FKeys if it can't find them!  The application
will automatically quit.

Any other errors will either be GS/OS or toolbox errors and should not
occur under normal circumstances.  They could occur when a disk is locked
or full (?) or damaged.  Any non-disk errors may be cryptic to you, but
will be of interest to me.  Please send me the error number, what you
were doing, what application you were in, and your equipment setup.  This
will be instrumental in squashing any bugs.


+ Technical Information

The following is a list of Control key equivalents.

    Esc        - Control [
    Tab        - Control I
    Return     - Control M
    LeftArrow  - Control H
    RightArrow - Control U
    DownArrow  - Control K
    UpArrow    - Control J
    Clear      - Control Keypad X
    Enter      - Control Keypad M

The default (from the factory) internal functions are:

    Enable/Disable FKey      - Option Command Control Q
      This function practically disconnects FKey.  It will disable all FKey
      functions EXCEPT itself.  It is a toggle.

    Clicker On/Off           - Option Command s
      This function turns off the clicking you hear when you press a key under
      FKey.  It is a toggle.  The click should tell you FKey has been
      installed.

FKey files use the filetype of $F3 (User Type #3), and an auxilliary filetype
of $8000 will make that file inactive.  For more information of the structure
of FKeys, see the source code files in another download.

When the CDev is booted (you see the icon on the boot screen), an
initialization program is permanently loaded that patches the vector used
when keys are pressed and also installs a heartbeat routine to ensure it
remains patched.  It also loads and initializes the FKey files.  This program
is the guts of FKey.  The largest part of the CDev is the configuration
program.  At 15K, I don't consider it large.  It is possible to use the FKey
Initialization file, that would only be about 2.5K.

IF AND ONLY IF YOU ARE FAMILIAR WITH THE FKEY MANAGER CDEV and would like some
more space on your boot disk, you may use the FKey Init IN PLACE OF FKey CDev.
If you have both the FKey CDev and Init active, they will fight each other and
may slow your computer down, I don't think they'll cause a crash, but...
Place the FKey.Init file in the "System.Setup" folder in the "System" folder
of your boot disk.  It will load and run your FKey functions.  You will not
be able to change the keystroke sequences except with the FKey Manager CDev.
You may change the location the Init file looks for the FKey files with
the FKey application.  AGAIN, if you use the Init file, I'm assuming you
know enough about your IIGS and the System Software to understand this
and DO NOT have the CDev active.


+ Look for the source code somewhere nearby.  It's in ORCA/C v1.3 with
  APW v1.1 Rez files.  The initialization file and it's loading routine are
  written in ORCA/M Assembler for speed.  Most of the resources were designed
  with Genesys with some help by Design Master.  The FKey files are written
  in ORCA/Pascal, ORCA/C, and ORCA/M for example purposes.

  This program contains material from the ORCA/C and ORCA/Pascal
  Run-Time Libraries, copyright 1987-1989
  by Byte Works, Inc.  Used with permission


+ Future Additions:

You've got me!  Any ideas!
The ability to load and unload FKeys?
FKey Manager capabilities in the application?


+ Revisions:

v0.1b
- Initial Beta Release.