Fresh Fish 5

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

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / util / cliphistory-1.0.lha / ClipHistory / ClipHistory.man < prev next >

Wrap

Text File | 1994-04-03 | 18.4 KB | 469 lines

This file describes ClipHistory, version 1.0, a program that adds a history to the clipboard. Introduction ************ This is a program that I've been thinking of doing for a long time, but I haven't actually implemented it until now. I think first I got the idea when I had used the history feature of PowerSnap (by Nico François) a little while. I soon realised that it was a very convenient feature. But other programs uses the clipboard as well. The history PowerSnap maintains only applies to the text that PowerSnap writes to the clipboard, not the ones e.g. my editor writes. And I thought that it would indeed be useful to have them in a history too. One problem with such a history is that it easily can eat up a lot of memory, since cuts and copies in an editor can be rather large at times. To remedy this problem, there are several filtering options, that limits the amount of memory ClipHistory may use. But more about this later on in this document. One interesting detail: ClipHistory is a completely system friendly program, in that it doesn't patch any functions at all. It only uses well documented features of the operating system. This does have a minor drawback: ClipHistory can miss clips, if several clips are written in a very short time. But this shouldn't be any problem, I think.. :) Legal information ***************** ClipHistory is freeware, i.e. copyrighted, freely distributable software. Feel free to use and copy this program, as long as the following restrictions are fulfilled: * All files are copied without any alterations. If any extra files are added, it must be obvious that they don't belong to the original distribution, nor that they don't must be included in any redistribution. Exception: So called "BBS ads" may not be added. * The copying is done on a non-commercial basis. A small fee to cover media costs etc. may be charged. * The copier isn't claiming the copyright of this program. Any exeptions from the above requires a written permission from the author. No warranty =========== THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. System requirements ******************* ClipHistory have very modest system requirements. It needs OS 2.04 or better, although OS 3.0 or better will make ClipHistory operate slightly better.. :) If you have ReqTools (by Nico François) installed, then ClipHistory will use ReqTools for its requesters (you can disable this if you like). Otherwise the "normal" system requesters will be used. Installation ************ ClipHistory is easy to install. Simply copy the program (and its icon) to WBStartup, or whereever you find convenient. If you have OS 2.1 or better, you might want to copy a catalog file as well, to make ClipHistory operate in another language than english. The easiest way is to let the Installer do it (if you have it that is! :). If not, copy the file cliphistory.catalog as found in the Catalogs/<language> drawer to Locale:Catalogs/<language> (or to a the drawer Catalogs/<language> in the same drawer as you placed ClipHistory. In either case, <language> should be one of the languages you have select in the Locale preferences editor. If there is no catalog file for your language, please try to fill in the file Empty.ct in the Catalogs drawer and send it to me. I will then include the catalog in the next release of ClipHistory. Usage ***** To use ClipHistory, you first make sure that the tooltypes are set up properly. Then start it. You can also start if from a shell, but then you must remember to Run it (and to write suitble arguments). To make it permanently installed, simply drop it into WBStartup, or enter a suitable line in your S:User-Startup file. ClipHistory installs itself as a commodity, so you can use the Commodities Exchange program to show the interface, disable/enable it, or remove it completely. Starting ClipHistory a second time (for the same clipboard unit) will cause the first copy to show the interface. Pressing the hotkey will also open the interface (CX_POPKEY, see Options). The user interface of ClipHistory is very simple; it contains of a window with a list gadget. This list contains all the remembered clips. There is also a menu attached (see Menus). The text showed in the list is either the text - if it is a text clip - or the type of the IFF clip (everything on the clipboard should be in IFF format), followed by its size (in bytes). If you have OS 3.0 or higher, the non-text clips will be shown in bold (or at least something similar to bold). To select an item in the list, you either click once on it with the mouse, or you use the cursur up/down keys (optionally with the shift/alt/ctrl qualifiers) to highlight the requested item. To copy an item to the clipboard, you double-click on the item, or press return when the proper item is selected. Unless the STICKY option (see Options) have been used, the window will close. Escape closes the window. Menus ***** The window ClipHistory opens have the following menus: Project Save clip as... This allows you to save the currently selected item to a file of your choice. About... Shows some information about the program and the history. Hide Close the window, but don't quit. Quit Close the window and quit. Edit Delete... This will delete the currently selected item. You can also press Del to do this. Delete all... This will delete all clips in the list. You can also press Shift-Del to do this. Options Create icons? If checked, then icons will be created for the files you save. This is the same as the option CREATEICONS (see Options). Save text as IFF? If checked, then text clips (those that shows up as "normal" text in the window) will be saved as IFF files. If you save them as normal text, then some information might be lost (technical note: all CHRS chunks will be saved, but no other). Same as the option TEXTASIFF (see Options). ReqTools? If checked, then ReqTools will be used for requesters, if ReqTools is available, that is. Same as the option REQTOOLS (see Options). Options ******* Options can be specified in the tooltypes (when starting from the Workbench) or on the command line (when starting from a Shell). CX_PRIORITY This value specifies the priority ClipHistory will have in the commodities input chain. This priority only applies to the hotkey. Default is 0. Accpted range is -128 to 127. CX_POPKEY This specifies the hotkey to use to open the window. Default is "control lalt c". Please refer to your Amiga manual for more information about hotkey descriptors. Note: If this string is 100 chars long or more, unpredictable things may happen when you open the window. There is (currently) no check for this. I hope this doesn't cause any problems for anyone... :) CX_POPUP If YES, then ClipHistory will open the window upon startup (this is the default). Use NO to disable this. CLIPUNIT This value specifies the clipboard unit to use. Default is 0. Accepted range is 0 to 255. You can start one copy of ClipHistory for each clipboard unit. In Commodities Exchange, the name will be "ClipHistory <unit>", where <unit> is the unit you specify here. TOOLPRI This argument specifies the "normal" priority for ClipHistory. To make sure that ClipHistory doesn't miss any clips, even if the computer is doing much work, you might want to rise the task priority of ClipHistory. Default is to use whatever priority ClipHistory was started in (this is normally 0). Accepted range is -128 to 4. Note: The Workbench also supports the TOOLPRI tooltype. It was added to ClipHistory so that Shell users easily can change the priority as well. WORKPRI Some operations ClipHistory does can take a little time sometimes. Here you can specify the priority ClipHistory should use during this time, so that other programs can run normally. Usually a negative value should be entered. Default is not to change the priority. Accepted range is -128 to 4. SILENT If YES, then don't display any requesters for "clip operation errors", like when there was a problem reading/writing to the clipboard, or when there wasn't enough memory to save a clip. Default is NO. PUBSCREEN This specifies the public screen on which ClipHistory should open its window on. Default is the frontmost screen if it is public (if OPENONALL is on, it will use the frontmost screen anyway), or the default public screen. OPENONALL If YES, then ClipHistory will open on the frontmost screen, regardless if it is public or not. Default is NO. Note: In order for this to work properly, a function in Intuition (CloseScreen()) needs to be patched (this patch is only installed if this option have been activated). This might make it impossible for ClipHistory to remove itself from the system if some other program have patched the same function. If you have a SetMan-like program installed, this should never happen. FONTNAME This string specifies the name of the font (including the ".font" extension) to use for the window/menus. If not specified, then the current screen font is used. You must specify both FONTNAME and FONTSIZE. Hint: If you have MagicWB, it can be a good idea to use e.g. XHelvetica, since that font is "complete", i.e. chars than normally aren't printable holds graphics to identify the char in question. FONTSIZE This value specifies the size of the above font. You must specify both FONTNAME and FONTSIZE. WINDOWLEFT Initial left edge of the window. Default is to center the window on the screen. WINDOWTOP Initial top edge of the window. Default is to center the window on the screen. WINWIDTH Initial width of the window. Default is <width of the screen>/2. WINHEIGHT Initial height of the window. Default is <width of the screen>/3. STICKY If YES, ClipHistory won't close the window after writing a clip to the clipboard. Default is NO. POPSCREEN If YES, then ClipHistory will - when closing its window - restore the screen that was in front before the window was opened. This only needs to be done if that screen wasn't public. Default is NO. Note: Using either PUBSCREEN, OPENONALL or STICKY will disable this option. SAVEPOS If YES, then ClipHistory will remember the current position of the window when you close it. Otherwise it will reopen using the position specified in the arguments (or the defaults). Default is NO. SAVESIZE If YES, then ClipHistory will remember the current size of the window when you close it. Otherwise it will reopen using the size specified in the arguments (or the defaults). Default is NO. MAXCLIPS Maximum number of clips that the history can hold. Any value accpted. Note that 0 really means 1... Default is 32767 (the listview handling routines in the OS can't cope with more, so.. :). MAXCLIPSIZE If the clip is larger than this value, then it will not be saved in the history. Using 0 here will disable the history. Default is the MAXMEM limit (see below) if that one is specified. Otherwise there is no limit. MINCLIPSIZE If the clip is smaller than this, then it will not be saved in the history. Default is 0. Please note that this refers to the total size of the clip, including the extra overhead due to the IFF file format. For a minimal IFF file (as saved by e.g. PowerSnap), this overhead is 20 bytes. Also, an IFF file is (read: should be) always padded to an even number of bytes. Thus, a relatively useful minimum could be 22, which would force each saved clip to have at least 3 data bytes (when talking about saved text at least). MAXMEM This specifies how much memory the history may use at most. The history is dynamically allocated, using so called memory pools (to reduce memory fragmentation). Thus, the actual amount of memory used might be a little more than this value. Default is no max (other than the amount of free memory :). MATCH If YES, check all new items against the last one, and only save the new one if it is different. Default is NO. FULLMATCH Like MATCH, but check all entries instead. Default is NO. Warning: This can take some time if you have a large history (ClipHistory will use the WORKPRI (see above) during this check). If more than one clip is written to the clipboard during this time, only the last one will be remembered. CASE If NO, then ClipHistory will ignore the case when comparing two clips (when either MATCH or FULLMATCH have been used). Obviously, this is only possible when the clip contains text (FTXT). Default is YES. FILTER Here you can specify which IFF types that should be saved (or not saved, if REJECT have been specified). Space separate the items. Case is important. There are many different IFF types available, and I can't mention them all, but here is a list over the most common ones: FTXT Text. ConClip and PowerSnap saves these ones. ILBM Graphics/palettes. Saved by e.g. IconEdit. 8SVX Sound (samples). REJECT Make the FILTER (see above) reject on a match instead of accept, i.e. reverse the action of the filter. TEXTASIFF If YES, then FTXT clips will be saved as normal text instead of as an IFF file. All clips that shows up as "normal" text in the window are FTXT clips. Note that some information may be lost (e.g. font information). Default is NO. CREATEICONS If YES, then an icon will be created for each clip saved. Default is NO. REQTOOLS If YES, then ClipHistory will use ReqTools for requesters, if it should be available. Default is YES. Future ****** There are a few things I might add to ClipHistory: * More IFF parsing. Now it is minimal, only reading/writing exactly what is on the clipboard, with a minor "support" for FTXT. Enhanced parsing could e.g. reduce the overhead for FTXT clips, by only saving the actual text. * Separate accept and reject filters. I would need to alter the way they are specified though (now I'm using ReadArgs() "/M" specifier for this, and ReadArgs() don't like several "/M" specifiers in one template.. :). * Load of single clips and/or load/save of the entire history. * Prefs window, to edit/save the settings. Perhaps as a separate prefs program. * A way to view a large clip in full. I'm not sure how, but something could be nice. Perhaps writing the clip to a temporary file, and let some viewer program handle it (like MultiView)? * Some other way of "highlighting" non-text clips on OS 3.0 or better. Problem is that I don't know how I should change it. Please tell me if you have any ideas. * Make a Triton version (maybe ClipHistory will require Triton). None of these things are important for me, but feel free to send me a note telling me what *you* would like to see added (see Author contact). Author contact ************** Feel free to send comments, bug reports, money, or whatever, to: S-mail: Magnus Holmgren Rydsvägen 254 A:14 S-582 51 Linköping SWEDEN E-mail: cmh@augs.se (internet) or 2:204/404.6 (fidonet). Acknowledgements **************** Thanks go to the following persons: Nico François His program PowerSnap inspired me do write this program in the first place. He also sent me a few small (but useful) functions I needed, and came with a few suggestions/bug reports. Nikolai Waldman Suggestions. Michael Berg Bug report and suggestions. Program history *************** Version 1.0: Initial release.