Frozen Fish 1: Amiga

home *** CD-ROM | disk | FTP | other *** search

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d3xx / d308 / freq.lha / FReq / FReq.doc < prev next >

Wrap

Text File | 1990-01-18 | 32KB | 637 lines

Introduction FReq is a general purpose file requester. It was written as a result of my dissatisfaction with most of the file requesters I am forced to use daily. FReq was designed to be easy to use and fast. You may ask yourself "What good is just a file requester without an application program built around it?" Answer: FReq was designed with a built-in REXX port allowing you to replace the file requesters in your existing applications with FReq (provided they also have a REXX port). Why would you want to do this? I feel that once you have used FReq, you will wish that all of your programs could use it. Recognizing that not everyone currently has the ARexx language (it will be part of the operating system in release 1.4 of AmigaDOS), I have provided a method of accessing FReq without it. Please refer to the section Using FReq without ARexx for a discussion of how to use FReq without the ARexx language. I am making FReq available to the general public without charge to encourage its use. If you are a software developer, please contact me to find out how you can incorporate FReq into your own application. Quick Run-Down of FReq's Features + User selects disks by volume name + Sorts directories and filenames separately + Filters ".info" files + Performs pattern matching + Can list all existing assignments + Displays file size + Displays file and directory dates + Displays file comments, protection bits, etc. + Stays resident in memory + Programmable using the ARexx language + Fast Operation. Able to scan hard disk directories at greater than 60 entries per second. Using FReq First copy the file 'FReq' to your 'DEVS:' directory. The example programs supplied with FReq assume that the 'FReq' file is located in your 'DEVS:' directory. With proper programming techniques it is not necessary to pre-load FReq to use it. You may want to do this, however, to prevent needing to load FReq when it's used the first time. If you use FReq a lot, then it would be a good idea to add the following line to your Startup-Sequence. RUN >NIL: <NIL: DEVS:FReq >NIL: <NIL: Note that nothing appears to happen after running FReq. FReq does not open its window until a program calls for it. The example program 'FReq.rexx' shows the proper way to call FReq from within a REXX program. The programs 'Startup.txed', 'Open.txed', and 'SaveAS.txed' can be used to replace the file requester in MicroSmiths' TxEd Plus editor program. Each of these programs contain comments explaining their use. Quick Guide to Operating FReq When FReq's window first opens, one of two possible items are listed in the display window. If FReq is called upon with the 'DisplayDef' option, the current directory is listed. Otherwise all currently mounted disk volume names are listed. Disk volume names may be identified by a small disk icon to the left of each name. The information FReq lists in its display window is color coded. This document will assume you are using the default preferences settings where color 1 is blue, color 2 is white, color 3 is black, and color 4 is red. If you are using colors different from these then substitute the colors you are using for the ones listed above. In the 'Preferences' program, color 1 is on the far left and color 4 is on the right. Filenames and directories are listed in FReq's display window. The directories in the current path are sorted and displayed first. Directories can be recognized by their red color. Files are white in color and are sorted and displayed after the directories. To list the contents of a directory in the display window, you simply "single-click" on the directory you want listed. After doing so the chosen directory is added to the current path and the contents of that directory is listed in the display window. To get back the directory listed previously, you can "single-click" on the "Parent" gadget located above and to the left of the display window. Doing so will subtract the current directory from the current path and then the "parent" directory will be displayed. Choosing a file is done in the same way that directories are chosen. If you "single-click" on a filename, that name is copied into the current filename box located just below the display window. Note that the path and filename is not returned to your calling program until the 'OK' button is selected. FReq's Menus FReq has several menus which access many of its special features. These menus are accessed in Intuition's normal manner using the right mouse button. Detailed descriptions of each menu and that menu's options are given below. Project Menu - The only option under the Project menu is the "About" option. Selecting "About" opens a window displaying information about FReq. Some of the information displayed includes the version number, the release date, and the public REXX port name. Display Menu - The display menu currently has three options: "Name Only", "File Size", and "File Date". Selecting the file size or date option causes the file size or date to display beside the filename in the display window. Each of these menu options also has an equivalent command key sequence. The key sequence corresponding to each menu option is listed below. Key Sequence Function Performed Right-Amiga N Displays only the filename Right-Amiga S Displays each file's size Right-Amiga D Displays file and directory dates Note that one of the Display Menu's options is always activated. The Display Menu option which is currently active is indicated by a check mark to the left of the menu option itself. Special Menu - The special menu has three options "Assigns", "Display .info", and "File Status". Each control one of FReq's special functions. The "Special" menu's options are described below in detail. Assigns - This menu option lists all of the logical assignments currently defined in your system. Sometimes it is much easier to locate a directory by its "Assigned" name rather than locating it by its full path name. If you are unfamiliar with logical assignments then refer to the AmigaDOS manual's Assign command. Two examples of assignments which should always be in existence are 'C:' (the directory containing all of the CLI commands) and 'S:' (the directory containing your 'Startup- Sequence' file and other script files). Choosing a logical assignment from the display window causes the complete path specification for that assignment to be displayed in the "Current Path Gadget". The "Assigns" menu option can also be performed by using the 'Right-Amiga A' keyboard sequence. Display .info - The "Display .info" menu option is one that can be toggled on or off. FReq normally filters out (e.g. does not list) any file with a suffix of '.info'. These ".info" files are used by Workbench to display the icons associated with files. For example, if your disk contains the two files 'Clock' and 'Clock.info', then the 'Clock' file is a program which you can execute and the 'Clock.info' file contains the picture of a clock that you will see in one of Workbench's windows. Normally, when choosing a file from an application program, you will not need to see the ".info" files and that is why FReq does not list them. If for some reason you do need to see these files, then you can do so by setting the 'Display .info' option "on". One reason you might need to access these files, for instance, is if you are using an Icon Editor program. When this option is "on" there will be a check mark to the left of this option in the menu. The "Display .info" filter can be toggled "off" or "on" by using the 'Right-Amiga I' command key sequence. In addition, the REXX command 'DisplayInfo' can be used to set this filter under program control. File Status - The "File Status" menu option opens a window displaying supplemental information on the currently selected file. The information displayed includes the file's size, date, protection bits, comment, and disk key. When you are finished viewing a file's status, close the status window by "single-clicking" on the close gadget located in the upper left- hand corner of the window's border. Note that while the status window is open, FReq becomes inoperable. The file status function can be accessed from the keyboard with the 'Right-Amiga F' command key sequence. FReq's Gadgets FReq has a number of gadgets represented by various icons and boxes located within its window. The function of each gadget is described in detail below. Display Window Gadget - This gadget is the large black rectangular box with a white border around it that occupies most of FReq's main window. This area is where filenames, directories, and disk volume names are displayed. A filename can be selected, or a directory or disk volume's contents can be listed simply by "single-clicking" on this gadget with the mouse pointer over the desired name. File dates and sizes are also displayed in this window by selecting the appropriate menu function. If you "double-click" on a filename in the display window, this will have the same effect as "single-clicking" on the filename and then selecting the "OK Gadget". "Double-Clicking" on a volume or directory name produces the same effect as "single-clicking". Parent Gadget - The "Parent Gadget" is located just above and to the left of the Display Window. The "Parent Gadget" causes the parent of the current directory to be listed. If the current directory is also the root directory of the disk being accessed, then selecting the parent gadget lists the mounted disk volume names. If you have descended several levels of directories, you can get back to the root directory of the currently selected disk by holding down either SHIFT key while selecting this gadget. Volumes Gadget - The "Volumes Gadget" is located to the right of the "Parent Gadget". Selecting the "Volumes Gadget" will cause all of the mounted disk volume names to be listed in the "Display Window". Note that the disk volume names are also listed when you select the "Parent Gadget" while at the root-level of a disk. Scroll Bar - The scroll bar is located to the right of the display window and is a long rectangular gadget. The scroll bar lists the hidden filenames or directories. Since the display window can only show up to 15 names at one time, a given path with more than 15 entries cannot be fully displayed at one time. The size of the scroll bar corresponds directly to the number of files in the current directory. For example, if there are 30 files in the current directory then the scroll bar will be half the size of its containing box; if there are 60 files then it will be one-forth the size, etc. To scroll through the listing of files and directories, place the mouse pointer over the scroll bar's knob and hold down the left mouse button. Moving the mouse up and down scrolls the display window to reveal the remaining files and directories. An alternate method to scrolling the display window is "paging" it. You can display the next or previous page of files and directories in the display window by "single- clicking" with the mouse pointer directly below or above the knob of the scroll gadget. Arrow Gadgets - The arrow gadgets located directly below the scroll gadget provide another method of scrolling the display window. If the left mouse button is held down over an arrow gadget, then the display window continues to scroll in the direction of the arrow until the gadget is either released or the end of the list of files is reached. Holding down a shift key while selecting the up-arrow gadget will move the display to the beginning of the file list. Likewise, holding down a shift key while selecting the down- arrow gadget will move to the extreme end of the file list. Current Path Gadget - This gadget is the long rectangular box located in the upper right corner of FReq's main window. Its purpose is to display the complete path specification of the directory listed in the display window. Normally the current path automatically adjusts to reflect the volume and directories chosen from the display window. You can, however, manually adjust the path by "single-clicking" on the "Current Path Gadget" and then typing in any valid AmigaDOS path specification. After pressing the Return or Enter key, the directory entered lists into the display window, provided a valid path specification is given. Note that this is a standard intuition string gadget and once activated all of the standard editing command key sequences will be available. These editing command sequences are as follows: Key Sequence Effect Right-Amiga X Erases the entire line Right-Amiga Q Undoes any changes made to the line Shift-Right Arrow Moves cursor to the end of the line Shift-Left Arrow Moves cursor to the start of the line If the current path is entirely erased, leaving the "Current Path Gadget" blank, the default path of the program calling FReq is displayed. Current Filename Gadget - This gadget is the long rectangular gadget located immediately below the display window showing the name of the currently selected file. If this gadget is blank, then no file is selected. The filename may be typed in from the keyboard or selected by "single-clicking" on a file listed in the display window. Note that the filename is not accepted until the "OK Gadget" is selected. This feature will allow you, during a save operation, to pick a filename from the display window similar to the name you want to call your file, then just make minor changes to it before selecting the "OK Gadget". For example, if you want to save a file with the name 'My_Document2' and there is already a file named 'My_Document' in the currently listed directory, then you can choose 'My_Document' from the display window and then simply edit that name adding the character '2' to the end. Doing this can save a lot of typing. The "Filename Gadget" is also a standard intuition string gadget. The editing commands listed in the description of the "Current Path Gadget" are available within this gadget as well. Pattern Gadget - This is the small rectangular gadget located below the "Current Filename Gadget". FReq provides complete AmigaDOS pattern matching capabilities. Normally, the "Pattern Gadget" contains the characters '#?', a pattern specification meaning "match everything". You can edit the pattern specification causing FReq to list only those files and directories matching the specified pattern. Some pattern specification examples are given below. Pattern Effect #? Lists all files and directories #?.doc Lists only the files ending with '.doc' c#? Lists only the files beginning with 'c' #?x#? Lists only the files containing an 'x' Keep in mind that it is possible to specify a pattern resulting in no files or directories being listed. If this happens, the screen flashes and an error message is displayed. The editing commands of the "Pattern Gadget" are the same as those listed for the "Current Path Gadget". OK and CANCEL Gadgets - These gadgets are located in the lower right corner of FReq's window and are identified by their respective names. They are used to signal the program calling FReq of your intentions. If the "OK Gadget" is selected, FReq passes the complete path specification and filename back to the calling program. If the "CANCEL Gadget" is selected, nothing is passed back to the calling program except the message that you have selected "Cancel". Selecting the "OK Gadget" lets your program know that you have selected a file and everything is "OK". Select the "Cancel Gadget" if you wish to abort the current operation of the calling program, such as the loading or saving of a file. Close Window Gadget - Selecting this gadget is similar to selecting the "CANCEL Gadget" with one important distinction. This gadget causes FReq to close itself down and free up any memory it was using. Normally FReq stays resident in memory and remains there until the 'CloseDown' command is received at its REXX port. Selecting the "Close Window Gadget" forces FReq to close itself down immediately and should indicate a "Cancel" condition to the calling program. Keyboard Commands FReq supports a number of keyboard commands. Note that if one of the string gadgets is activated, all of the "key- commands" are disabled until the "Return" or "Enter" key is pressed. You can tell if a string gadget is activated by the presence of a cursor within that gadget. When FReq's main window first opens the "Current Filename" string gadget is normally activated. Below is a table listing the "key-commands" FReq supports. Key Effect f Activates the "Current Filename Gadget" TAB Activates the "Current Filename Gadget" d Activates the "Current Path Gadget" p Activates the "Pattern Gadget" RETURN Same as "Single-Clicking" the OK Gadget ESC Same as "Single-Clicking" the CANCEL Gadget In addition, FReq also has the following "Command Key" sequences which may be used instead of their equivalent menu bar selections. Below is the table of "Command Key" sequences. Key Sequence Equivalent Menu Selection Right-Amiga N Display Name Only Right-Amiga S Display Size Right-Amiga D Display Date Right-Amiga A Display Assigns Right-Amiga I Display ".info" files Right-Amiga F File Status The SHIFT key has a special meaning when used in conjunction with either the "Parent Gadget" or the "Arrow Gadgets". The special functions performed are listed in the table below. Command Effect SHIFT + Parent Gadget List root directory of disk SHIFT + Up Arrow Gadget Displays the top of the file list SHIFT + Down Arrow Gadget Displays the end of file the list The REXX Port FReq has a REXX port named 'FileRequester' which can receive commands issued by an ARexx program. The program 'FReq.rexx' supplied with FReq is a programming example of the proper way to call FReq from within a REXX program. The commands FReq currently supports are described in detail below. Letter case is not important. Note that the brackets denote an optional parameter. DisplayDef - This command causes FReq to keep all of its current settings including the path specification, filename, and pattern matching specification. If the 'DisplayDef' command is issued before the 'GetFileName' command, then FReq will keep all of its previous settings when opening. Otherwise these settings will be cleared. Note that the 'DisplayDef' command must be issued each time you call upon FReq and desire the default settings to be maintained. This command is also required if you wish to modify one of the default settings with one of the 'Set...' commands listed below. SetTitle [title] - This command will display title in the "drag bar" of FReq's main window. 'Select a File' is the title displayed by default. The title should be set to a meaningful message telling the user why the file requester was called. Some good examples are: 'Select a File to Load', 'Choose an Archive to Extract', 'Select a Picture to View', etc. SetPath [path] - This command sets the default path specification to path. If this command is issued before the 'GetFileName' command, then path is displayed in the "Current Path Gadget" and the contents of the directory specified by path will be listed in the display window when FReq first opens. If path is not a valid path specification then no files are listed. Note that you must also use the 'DisplayDef' command in conjunction with this command in order for 'SetPath' to have any effect. The 'SetPath' command sets the default path and unless the 'DisplayDef' command is also issued, all the defaults will be cleared when FReq opens. SetPattern [pattern] - This command sets the pattern matching specification to pattern. Normally it is good practice for the pattern matching specification to be set by the user. This matching specification applies to directories as well as files, therefore, if you set a pattern using this command, the user may not be able to fully navigate their directory tree because some directories may not be displayed. The exception to this rule is when you know ahead of time in which directory the user needs to be looking. For example, if you want to list all of the available libraries, then you could set the current path to 'LIBS:' and the pattern to '#?.library'. Note that like the 'SetPath' command, you must also use the 'DisplayDef' command in conjunction with 'SetPattern' in order for this command to have any effect. The 'SetPattern' command sets the default pattern matching specification and unless the 'DisplayDef' command is also issued, all the defaults will be cleared when FReq opens. SetFileName [name] - This command sets the default filename to name. No checking is done to determine whether or not name is a valid filename. Note that you must also use the 'DisplayDef' command in order for this command to have any effect. The 'SetFileName' command sets the default filename in the "Current Filename Gadget" and unless the 'DisplayDef' command is also issued all the defaults will be cleared when FReq opens. GetFileName - This command asks FReq for a filename. It returns the complete path specification and filename in the 'Result' variable of the calling REXX program. You should first, however, check the value of the 'RC' return code variable to find out if a filename was returned. If 'RC' is equal to 0, then a path and filename was returned. Otherwise no filename is returned and the 'Result' variable remains unchanged. The possible values for 'RC' are listed below. Value of RC Meaning of this return code 0 The user selected the OK gadget 1 The user selected the CANCEL gadget 2 The user selected the Close Window gadget Note that most of FReq's other commands must be issued before the 'GetFileName' command in order for them to work. The 'GetFileName' command will pause your REXX program until the user selects either OK, CANCEL, or Close Window. DisplayInfo ON|OFF - This command turns "on" or "off" the ".info file" filtering feature of FReq. Normally this option is set to "off" because there is usually no need to have these files listed. Of course if you are using an Icon Editor you may want to see the ".info" files. CloseDown - The 'CloseDown' command will cause FReq to terminate, freeing all memory that it was using. It is normally a good idea to leave FReq resident in memory as this will result in not having to load it in from disk each time it is needed. However, if you need to save memory then you may want to "CloseDown" FReq after using it. Using FReq without ARexx This first release of FReq is supplied in two versions. To keep FReq as small as possible I decided to implement a separate version which works without the ARexx language. The version of FReq which doesn't require the ARexx language (version b) is the file named 'FReq_v1b'. This version of FReq sends the path specification and filename to the standard output. Normally the "standard output" is the window from which FReq was invoked. You can change this, however, by using redirection when you execute FReq. For example, to send the path specification and filename to a file in RAM: named 'FileName' execute FReq as follows: FReq_v1b >RAM:FileName [ DEFAULT ] Note that the "DEFAULT" key word is optional and you do not type the bracket characters. When using version b of FReq, the only option available is the "DEFAULT" option. This option causes the default directory to list when FReq opens. Without this option, the volume names list when FReq first opens. Unlike version 1.0, version b of FReq clears itself out of memory after each invocation. It would be a good idea to copy 'FReq_v1b' to the RAM disk if version b of FReq is being used. Version b of FReq was primarily provided to allow AmigaBASIC programmers to use FReq. You can call FReq from within AmigaBASIC by using the dos.library's Execute() function. Note that in order to use the Execute() function from BASIC you must first issue the LIBRARY statement to open 'dos.library'. A detailed description of how to do this is beyond the scope of this manual. Refer to the AmigaBASIC manual's description of the CALL and LIBRARY statements for a description of how to use external functions. You can also use version b of FReq within your AmigaDOS scripts. However, you will need some way of retrieving the filename from the file you send it to. An example of doing this with version 1.3 of AmigaDOS is given below. FReq_v1b >ENV:FileName GetEnv FileName Error Codes If you encounter an error during the execution of a REXX program sending commands to FReq, you can determine what the error is by examining the 'RC' variable. Below is a table of possible error code returns and their meanings. Error Code Meaning 50 Invalid Command. A command was sent to FReq which it did not recognize. 51 Invalid Option. The option given after a command is either not valid or an option was required and not found. 99 Out of memory Error. This error can occur whenever your computer gets low on memory. Most of the time this error will cause FReq to close down freeing any memory it used.