****************************************** ** POPFUNCS V2.1 ** ** Written by Tom Krehbiel ** ** June 1988 ** ****************************************** This program in it's executable form is being released as ShareWare (user supported software). Feel free to give a copy to anyone who wants one; just make sure you: 1) give them all the files listed below, and 2) charge no money for it. If you feel that this program has been useful to you, a small donation of five or ten dollars would be GREATLY appreciated. This will encourage me to continue to upgrade this and other programs. I'm also curious just how many people this program gets to, so send me a postcard or something. Send comments/bug reports/donations to: Tom Krehbiel 10747 Surry Road Chester, VA 23831 I can also be reached through David Krehbiel (yes, we're related) on Compuserve (70701,1515). If you do find a bug (and I'm sure there's at least a few left), please describe the conditions under which the program bombed so I can better correct the problem. IN THE ARC FILE The following files should be included in the ARC file: PopFuncs The main program PopFuncs.info The icon for the main program PopFuncs.doc This document Default.fkeys Sample macro file README How to set up PopFuncs EXECUTE.ME To rename all the files properly Okay, on to more important things... FEATURES * Useable from WorkBench or CLI (though it's not as useful from WB). * Easily user-definable keyboard macros. * 'Pause' feature to temporarily disable PopFuncs. * Supports saving/loading macro files. * Window manipulations can be embedded in the macros. * User-definable 'hot keys.' * Run any program in the background at the touch of a key. * Screen blanking after a user-definable length of time. * Allows 'screen shuffling' with left-amiga-M. * Window 'latching' to recall specific windows at a keypress. NEW TO 2.1 The following things have changed since V2.0: - A problem with window enlarging was fixed. - Added {n} to simulate pressing the return key. - An UNDO gadget was added to the define window. - A CLEAR gadget was also added to the define window. - The input handler was revised considerably. - The window 'latching' feature was added. HOW TO RUN IT PopFuncs can be run from the CLI as follows: Run >Nil: PopFuncs [macro file] where 'macro file' is an optional file of macros to load in on startup. If 'macro file' cannot be found, then the file 'S:Default.fkeys' is loaded. If this file doesn't exist either, then the macro definitions will be blank on startup and you'll have to either load macro definitions or type them in yourself. This can also be put into your startup-sequence so it will run automatically on boot-up. The ">nil:" will enable you to remove the CLI that PopFuncs was started from. This isn't required, but if you put this in your startup sequence and do an 'EndCLI' at the end, then you would probably want to put the ">nil:" in the command. It can also be started from the WorkBench simply by double-clicking on its icon. Although some features are useful from WorkBench (most notably the window manipulations and background-program-running), PopFuncs is much more effective from CLI. THE DEFINITION WINDOW By pressing ALT-D while the program is running, a window will pop up (hence the name 'PopFuncs') giving you the current macro definitions. Clicking in any of the string gadgets labeled F1-S10 with the left mouse button allows you to change the text of the macros as you would with any string gadgets. The string gadget under the macro text gadgets, labeled 'Blank Time', is for setting the screen blanking time. See SCREEN BLANKING below. The three tiny string gadgets under the macro definitions, labelled 'Kill:', 'Define:', and 'Pause:',allow you to change the 'hot keys' that perform various functions. For example, if you're using Scribble!, which uses ALT-P to set a page-break, you could click in the PAUSE gadget and change the P to an S. Then, any time you hit ALT-S, PopFuncs will pause. You can use any ASCII character from space to DEL. WARNING: Make sure all three of the 'hot keys' are different. Results are unpredictable if any two are the same. I hope this isn't a problem. The UNDO gadget will restore the macros to whatever state they were in when you first popped up the window. So if you completely screw up a macro, you can hit undo and all will be saved. The CLEAR gadget clears out all of the macros, leaving a blank slate. If you accidently hit clear, don't worry -- just hit undo. The OK gadget simply removes the definition window and let's you continue normal use. Note that all of PopFuncs' features (except screen blanking) are inactive while the definition window is up. SAVE allows you to save the current macro definitions to a file of your choice. It saves the macro definitions, the blank time, the three definable 'hot keys,' and all of the window latches (see below). Sorry about the pitiful file requester, but I wanted to keep this program as small as possible. Later on I might add a better requester, but for right now, this one will do. LOAD (coincidentally) allows you to load in a macro file from disk. See MACRO FILE CONTENTS below. Note: If you're lazy and don't like to use the mouse, you can type the first letter of any of the bottom gadget names and have it perform that functions. For example, hitting 's' (lower case only) will bring up the save file requester. You can also hit RETURN for OK and ESC for UNDO. Also, the number keys activate the unshifted function key string gadgets, and the shifted number keys activate the shifted function key string gadgets. For example, hitting '4' on the keyboard activates the F4 string gadget, and shift '4' would activate the S4 string gadget. NOTE: All of the functions of PopFuncs (except the screen blanking) are disabled while the definition window is displayed. "PAUSING" Pressing ALT-P will temporarily 'pause' PopFuncs. This turns off the trapping of every key except ALT-P again. This can be used if a program you are running has its own definitions for the functions keys and you'd rather use them. While paused, PopFuncs displays a small window with the message 'PopFuncs sleeping...' to let you know it's not doing anything. To restart it, just hit ALT-P again. SCREEN BLANKING PopFuncs supports variable-time length screen blanking. This means that after a certain amount of time of inactivity that you define, the screen will be blanked to avoid video burn-in. In the definition window underneath the macro string gadgets is another (another) string gadget that defines the number of minutes that must elapse before screen-blanking. The default value is ten minutes. NOTE: Serial and parallel port activity is NOT considered activity. That is, if you're in a terminal program and just watching a bunch text scroll by, the screen WILL blank after the set time has expired. Sorry. SCREEN SHUFFLING I've changed the meaning of the Left-Amiga-M key slightly. Normally it pushes the WorkBench screen to the back. But PopFuncs takes the FRONT SCREEN and pushes it to the back. This lets you flip through any screens that are present, which you couldn't normally do. EXITTING If for some strange reason you'd like to remove PopFuncs from the machine, SHIFT-ALT-K (for kill) will do the job. It will display a message about it's death and you will have to deal with your guilt. WINDOW "LATCHING" Suppose you're running three different programs (like a spreadsheet, terminal, and database manager) and you're constantly switching between the different windows. Wouldn't it be nice if you could just hit a key and have the spreadsheet window pop to the front and activate, no matter what screen it was on? Well that's what PopFuncs' window latching allows you to do. It let's you 'latch on' to a window and then recall it at any time by hitting an appropriate key sequence. PopFuncs lets you latch onto up to 9 windows in this way. There are two ways to implement window latching: The first is by far the simpler of the two. Just activate the window you want to latch onto, then press and hold SHIFT and ALT and then press any of the numbers 1-9 ON THE NUMERIC KEYPAD. This causes PopFuncs to remember that window (actually it remembers the window's title). The second way is to put a definition line in the macro file, detailed below under MACRO FILE CONTENTS. When you want to recall the latched window, all you have to do is hit ALT and the NUMERIC KEYPAD number of the window you want to recall. All of the windows in the system are then searched to find the one you latched and it is then popped to the front and activated. If it can't find the window (if, for example, it was closed) then nothing will happen. NOTE: The way PopFuncs remembers a window is by it's title. It saves the window's title in memory, and then when you want to find it again, it searches through all the windows and all the screens and tries to match it's remembered title to titles on the windows it is searching. The point is if you latch onto a window and then the window's title is changed somehow, PopFuncs will probably not be able to find that window again. ANOTHER NOTE: If you try to latch onto a window that does not have a title, (like maybe borderless backdrop windows), then PopFuncs remembers the SCREEN title. Then when you call up that latch, it will pop the screen to the front but it will not activate any windows. THE MACROS Now for what you've all been waiting for... The macros can have anything you want in them, including some special codes described below: ('x' is any ASCII character, 'n' is a digit from 1-9, 'list' is a list of ASCII characters) ^x This let's you embed control characters in the string. EXAMPLE: ^M is a carriage return. NOTE: ^M IS DIFFERENT FROM ^m. That is, ^M is like hitting shift-control-M, and ^m is just plain control-M. ~n This is a simple time delay, where 'n' is a digit from 1-9 indicating the length of the delay in seconds. EXAMPLE: "cd df0:^M~1dir^M" will change directories to df0:, pause for a second, then do a directory. \ This overrides any of the special codes. So if you want a "^" in your macro, you'll have to do a "\^". I tried to make the command codes as obscure as possible, but if this inconveniences anyone, I apologize. NOTE: To do a "\", you'll have to do a "\\". [list]x This lets you add any qualifiers to a keystroke. So, if you want to do a CONTROL-LEFT AMIGA-RIGHT SHIFT-LEFT ALT-M, put a "[clta]m" in the macro. The qualifier codes are: c = control l = left amiga r = right amiga a = left alt b = right alt s = left shift t = right shift NOTE: "[c]M" is the same as "[cs]m". NOTE: If you wanted to have F10 pause PopFuncs, you could make F10 "[a]p" and that would be the same as hitting ALT-P. NOTE: If you wanted to bind F10 to clicking the left mouse button, you could do "[al]x". Note that you MUST have an ASCII character after the right bracket, whether it does anything or not (in this case it serves no purpose). {x} This lets you put in keystrokes that aren't ASCII characters. So, if you want to put an up arrow in your macro, do a "{u}". Codes are as follows: u = up arrow d = down arrow l = left arrow r = right arrow t = the tab key e = the escape key b = the backspace key h = the help key 0-9 = numeric keypad numbers - = numeric keypad "-" . = numeric keypad "." c = numeric keypad ENTER n = the return key x = the delete key NOTE: You can only put one character within the "{}"s. NOTE: You can also add qualifiers to these codes, so if you want a SHIFT-TAB, you could do "[s]{t}". These are the window manipulation commands. If you want to bind F10 to shrinking the active window, pushing it to the back, and activating the next window, use "<-ba>". The codes are: - = Shrink the currently active window to it's minimum size. NOTE: This only works on a window that has a sizing gadget. + = Enlarge the currently active window as far to the right and down as possible. If you want to make a window the entire screen size, first move the window to the upper left-hand corner see below), then enlarge it. NOTE: This only works on a window that has a sizing gadget. b = Push the currently active window to the back. NOTE: This only works if the window has depth gadgets. f = Bring the currently active window to the front NOTE: This only works if the window has depth gadgets. a = Activate the next window in the chain of windows. This will allow you to 'scroll' through the windows in the active screen. 7 = Move active window to upper-left hand corner. 9 = Move active window to upper-right hand corner. 1 = Move active window to lower-left hand corner. 3 = Move active window to lower-right hand corner. NOTE: The codes for the move-window functions above actually do have a meaning. If you'll notice on the numeric keypad, the 7 is on the upper left, 9 is on the upper right, 1 is on the lower left, and 3 is on the lower right. This gives a little bit of visual help when moving windows: 7 9 \ / X / \ 1 3 ' (apostrophe) Use this if you want to put a comment in your macro definition. EG, "<-baf+>' Shrink window, push to back, activate next, bring to front, enlarge". Note that this comment extends all the way to the end of the line, so don't try to put anything useful after the comment character. `command' Here's an interesting feature that my brother wanted me to include. Suppose you're typing away at you're CLI and you suddenly realize that you want to run Access! or something. Well, you can program a function key to execute any program in the background. For example, if you did a `Terminals:Access!' in one of your macros, then PopFuncs will start up the program Access! on the disk Terminals, assuming the disk Terminals is in a drive. If it isn't, you'll get the standard "Please insert volume Terminals: in any drive" requester. Note that PopFuncs prepends 'Run >nil:' onto the beginning of the command, so a program that requires a CLI window will probably not work properly. This feature would be more useful to somebody with a hard disk, but it is still a handy feature for non-HD users who love to copy gobs and gobs of disks into RAM (like me - I can't wait 'til I get a HD). NOTE: If you want a function key that simply starts a NewCLI, just program one with "`NewCLI'" and you've got you're own PopCLI. NOTE TOO: If a program that you start like this requires a CLI window, you might try this: "`NewCLI'~1ProgramName^M". This will open a NewCLI window, pause for a second, then execute the program as if you had typed it's name into that CLI window. Most programs compiled with Lattice will require a CLI window, unless you change the startup code so that it doesn't open up that (aggravating and basically useless) stdout window from WB. WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING IF YOU HAVE RUN POPFUNCS FROM THE WORKBENCH, SOME PROGRAMS MIGHT GURU THE MACHINE IF YOU TRY TO RUN THEM IN THE BACKGROUND. THIS ALSO HAPPENS IF YOU HAVE RUN POPFUNCS FROM CLI AND REMOVE THE CLI WINDOW IT WAS STARTED FROM. PROGRAMS THAT THIS HAPPENS WITH THAT I'VE FOUND SO FAR ARE: ACCESS! (SOMETIMES) AND DELUXE MUSIC. IF YOU DISCOVER ANOTHER PROGRAM THAT GURUS PLEASE LET ME KNOW! I'M TEARING MY HAIR OUT OVER THIS ONE... EXAMPLE MACROS Here's some macro examples: "cd df0:^M" Pretty self explanatory. Writes "cd df0:" and places a carriage return on the end. "[sa]k" This would be the same as hitting SHIFT-ALT-K. This would effectively remove PopFuncs. "[s]{d}" This is the equivalent of hitting SHIFT-DOWN ARROW. If you were running an editor like Memacs or DME, then this would move the cursor down a page. "" This will activate the next window, bring it to the front and expand it to full screen size. "\'Hello\'" This prints the message "'Hello'". Note that the back slashes are necessary since "'" is the symbol for a comment. "`C:PopCalc'" This runs the program C:PopCalc in the background. (If you're wondering what PopCalc is, it's another program I'm working on. It's basically a full- featured scientific calculator that you can call up at the touch of a 'hot key'. I should be releasing it soon.) "`NewCLI'~1<7+>Conquest^M~9" I dedicate this one to my brother David, the world's most avid 'Conquest' player. This starts a new CLI, pauses a second to give it time to do stuff, enlarges the CLI to full screen size, then executes the game Conquest (assuming it's in the current directory - you might have to put a path name in front of it to make it look in a specific place). After that it waits 9 seconds for the game to load in, then pushes the active window (which is that little tiny window in the lower right) to the back so it's out of the way. MACRO FILE CONTENTS The macro file format is very simple. The first line contains the screen blanking information as follows: B=n where 'n' is a decimal number indicating the number of minutes that must elapse with no activity before the screen will blank. The maximum value for this number is 65535 (yes, that's a word). The next three lines contain the 'hot key' definitions in the following format: Kill hot-key Redefine hot-key Pause hot-key Each line should only have a single ASCII character on it. The next lines contain the latch definitions. There can be any number of lines here, but remember that you can only program 9 window latches. Each latch line has the following format: LATCH n,string where 'n' is a numeric digit from 1-9, and 'string' is any string of ASCII text characters. 'n' is the numeric keypad number (along with ALT) that you press in order to bring up this latch, and 'string' is the window title that PopFuncs looks for (see WINDOW LATCHING above). Note that you don't have to put in the window's entire title, for example: LATCH 1,Left will match any of the following window titles: "Left", "LeftWing", "Lefty", "Left or Right". The next twenty lines are the macro texts, in order from F1 through S10. If you only have 12 defined, then it's okay to leave the other eight off, but if you have a blank macro between to others, you MUST leave a blank line in the macro file. SAMPLE MACRO FILE B=15 <- sets blanking interval to 15 minutes K <- binds SHIFT-ALT-K to killing PopFuncs D <- binds ALT-D to popping up the define window P <- binds ALT-P to 'pausing' PopFuncs LATCH 1,AmigaShell <- latch onto a window with a title of "AmigaShell*" LATCH 4,2 cd df0:^M cd df1:^M cd vd0:^M <- these blank lines are required if you <- want to leave a macro blank. dir^M IN THE FUTURE Here are some things I intend to put into PopFuncs in the future. If you have any suggestions, let me know. - Support for the AREXX stuff. I'm not quite sure how to work this yet, but my brother insists on me adding it in, so I'll look into it. - A better file requester. Something small in code size, but useful. - I also hope to shrink the actual code size. I was shooting for about 7K when I started this thing, but it quickly grew when I started adding additional features. The entire thing is written in Assembly, so it's not as big as it could be. (Actually, my first version was written with Lattice C, and with only half the features it was 29K. Fortunately, the disk it was on corrupted and I had to rewrite the thing in assembly. That's why this is 2.1 instead of 1.1) CONCLUSION Well, I think that about covers everything. I hope somebody out there finds a use for this program. -Tom- (This is my first REAL program, by the way.)