+ 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.