@DataBase ClipHistory.guide @$VER: ClipHistory.guide 2.4 (12.4.97) @(C) Copyright © 1994/96-97 by Magnus Holmgren @Author Magnus Holmgren @Node Main "ClipHistory.guide" @{u}@{b}@{fg highlight}ClipHistory 2.4@{fg text}@{ub}@{uu} Copyright © 1994/96-97 by Magnus Holmgren Welcome to @{b}ClipHistory@{ub}, a program that adds a history to the clipboard. @{" Introduction " Link "Introduction"} @{" Legal information " Link "Legal information"} @{" System requirements " Link "System requirements"} @{" Installation " Link "Installation"} @{" Usage " Link "Usage"} @{" Menus " Link "Menus"} @{" Options " Link "Options"} @{" ARexx " Link "ARexx"} @{" The Future " Link "Future"} @{" Acknowledgements " Link "Acknowledgements"} @{" Author contact " Link "Author contact"} @{" Program history " Link "Program history"} @EndNode @Node "Introduction" "ClipHistory.guide/Introduction" @{u}@{b}Introduction@{ub}@{uu} This is a program that I thought about writing for a long time (a year or so! :) before I actually wrote it. I first got the idea when I had used the history feature of @{b}PowerSnap@{ub} (by Nico François) a little while. I soon realised that it was a very convenient feature. The problem is that other programs uses the clipboard as well. The history @{b}PowerSnap@{ub} maintains only applies to the text that @{b}PowerSnap@{ub} writes to the clipboard, not the ones e.g. my text 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 @{b}ClipHistory@{ub} may use. But more about this later on in this document. One interesting detail: @{b}ClipHistory@{ub} is a completely system friendly program, in that it doesn't patch any functions at all (unless you really want it to! :). It only uses well documented features of the operating system. This does have a minor drawback: @{b}ClipHistory@{ub} can miss clips, if several clips are written in a very short time. But this shouldn't be any problem, I think.. :) @EndNode @Node "Legal information" "ClipHistory.guide/Legal information" @{u}@{b}Legal information@{ub}@{uu} @{b}ClipHistory@{ub} 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, and that they don't need to be included in any redistribution. Exception: So called "BBS ads" may @{i}not @{ui}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. @{u}@{b}No Warranty@{ub}@{uu} @{b}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.@{ub} @EndNode @Node "System requirements" "ClipHistory.guide/System requirements" @{u}@{b}System requirements@{ub}@{uu} @{b}ClipHistory@{ub} have very modest system requirements. It needs OS 2.04 or better, although OS 3.0 or better will make @{b}ClipHistory@{ub} operate slightly better. Other than that, nothing special is needed. If you have @{b}ReqTools@{ub} (by Nico François and yours truly ;) installed, then @{b}ClipHistory@{ub} will use @{b}ReqTools@{ub} for its requesters (you can disable this if you like). Otherwise the "normal" system requesters will be used. @EndNode @Node "Installation" "ClipHistory.guide/Installation" @{u}@{b}Installation@{ub}@{uu} @{b}ClipHistory@{ub} is easy to install. Simply copy the program (and its icon) to @{b}WBStartup@{ub}, or whereever you find convenient. If you have OS 2.1 or higher, you might want to copy a catalog file as well, to make @{b}ClipHistory@{ub} operate in another language than english. The easiest way is to let the @{b}Installer@{ub} do it. If not, copy the file @{b}cliphistory.catalog@{ub}, found in the @{b}Catalogs/@{ub} drawer, to @{b}Locale:Catalogs/@{ub} (or to the drawer @{b}Catalogs/@{ub} in the same drawer as you placed @{b}ClipHistory@{ub}). In either case, should be one of the languages you have selected in the @{b}Locale@{ub} preferences editor. If there is no catalog file for your language, please try to fill in the file @{b}Empty.ct@{ub} in the @{b}Catalogs@{ub} drawer and send it to me. I will then include the catalog in the next release of @{b}ClipHistory@{ub}. It would be nice if you could translate the @{b}Installer@{ub} script as well. @EndNode @Node "Usage" "ClipHistory.guide/Usage" @{u}@{b}Usage@{ub}@{uu} To use @{b}ClipHistory@{ub}, you first make sure that the @{"tooltypes" Link "Options"} are set up properly. Then start it. You can also start if from a shell, but then you must remember to @{b}Run@{ub} it (and to write suitable arguments). To make it permanently installed, simply drop it into @{b}WBStartup@{ub}, or enter a suitable line in your @{b}S:User-Startup@{ub} file. @{b}ClipHistory@{ub} installs itself as a commodity, so you can use the Commodities @{b}Exchange@{ub} program to show the interface, disable/enable it, or remove it completely. Starting @{b}ClipHistory@{ub} a second time (for the same clipboard unit (option @{b}CLIPUNIT@{ub})) will cause the first copy to show the interface. Pressing the hotkey will also open the interface (option @{b}CX_POPKEY@{ub}). See @{"Options" Link "Options"} for more information. The user interface of @{b}ClipHistory@{ub} is very simple; it contains of a window with a list gadget. This list contains all the remembered clips. There is also a menu strip attached (see @{"Menus" Link "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. 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 one of 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 @{b}STICKY@{ub} option (see @{"Options" Link "Options"}) have been used, the window will close. To display a clip, you can enter Alt-Return, in addition to using the menus. Esc closes the window. @EndNode @Node "Menus" "ClipHistory.guide/Menus" @{u}@{b}Menus@{ub}@{uu} The window @{b}ClipHistory@{ub} opens have the following menus: @{b}Project@{ub} @{b}About...@{ub} Show some information about the program and the history. @{b}Hide@{ub} Close the window, but don't quit. @{b}Quit@{ub} Close the window and quit. @{b}Edit@{ub} @{b}Open clipboard...@{ub} This will open a file requester, allowing you to select a file that will be written to the clipboard. If it is an IFF file, it will be copied as it is, otherwise it will be written as an IFF FTXT file. @{b}Save clipboard as...@{ub} This will open a file requester, allowing you to select a filename to which the current clipboard contents will be written. @{b}Show clipboard...@{ub} This will write the current clipboard contents to a temprary file, and start the @{b}SHOWCLIP@{ub} program to show this file (see @{"Options" Link "Options"} for more information), @{b}Clear clipboard@{ub} Simply clear the clipboard, by writing a special (and small) IFF EMTY file to it. @{b}History@{ub} @{b}Delete item...@{ub} This will delete the currently selected item. You can also press Del to do this. @{b}Delete all items...@{ub} This will delete @{i}all @{ui}clips in the list. You can also press shift-del to do this. @{b}Save item as...@{ub} This allows you to save the currently selected item to a file of your choice. @{b}Show item...@{ub} This will write the currently selected item to a temporary file, and start the @{b}SHOWCLIP@{ub} program to show this file (see @{"Options" Link "Options"} for more information), @{b}Options@{ub} @{b}Create icons?@{ub} If checked, then icons will be created for the files you save. This is the same as the option @{b}CREATEICONS@{ub} (see @{"Options" Link "Options"}). @{b}Save text as IFF?@{ub} 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(s)). Same as the option @{b}TEXTASIFF@{ub} (see @{"Options" Link "Options"}). @{b}ReqTools?@{ub} If checked, then @{b}ReqTools@{ub} will be used for requesters, if it's available. Same as the option @{b}REQTOOLS@{ub} (see @{"Options" Link "Options"}). @{b}Sticky?@{ub} If checked, then then @{b}ClipHistory@{ub} won't close the window after writing a clip to the clipboard. Same as the @{b}STICKY@{ub} option (see @{"Options" Link "Options"}). @EndNode @Node "Options" "ClipHistory.guide/Options" @{u}@{b}Options@{uu}@{ub} Options can be specified in the tooltypes (when starting from the @{b}Workbench@{ub}) or on the command line (when starting from a @{b}Shell@{ub}). @{b}CX_PRIORITY@{ub} This value specifies the priority @{b}ClipHistory@{ub} will have in the commodities input chain. This priority only applies to the hotkey. Default is 0. Accepted range is -128 to 127. @{b}CX_POPKEY@{ub} This string specifies the hotkey that will open the window. Default is "control lalt c". Please refer to your Amiga manual for more information about hotkey descriptors. @{b}CX_POPUP@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will open the window upon startup (this is the default). Use NO to disable this. @{b}CLIPUNIT@{ub} This value specifies the clipboard unit to use. Default is 0. Accepted range is 0 to 255. You can start one copy of @{b}ClipHistory@{ub} for each clipboard unit. In Commodities @{b}Exchange@{ub}, the name will be "ClipHistory ", where is the number you specify here. @{i}Note: @{ui} @{b}ClipHistory@{ub} can be made resident. This is useful if you start several copies of @{b}ClipHistory@{ub}, so that all copies share the same code (which saves quite a bit of memory). @{b}TOOLPRI@{ub} This value specifies the "normal" priority for @{b}ClipHistory@{ub}. To make sure that @{b}ClipHistory@{ub} doesn't miss any clips, even if the computer is doing much work, you might want to rise the task priority of @{b}ClipHistory@{ub}. Default is to use whatever priority @{b}ClipHistory@{ub} was started in (this is normally 0). Accepted range is -128 to 4. @{i}Note: @{ui}The @{b}Workbench@{ub} also supports the @{b}TOOLPRI@{ub} tooltype. It was added to @{b}ClipHistory@{ub} so that @{b}Shell@{ub} users easily can change the priority as well. @{b}WORKPRI@{ub} Some operations @{b}ClipHistory@{ub} does can take a little time. Here you can specify the priority @{b}ClipHistory@{ub} should use during this time, so that other programs can run normally. Usually a negative value should be entered. The default is not to change the priority. Accepted range is -128 to 4. @{b}SILENT@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} won't display any requesters or flash the screen for various 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. @{b}PORTNAME@{ub} This string lets you specify the name of the @{b}ARexx@{ub} port @{b}ClipHistory@{ub} opens. The default is "CLIPHISTORYx", where "x" is the clipboard unit the history operates on (see @{b}CLIPUNIT@{ub}). If you enter an empty string (""), then no @{b}ARexx@{ub} port will be opened. If @{b}ARexx@{ub} isn't installed, then no @{b}ARexx@{ub} port will be opened either. @{b}NEXTKEY@{ub} This string specifies the hotkey that will activate the next item in the history (if possible) and paste that one to the clipboard without opening the window. Useful when you have snapped a few strings and want to paste them somewere. This works even if the window should happen to be open. Default is no hotkey (""). @{b}PREVKEY@{ub} This string specifies a hotkey that works much like @{b}NEXTKEY@{ub}, but it will paste the previous history item (if possible) instead. Default is no hotkey (""). @{b}AUTOSELECT@{ub} By default, @{b}NEXTKEY@{ub} and @{b}PREVKEY@{ub} will fail (flashing the display to inform you about it) if no clip item is selected. If this option is set to YES, then @{b}NEXTKEY@{ub} will automatically select the first item in the list, and @{b}PREVKEY@{ub} will select the last item. @{b}PUBSCREEN@{ub} This string specifies the public screen on which @{b}ClipHistory@{ub} should open its window on. Default is the frontmost screen if it is public (if @{b}OPENONALL@{ub} is on, it will use the frontmost screen anyway), or the default public screen. @{b}OPENONALL@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will open on the frontmost screen, regardless if it is public or not. Default is NO. @{i}Note: @{ui}In order for this to work properly, a function in @{b}Intuition@{ub} (@{b}CloseScreen()@{ub}) needs to be patched (this patch is only installed if this option have been activated). If some other program have patched the same program and you try to exit, then @{b}ClipHistory@{ub} will exit anyway, but it will leave a small memory allocation, to make sure there aren't any problems. If you have a @{b}SetMan@{ub}-like program installed, this should never happen. @{b}FONTNAME@{ub} 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 @{b}FONTNAME@{ub} and @{b}FONTSIZE@{ub}. Hint: If you have @{b}MagicWB@{ub}, it can be a good idea to use e.g. XHelvetica, since that font is "complete", i.e. chars that normally aren't printable holds graphics to identify the char in question. @{b}FONTSIZE@{ub} This value specifies the size of the above font. You must specify both @{b}FONTNAME@{ub} and @{b}FONTSIZE@{ub}. @{b}WINDOWLEFT@{ub} This value specifies the initial left edge of the window. Default is to center the window on the screen. @{b}WINDOWTOP@{ub} This value specifies the initial top edge of the window. Default is to center the window on the screen. @{b}WINWIDTH@{ub} This value specifies the initial width of the window. Default is / 2. @{b}WINHEIGHT@{ub} This value specifies the initial height of the window. Default is / 3. @{b}CENTERMOUSE@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will center the window under the mouse. This option will override the options @{b}SAVEPOS@{ub}, @{b}WINDOWLEFT@{ub} and @{b}WINDOWTOP@{ub}, if set to YES. Default is NO. @{b}NORMALGLYPHS@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will not use custom symbols in the menus (only when running under OS 3.0 or higher). This can be useful if you e.g. use @{b}MagicMenu@{ub}, which currently doesn't handle these symbols properly. @{b}SCREENMENUFONT@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will use the current screen font for the menus, rather than the font specified in @{b}FONTNAME@{ub} and @{b}FONTSIZE@{ub}. @{b}STICKY@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} won't close the window after writing a clip to the clipboard. Default is NO. @{b}SINGLECLICK@{ub} If this option is set to YES, then a single click with the mouse on an item is enough to paste it to the clipboard. Click with Shift, Alt or Ctrl pressed to select an item without pasting (a doubleclick with any qualifier down will also paste). If set to NO, a doubleclick is needed to paste the item. A single click with any qualifier down will then paste the item. Default is NO. @{b}POPSCREEN@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} 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. @{i}Note: @{ui}Using @{b}PUBSCREEN@{ub}, @{b}OPENONALL@{ub} or @{b}STICKY@{ub} will disable this option. @{b}SAVEPOS@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} 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. @{b}SAVESIZE@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} 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. @{b}MAXCLIPS@{ub} This value specifies the maximum number of clips that the history can hold. Default is 32767. Accepted range is 0 to 32767. Note that 0 really means 1. @{b}MAXCLIPSIZE@{ub} 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 @{b}MAXMEM@{ub} limit (see below) if that one is specified. Otherwise there is no limit (other than the amount of free memory). @{b}MINCLIPSIZE@{ub} If the clip is smaller than this value, then it will not be saved in the history. The default is 0. Please note that this value 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. @{b}PowerSnap@{ub}), 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). @{b}MAXMEM@{ub} This value 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). @{b}MATCH@{ub} If this option is set to YES, check all new items against the last one, and only save the new one if it is different. Default is NO. @{b}FULLMATCH@{ub} Like @{b}MATCH@{ub}, but check @{i}all @{ui}entries instead. This option overrides @{b}MATCH@{ub}. Default is NO. @{i}Note: @{ui}This can take some time if you have a (very) large history (@{b}ClipHistory@{ub} will use the @{b}WORKPRI@{ub} during this check). If more than one clip is written to the clipboard during this time, only the last one will be remembered. @{b}CASE@{ub} If this option is set to NO, then @{b}ClipHistory@{ub} will ignore the case when comparing two clips (when either @{b}MATCH@{ub} or @{b}FULLMATCH@{ub} have been enavled). Obviously, this is only possible when the clip contains text (FTXT). Default is YES. @{b}FILTER@{ub} Here you can specify which IFF types that should be saved (or not saved, if @{b}REJECT@{ub} have been specified). Space separate the items. Case @{i}is @{ui}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: @{b}FTXT@{ub} Text. E.g. ConClip and PowerSnap saves these ones. Text editors are likely to write them as well. @{b}ILBM@{ub} Graphics/palettes. Saved by e.g. IconEdit. @{b}8SVX@{ub} Sound (samples). @{b}REJECT@{ub} If this option is set to YES, them the @{b}FILTER@{ub} (see above) will reject the clip on a match instead of accept it, i.e. it reverses the action of the filter. Default is NO. @{b}SHOWCLIP@{ub} This option lets you specify the program to use to view a clip. @{b}ClipHistory@{ub} will write the currently selected clip (or the contents of the clipboard) to a temporary file, and then start this program with the filename as the first argument. Note that this file will not be deleted by @{b}ClipHistory@{ub} (you can do this with a script if you want to). Default is "MultiView". @{b}TEMPDIR@{ub} This option specifies were @{b}ClipHistory@{ub} should write the temprary files that the @{b}SHOWCLIP@{ub} program should read and display. Default is "T:". @{b}FILETYPE@{ub} If this option is specified, then the file type will be the second argument to the @{b}SHOWCLIP@{ub} program. This way, a simple @{b}Shell@{ub} script can be used to view the file (see the included @{b}ShowClip@{ub} script). This argument will be "text" if the clip was written as a simple text file (@{b}TEXTASIFF@{ub} is set to NO), otherwise the IFF file type will be the second argumet (see @{b}FILTER@{ub} for more information about IFF types). Default is NO. @{b}SAVEPATH@{ub} This option lets you specify the directory in which the "Save clipboard..."/"Save item..." file requester should open the first time (it remembers the last used directory). The default is to open in the current directory for @{b}ClipHistory@{ub} @{b}TEXTASIFF@{ub} If this option is set to YES then FTXT clips will be saved as an IFF file, rather than a normal ASCII-file. All clips that shows up as "normal" text in the window are FTXT clips. Note that some information may be lost if a clip is saved as ASCII (e.g. font information). Default is NO. @{b}CREATEICONS@{ub} If this option is set to YES, then an icon will be created for each clip that is saved. Default is NO. @{b}REQTOOLS@{ub} If this option is set to YES, then @{b}ClipHistory@{ub} will use @{b}ReqTools@{ub} for requesters, if it should be available. Default is YES. @EndNode @Node "ARexx" "ClipHistory.guide/ARexx" @{u}@{b}ARexx@{uu}@{ub} As of version 2.0, @{b}ClipHistory@{ub} have an @{b}ARexx@{ub} port. This means you can access the history and the clipboard from your @{b}ARexx@{ub} programs. The port is called "CLIPHISTORYx" by default (where x is the clipboard unit, specified with the @{b}CLIPUNIT@{ub} argument), but you may change this by using the @{b}PORTNAME@{ub} argument. See @{"Options" Link "Options"} for more information. @{" Details " Link "Details"} @{" General commands " Link "General commands"} @{" History commands " Link "History commands"} @{" Clipboard commands " Link "Clipboard commands"} @{" Requester commands " Link "Requester commands"} @{" Window commands " Link "Window commands"} @{" Example scripts " Link "Example scripts"} @EndNode @Node "Details" "ClipHistory.guide/Details" @Toc "ARexx" @{u}@{b}Details@{uu}@{ub} The @{b}ARexx@{ub} commands in @{b}ClipHistory@{ub} are documented in this manner: GetPrefs PREFS/A => VALUE/N This line is then followed by an exaplanation of what the command does. First on the line is the name of the command (in this example: @{b}GetPrefs@{ub}). Case is not importand when looking for a command. After that follows the arguments (in some cases, there are no arguments). The @{b}=>@{ub} arrow indicates that what follows after it is the return value(s) (a command may return several pieces of information). If no @{b}=>@{ub} arrow is present, then the command returns no information. The arguments use the standard @{b}AmigaDOS@{ub} template. Thus, the keyword is optional, but must be specified if the argument doesn't come in the specified order. The keyword is the text before the @{b}/@{ub} char (and after any @{b},@{ub} char), and the character after is a modifier, that tells you a little about this argument. The following modifiers are used in this document (there are others, but they are not used here): @{b}/A@{ub} This argument is required. An error is returned if the argument isn't specified. @{b}/N@{ub} This argument is numeric. It should be a valid decimal number, or an error is returned. @{b}/S@{ub} This argument is a switch. The precense of this keyword enables a flag. If it is not present, the flag is not enabled. @{b}/F@{ub} All text following the keyword is taken as the argument, without any modifications. @{b}/M@{ub} Any number of arguments may be specified here. These modifiers may be combined, so e.g. @{b}/A/N@{ub} means that a numeric value must be specified. If no modifier is present, then there are no special requirements upon the arguments (at least not anything the argument parser (@{b}ReadArgs()@{ub}) can check). These modifiers also applies to the return values. But first we need some more information about the returns. The normal way of returning information to an @{b}ARexx@{ub} script is to place it in @{i}RC @{ui}(limited to numeric results, since this also returns errors from the command) or @{i}RESULT @{ui}(which may contain anything). In @{b}ClipHistory@{ub} (and several other programs) there is a little more control. Each command that returns some information also have the two "hidden" (i.e. not documented) arguments; @{b}VAR@{ub} and @{b}STEM@{ub}. These arguments specify were the return value should be placed. The @{b}VAR@{ub} argument specifies in which variable the result should be placed. This is baiscally the same as to return the value in @{i}RESULT.@{ui} The @{b}STEM@{ub} argument is a little different, and is mostly useful for commands that returns several pieces of information. The argument specifies the "stem base name" for the return values. Thus, if a command have the return template @{b}SIZE/N,ITEMS/N@{ub}, and we specified the stem base name @{b}TEST.@{ub}, then the variables (stems) @{i}TEST.SIZE @{ui}and @{i}TEST.ITEMS @{ui}would hold the returns (numeric values). If the return is in a normal variable, then the different returns will be placed after each other, separated by spaces. Now, there is a special return, which use the @{b}/M@{ub} modifier. If we use the same stem base name as above, and the command have the return template @{b}CLIP/M@{ub}, then the stem @{i}TEST.CLIP.COUNT @{ui}will hold the number of strings that are returned, and @{i}TEST.CLIP.0, TEST.CLIP.1...@{ui} (until @{i}TEST.CLIP.x, @{ui} where @{b}x@{ub} equals @{i}TEST.CLIP.COUNT @{ui}- 1) will hold the different strings. If the same information is returned in a normal variable, then there will first be the count, followed by the different strings, separated by spaces. If an argument contains spaces, then it usually needs to be "double quoted", like this: '"This is a correctly quoted string"' This is needed since @{b}ARexx@{ub} first removes the single quotes (@{b}'@{ub}) when it parses the string. @{b}ClipHistory@{ub} also needs quotes, to be able to separate the arguments (these quotes must use the @{b}"@{ub} char). Negative values also needs to be quoted (e.g. @{b}'-1'@{ub}). I'm not entirely sure why this is needed. Strings (e.g. file names) that contain a @{b}:@{ub} char need to be quoted as well. If an error occured, the variable @{i}RC2 @{ui}will usually hold an error message or a number (a dos error code. You can use @{b}Fault@{ub} to get an explanation for a certain number). Note that "OPTIONS RESULTS" must have be used in the script for this to happen. All commands sets @{i}RC @{ui}to 10 for an error, 5 for a warning (e.g. asking for a clip item that doesn't exist, or trying to do a window operation when the window isn't open), and 0 for all ok. The error code 20 is reserved for fatal errors, making @{b}ClipHistory@{ub} unable to parse the command, or properly return the result. The typical reason for this to happen is lack of memory. This is also returned if there are any pending commands when @{b}ClipHistory@{ub} is about to exit. The @{b}ARexx@{ub} interface in @{b}ClipHistory@{ub} was originally developed using @{b}ARexxBox@{ub}. The generated code was then modified in several ways to get it smaller (without loosing any functionality). @EndNode @Node "General commands" "ClipHistory.guide/General commands" @Toc "ARexx" @{u}@{b}General commands@{uu}@{ub} @{b}About@{ub} Simply open the about window. It will open on the same screen as the main window, or on the default public screen. @{b}CxActivate@{ub} Activate the @{b}Commodities@{ub} interface. Similar to the "Active" gadget in the @{b}Exchange@{ub} program. Returns 5 if the interface already was active. @{b}CxInactivate@{ub} Similar to @{b}CxActivate@{ub}, but inactivate the interface instead. Returns 5 if the interface already was inactive. @{b}GetPrefs PREFS/A => VALUE/N@{ub} Get the state of the specified preferences item. Currently, the following items may be specified: @{b}ICONS@{ub} The "Create icons?" menu item (@{b}CREATEICONS@{ub} argument). @{b}REQTOOLS@{ub} The "ReqTools?" menu item (@{b}REQTOOLS@{ub} argument). @{b}TEXTASIFF@{ub} The "Text as IFF?" menu item (@{b}TEXTAIFF@{ub} argument). @{b}STICKY@{ub} The "Sticky?" menu item (@{b}STICKY@{ub} argument). This corresponds to what is shown in the @{"Options" Link "Menus"} menu. See the @{"Options" Link "Options"} section for more information about these options. Currently, the value is set to 1 if the flag is set, or 0 if the flag isn't set. @{b}LockGUI@{ub} Lock the GUI, so that no input can be made (output can still me made). These calls nest, so remember to match them properly. @{b}Quit@{ub} Quit @{b}ClipHistory@{ub}. No confirmation requester will be shown. @{b}Show PUBSCREEN@{ub} Open the GUI. If a @{b}PUBSCREEN@{ub} argument is specified, then @{b}ClipHistory@{ub} will try to open on the specified public screen. @{b}UnlockGUI@{ub} Decrease the nesting count for the GUI lock. If we reach zero, unlock the GUI, re-enabling user input. If you call this command too many times (making the count negative), the count is reset to zero, and return 10. @{b}SetPrefs PREFS/A,VALUE/A/N@{ub} Set the state of the specified preferences item. Currently, the following items may be specified: @{b}ICONS@{ub} The "Create icons?" menu item (@{b}CREATEICONS@{ub} argument). @{b}REQTOOLS@{ub} The "ReqTools?" menu item (@{b}REQTOOLS@{ub} argument). @{b}TEXTASIFF@{ub} The "Text as IFF?" menu item (@{b}TEXTAIFF@{ub} argument). @{b}STICKY@{ub} The "Sticky?" menu item (@{b}STICKY@{ub} argument). This corresponds to what is shown in the @{"Options" Link "Menus"} menu. See the @{"Options" Link "Options"} section for more information about these options. If the value is 1 (or rather, not 0), then the flag is set, or if it is 0, the flag is cleared. @EndNode @Node "History commands" "ClipHistory.guide/History commands" @Toc "ARexx" @{u}@{b}History commands@{uu}@{ub} @{b}DeleteAllItems FORCE/S@{ub} Delete all items in the history. Use @{b}FORCE@{ub} to disable the confirmation requester. Returns 5 if the user cancelled the delete. @{b}DeleteItem ITEM/N,FORCE/S@{ub} Delete the specified item, or the currently selected if none was specified. Use @{b}FORCE@{ub} to disable the confirmation requester. Returns 5 if the user cancelled the requester, or the specified item didn't exist. @{b}GetTextItem ITEM/N => CLIP/M@{ub} Return the contents of the specified item, of if not specified, the currently selected item. If the clip doesn't contain any text, return 5 in @{i}RC@{ui}. The @{b}CLIP@{ub} array will hold the different CHRS chunks. Usually, there is only one. @{b}GetSelected => ITEM/N@{ub} Returns the ordinal number of the currently selected item, or -1 if no item is selected. @{b}ItemInfo ITEM/N => TYPE,SIZE/N,NUMCHRS/N@{ub} Return some information about the specified item, or the currently selected item if no argument is given. The follwing information is returned: @{b}TYPE@{ub} The type of the IFF file, usually FTXT, ILBM or 8SVX. @{b}SIZE/N@{ub} The size of the clip, in bytes. @{b}NUMCHRS/N@{ub} The number of so called CHRS chunks in the clip. If 0, then the clip doesn't contain any text. @{b}HistoryInfo => ITEMS/N,SIZE/N@{ub} Returns the following information about the history: @{b}ITEMS/N@{ub} Number of items currently in the history @{b}SIZE/N@{ub} The total size of the history, in bytes. @{b}LockHistory@{ub} Lock the history, so that no items can be added to it. These calls nest, so remember to match them properly. @{b}PutItem ITEM/N@{ub} Write the specified or currently selected item to the clipboard. @{b}SaveItemAs NAME,ITEM/N,REQUEST/S@{ub} Save the specified or currently selected item to the specified file. If no file name is specified, or the @{b}REQUEST@{ub} flag is used, show a requester to let the user specify the name. @{b}NAME@{ub} then specifies the default name in the requester. @{b}SelectItem ITEM/N,RELATIVE/S@{ub} Select the specified item. If the @{b}RELATIVE@{ub} flag is used, add the @{b}ITEM@{ub} to the currently selected item number (there must be a selected item for this to work). @{b}ShowItem ITEM/N@{ub} Show the specified, or currently selected item. See @{b}SHOWCLIP@{ub} in the @{"Options" Link "Options"} chapter for more information about this. @{b}UnlockHistory@{ub} Decrease the nesting count for the history lock. If we reach zero, unlock the history, making it possible to add new items. If you call this command too many times (making the count negative), the count is reset to zero, and return 10. @EndNode @Node "Clipboard commands" "ClipHistory.guide/Clipboard commands" @Toc "ARexx" @{u}@{b}Clipboard commands@{uu}@{ub} @{b}ClearClipboard@{ub} Clear the clipboard, by writing a special "empty" IFF-file to it. @{b}GetTextClip => CLIP/M@{ub} Return the contents of the clipboard. If the clipboard doesn't contain any text, return 5 in @{i}RC@{ui}. The @{b}CLIP@{ub} array will hold the CHRS chunks. Usually, there will only be one. @{b}PutFile NAME,REQUEST/S@{ub} Place the named file on the clipboard. If no name is given, or the @{b}REQUEST@{ub} flag is set, open a requester for the user to select a file. @{b}NAME@{ub} then specifies the default name in the requester. If the selected file is an IFF file, it will be copied as-is to the clipboard. Otherwise, @{b}ClipHistory@{ub} assumes the file contains text, and will write it as an IFF FTXT file. @{b}PutText TEXT/A/F@{ub} Put the specified text on the clipboard, as an IFF FTXT file. @{b}SaveClipAs NAME,ITEM/N,REQUEST/S@{ub} Save the clipboard contents to the specified file. If no file name is specified, or the @{b}REQUEST@{ub} flag is used, show a requester to let the user specify the name. @{b}NAME@{ub} then specifies the default name in the requester. @{b}ShowClip@{ub} Show the file in the clipboard. See the @{b}SHOWCLIP@{ub} argument in the @{"Options" Link "Options"} chapter for more information about this. @EndNode @Node "Requester commands" "ClipHistory.guide/Requester commands" @Toc "ARexx" @{u}@{b}Requester commands@{uu}@{ub} @{b}RequestFile TITLE,PATH,FILE,PATTERN,SAVEMODE/S => FILE@{ub} Show a file requester, with the specified title, default path and file, and the specified pattern, and return the selected name (@{b}FILE@{ub}). Use the SAVEMODE switch if you request a file to write data to. If the requester is cancelled, return 5 in @{i}RC@{ui}. @{b}RequestNotify PROMPT/A@{ub} Show the specified prompt in a requester with a single "Ok" gadget. @{b}RequestResponse TITLE,PROMPT/A,GADGETS@{ub} Show the specified prompt, with the specified title in a requester with an "Ok" and a "Cancel" gadget. Returns 5 if cancel was selected, or 0 if ok was selected. The @{b}GADGETS@{ub} option allows you to specify your own gadgets. The different gadgets should be separated by "|" chars. Returns 0 for the rightmost gadget, 1 for the leftmost, 2 for the next, and so on... @EndNode @Node "Window commands" "ClipHistory.guide/Window commands" @Toc "ARexx" @{u}@{b}Window commands@{uu}@{ub} @{b}ActivateWindow@{ub} Tries to activates the main window, if open. Returns 5 if the window isn't open. @{b}ChangeWindow LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N@{ub} Move and resize the window to the given coordinates, or as close as possible. '-1' for a given coordinate means "don't change this one". Returns 5 if the window isn't open. @{b}Hide@{ub} Simply close the window. @{b}IsOpen => OPEN/N@{ub} Returns 1 if the window is open, or 0 if it isn't. @{b}MoveWindow LEFTEDGE/N,TOPEDGE/N@{ub} Similar to @{b}ChangeWindow@{ub}, but this command only lets you change the position of the window. @{b}SizeWindow WIDTH/N,HEIGHT/N@{ub} Similar to @{b}ChangeWindow@{ub}, but this command only lets you change the size of the window. @{b}UnZoomWindow@{ub} If the window is zoomed, then unzoom it (possibly making it larger). Returns 5 if the window isn't open. @{b}WindowToBack@{ub} Simply move the window behind any other window(s), if possible. Returns 5 if the window isn't open. @{b}WindowToFront@{ub} Simply move the window in front of any other window(s), if possible. Returns 5 if the window isn't open. @{b}ZoomWindow@{ub} If the window isn't zoomed, then zoom it (possibly making it smaller). Returns 5 if the window isn't open. @EndNode @Node "Example scripts" "ClipHistory.guide/Example scripts" @Toc "ARexx" @{u}@{b}Example scripts@{ub}@{uu} Thogether with ClipHistory, you should find a couple of example ARexx scripts: @{i}@{b}Test.cliph@{ub} @{ui} A simple test script, that traverses all clips in the history, and collects some simple statistics about it. @{i}@{b}Dump.cliph@{ub} @{ui} Writes the contents of the history to a drawer, using a special name pattern, namely @{i}ClipHistory. @{ui} (where is a decimal number). Any previous files matching that pattern will be deleted. Edit the script to change the drawer the clips are written to. @{i}@{b}Restore.cliph@{ub} @{ui} The reverse of @{i}Dump.cliph@{ui}. That is, it loads all clips (matching the above pattern) found in the drawer (specified in the script) into @{b}ClipHistory@{ub}, optionally deleting the previous history contents. The two last scripts are included with @{b}ClipHistory@{ub} 2.4 and onwards. They allow you to easily make a snapshot of the current history, for reload at a later date. @EndNode @Node "Future" "ClipHistory.guide/Future" @{u}@{b}The Future@{uu}@{ub} There are a few things I might add to @{b}ClipHistory@{ub}: 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. Load/save of the entire history. Perhaps automated, so that the history contents can be (automatically) restored after a reboot. Store large clips on disk rather than in memory. Show (scaled) versions of graphics clips somehow. This would require OS 3.0 for several reasons. Prefs window, to edit/save the settings. Perhaps as a separate prefs program. I have done some work in this direction, but I've never finished it... Some other way of "highlighting" non-text clips on OS 3.0 or better. The problem is that I don't know how I should change it. :) Please tell me if you have any idea. AppWindow support. Dropped icons should then be pasted to the clipboard. Split and join clips (at line feed chars) These things are not that important for me, but feel free to send me a note telling me what @{b}you@{ub} would like to see added (see @{"Author contact" Link "Author contact"}). @EndNode @Node "Author contact" "ClipHistory.guide/Author contact" @{u}@{b}Author contact@{uu}@{ub} Feel free to send comments, bug reports (detailed ones, please), translations, money or whatever, to: S-mail: Magnus Holmgren Kvarnbergsvägen 5 S-444 47 Stenungsund SWEDEN E-mail: cmh@lls.se 2:203/512.10@fidonet.org @EndNode @Node "Acknowledgements" "ClipHistory.guide/Acknowledgements" @{u}@{b}Acknowledgements@{uu}@{ub} Thanks go to the following persons, for helping me in some way with this program: @{b}Nico François@{ub} His program @{b}PowerSnap@{ub} inspired me do write this program in the first place. He also sent me a few small (but useful) functions, and came with a few suggestions/bug reports. @{b}Nikolai Waldman@{ub} Suggestions. @{b}Michael Berg@{ub} Bug report and suggestions. @{b}Lars Eilebrecht@{ub} German translation. @{b}Georges Concalves@{ub} French translation and @{b}MagicWB@{ub} icon. @{b}Kenneth Fribert@{ub} Danish translation. @{b}Michael Balzer@{ub} For @{b}ARexxBox@{ub}, which was used as a base for the @{b}ARexx@{ub} interface (the code have been modified a "little".. Saved ~5 Kb from the program! :). @{b}Olaf Barthel@{ub} For the "menu glyph" code from @{b}term@{ub}. @EndNode @Node "Program history" "ClipHistory.guide/Program history" @{u}@{b}Program history@{uu}@{ub} @{b}Version 1.0:@{ub} Initial release. @{b}Version 1.1:@{ub} Removed some debugging code. Added the @{b}SINGLECLICK@{ub} flag. If YES, a single click on an item is enough to paste it to the clipboard. Use shift/alt/ctrl to select an item without pasting (a doubleclick with any qualifier down will also paste). If set to NO, a single click with any qualifier down will also paste the item. Recompiled with DICE 3.0. German catalog added. Unfortunately I don't have the source for it.. :) @{b}Version 2.0:@{ub} @{b}ARexx@{ub}-port with over 40 commands added. @{b}ClipHistory@{ub} is now residentable! It wasn't that easy... :) (try yourself with DICE, a couple of callback hooks and a patch! :) French catalog and installer script by Georges Goncalves included. Danish catalog by Kenneth Fribert included. German catalog source included. @{b}MagicWB@{ub} icon by Georges Concalves included. Added menu items to load/save/view/clear the current clipboard contents. You can also view an item in the history. Any font specified in the tooltypes needed to be in memory for @{b}ClipHistory@{ub} to find it. Now it will try to load it from disk if possible. If the screenfont or the font specified in the tooltypes didn't open, @{b}ClipHistory@{ub} will now use the system default font instead (rather than topaz/8). Added the following arguments: @{b}PORTNAME@{ub}, @{b}NEXTKEY@{ub}, @{b}PREVKEY@{ub}, @{b}AUTOSELECT@{ub}, @{b}SHOWCLIP@{ub}, @{b}TEMPDIR@{ub}, @{b}FILETYPE@{ub}, and @{b}SAVEPATH@{ub}. See @{"Options" Link "Options"}. @{b}ClipHistory@{ub} will now always exit even if someone have overpatched the function @{b}ClipHistory@{ub} may patch. If the patch was overpatched, there will be a small memory loss. When doing a full check, and a match is found, then @{b}ClipHistory@{ub} will select the item that matched, so that the selected item reflects the current clipboard contents. In general, @{b}ClipHistory@{ub} will do its best to keep the selected item up to date. This includes deselecting any item if no item in the history matches the current clipboard contents (e.g. a paste was filtered out) @{b}ClipHistory@{ub} will now use the OS 3.0 wait pointer when needed. @{b}SysIHack@{ub} "support" added (i.e. it handles larger-than-normal window size gadgets properly). The window will now backfill with the current background color, rather than color 0. The "Settings/Create icons" menu item was not working, in that icons never got created. I had written a function to do it, but it wasn't used anywere! :) Non-FTXT clips are now shown in real bold (if possible). When deleting a single item, a new item will be selected, if possible. @{b}Version 2.1:@{ub} The selected item wasn't always visible when the window opened. Removed @{b}Enforcer@{ub} hits when data was written to the clipboard and the window wasn't open. @{b}Version 2.2:@{ub} When copying a non-text clip from the clipboard to a file, then @{b}ClipHistory@{ub} would read innocent memory, and generate an incorrect (and often a very large) file. More tweeking of the @{b}ARexx@{ub} code. Made it somewhat smaller, and changed some other code to be more tolerant (e.g., stem base names no longer require a '.' char at the end. If not present, it will be added). Made a few minor fixes to the example @{b}ARexx@{ub}-script. Added scaled menu glyphs (OS 3.0+ only), based on source code from @{b}term@{ub}. Date in About requester localized. :) The @{b}ReqTools@{ub} file requester didn't open in the right drawer. @{b}Version 2.3:@{ub} @{b}ARexx@{ub}-commands that return information caused @{b}Enforcer@{ub} hits, if no @{i}STEM-@{ui}name was specified. Fixed another bug in the @{b}ARexx@{ub}-interface, that could cause incorrect returns. I'm not sure if it actually could happen with the current command set, but... ;) Recompiled with @{b}SAS/C@{ub} 6.56. Shaved off a few KBs. Alt-Return can be used to show the current clip in the GUI. @{b}ClipHistory@{ub} didn't make items visible properly on pre-OS 3.0 Amigas. The @{b}ARexx@{ub}-command @{b}PutText@{ub} didn't always return errors as it should. If @{b}MATCH@{ub} was specified, and a newly added clip was identical to the last, the last clip was either not activated, or it was deactivated. Now it is properly activated. Added some new options: @{b}CENTERMOUSE@{ub}, @{b}NORMALGLYPHS@{ub}, @{b}SCREENMENUFONT@{ub}. See @{"Options" Link "Options"} for more information. Added the @{b}STICKY@{ub} option to the Options @{"menu" Link "Menus"}. Stopped using @{b}TexInfo@{ub} for this manual. This means that the ASCII-version will no longer be included. Specifying @{b}PORTNAME=""@{ub} didn't stop @{b}ClipHistory@{ub} from creating an ARexx-port with the default name. NewIcons included. From various sources, with minor changes by me. Fixed some bugs in the cleanup code, that could cause problems if ClipHistory failed to start up properly. Cleaned up some code. @{b}Version 2.4:@{ub} Invalid clips (to be precise, clips with an odd "file" size) were saved into the history when they should be rejected. Also, they were saved in an incorrect state, causing problems when accessed later. Recompiled with @{b}SAS/C@{ub} 6.57. Added SAVEMODE switch to the @{"REQUESTFILE" Link "Requester commands"} @{b}ARexx@{ub} command. Included some more example @{b}ARexx@{ub} scripts, that actually can be useful, namely @{i}Dump.cliph @{ui}and @{i}Restore.cliph@{ui}. @{i}Dump.cliph @{ui}writes the contents of the history into a drawer (specified within the script), using the pattern @{i}ClipHistory.@{ui} (where is a decimal number). Any previous files with such a name will be deleted. @{i}Restore.cliph @{ui}can then be used to reload that saved history set (optionally replacing the previous history contents). Fixed an error in the documentation to the @{b}ARexx@{ub} command @{b}RequestNotify@{ub}. The return value is a warning (5) if "Cancel" was selected (and no GADGETS specified), and not the other way around. A couple of translations added and updated, done by ATO. @EndNode