@DATABASE SuperView.guide @WIDTH 80 ## $VER: SuperView.guide V2.5 (28.5.94) ## ## For reading this file you may use : ## ## Program-Name available at ## ## - ShowHyp (e.g. coming with GadToolsBox V2.0c) ## - Hyper (AmigaLibDisks) ## - AmigaGuide (various Packages) ## - MultiView (Workbench) ## @NODE MAIN "SuperView_Documentation" SuperView V2.5 (28.5.1994) - SHAREWARE - © 1993-94 by Andreas Ralph Kleinert Grube Hohe Grethe 23 D-57074 Siegen Germany email : --- All rights reserved. Needs Kickstart V2.04. Kickstart release 3.00 compatible. GUI created under use of GadToolsBox V2.0c. @{"The program's purpose" LINK Purpose} @{"About the program's abilities" LINK Abilities} @{"How to install it" LINK Installation} @{"How to use it" LINK Usage} @{"Known bugs and program limits" LINK Bugs} @{"Program history" LINK History} @{"Possible future enhancements" LINK Future} @{"Where to send bug-reports and donations" LINK Correspondence} @{"DISTRIBUTION LIMITATIONS" LINK Distribution} @{"Copyrights" LINK Copyrights} _ _ // Only \X/ Amiga makes it possible. @ENDNODE @NODE "Purpose" SuperView in its current phase of development is a program, which has mainly three purposes : - Displaying of various Graphic File Formats, e.g. IFF-ILBM, IFF-ACBM, PCX, GIF, BMP, FBM, TIFF, WPG, IMG, C64 and SVO ! - Writing/Conversion of most of these Graphic File Formats - "Screen-Grabbing", which means saving Screens in most of these Graphic File Formats All this under usage of internal and external Graphic- and GraphicCard-Drivers. More about the program's abilities can be found in the specific chapters. @ENDNODE @NODE "Abilities" SuperView is a program that has been designed for the purpose, to display any kind of graphic as fast and as comfortable as possible. Fast means not only fast in reading and displaying but also in calling and using the program. Highest possible flexibility is implemented via the external Driver-System, consisting of the superview.library, the "svobjects" and the "svdrivers". This allows at the time for example support of IFF-ILBM, IFF-ACBM, PCX, GIF, BMP and SVO. These intentions resulted in a bundle of features and options you have access to when using SuperView and installing it to your System : - own "superview.library" (supplied in separate archive) - intensive use of many special OS V2.04+ and OS V2.1+ capabilities - support of many OS V3.00+ and AGA graphics features, as e.g. support of interleaved BitMaps - support of external Viewer-Libraries (svobjects), for e.g. IFF-ILBM, IFF-ACBM, PCX, GIF, BMP, FBM, TIFF, WPG, IMG, C64 and SVO ! - support of external GraphicCard-Drivers (svdrivers), e.g. for : ECS, AGA, EGS-Cards - support of OS V3.00+ DataTypes for displaying of graphics - "Screen-Grabbing" - Commodity (optional) - ARexx-Port (optional) - AppIcon (optional) - AppMenu (optional) - AppWindow (optional) - Clipboard reading and writing - Localization for OS V2.1+ - AmigaGuide OnLine-Help for OS V2.1+ - detailed configuration via Config-File, Cli-Options and Workbench-Tooltypes - Graphical User Interface (GUI) for Workbench-Users (optional) - conversion of the supported File-Formats - information about the displayed graphics via Requester, selectable via GUI-Menu - and more And via ILBM.svobject and ACBM.svobject : - use of "iffparse.library" for reading and writing - reading and writing of extended CAMGs (OS V2.04+) and 24 Bit CMAPs (OS V3.00+, AGA) - intelligent CAMG-Chunk replacement routine - and more @ENDNODE @NODE "Installation" Even if you use the supplied Installer-Script, you should read the following notes. If you do not own the standard Installer-Program you should read them even more carefully and follow the instructions given. The superview.library has to be installed seperately, anyway ! Needed Workbench Resources HardDisk-Users won't perhaps have to install any additional Workbench Resources to their HardDisk. Disk-Users will have to copy the following libraries into their "LIBS:"-Directory : - gadtools.library V37+ - iffparse.library V37+ - asl.library V37+ - commodities.library V37+ - utility.library V37+ - workbench.library V37+ - icon.library V37+ Users of OS V2.1 or greater should also install the following libraries : - amigaguide.library V38+ - locale.library V38+ Other needed Resources You will have to copy the following library into your "LIBS:"-Directory : - superview.library V3+ Installing the Main Program Copying SuperView to your "WBStartup"-Drawer would be perhaps the best solution, but installing it in any other directory will suffice anyway. You should also install an appropriate Config-File in one of the supported paths (e.g. "ENV:" or "S:"). @ENDNODE @NODE "Usage" How To Use SuperView : An Introduction @{"1.0 SuperView's Construction" LINK Construction} 1.0.1 The Workbench Interface 1.0.2 The Graphical User Interface (GUI) 1.0.3 The CLI Interface 1.0.4 The Commodity Support 1.0.5 The ARexx-Port 1.0.6 The App-Features 1.0.7 Configuration Commands @{"2.0 Controlling And Using SuperView" LINK Control} 2.0.1 Options for Configuration and ARexx 2.0.2 GUI and WB-App Handling 2.0.3 Controlling the Display-Screen @{"3.0 Information about the supported Gfx Formats" LINK Gfx-Formats} 3.0.1 IFF-ILBM 3.0.2 IFF-ACBM 3.0.3 Other File Formats @ENDNODE @NODE "Construction" 1.0 SuperView's Construction SuperView bases on several interfaces, of which almost any can be activated/deactivated and accessed separately. These are : - The Workbench Interface - The Graphical User Interface (GUI) - The CLI Interface - The Commodity Support - The ARexx-Port - The App-Features - Configuration Commands 1.0.1 The Workench Interface The Workbench interface is just a standard WB-Interface, which means that it supports sevaral Tooltypes for program configuration, of which nearly any are also available via ARexx and the ConfigFile. It is supported to use SuperView as a DefaultTool for Project Icons via the Workbench "Information" Menu as well as displaying pictures via "multiple selection" as described in the Workbench manual. See 2.0.1 for more details on configuration. 1.0.2 The Graphical User Interface (GUI) As many other programs SuperView gives the user the possibility to control most activities via a Graphical User Interface, based on the standard Intuition elements as Gadgets, Menus and Windows. SuperView's GUI allows to reach nearly all of the program's features and also provides even more of them. This GUI is not opened automatically, because SuperView is also designed to run as a Commodity in the Background (see 1.0.4), where a GUI often is not actually needed. The GUI may be activated via Configuration options (see 2.0.1), which either have to be placed in the Config-File, as Icon- Tooltypes or as CommandLine-Options (see 1.0.3). When running SuperView as a Commodity the GUI can also be opened via the standard WB-Program "Commodity Exchange" (see 1.0.4). If an AppIcon or AppMenu is installed, it also will let the GUI pop up (see 1.0.6). 1.0.3 The CLI Interface The CLI Interface provides nearly all possibilies as the GUI does (except Screen Saving/Gfx Converting), so that CLI users are completely integrated into the program's idea of concept. Allowed configuration options can be parsed via CommandLine by simply adding an "-" to their front (see 2.0.1). 1.0.4 The Commodity Support Only one of the currently running copies of SuperView at a time has the possibility to install itself as a Commodity which can be controlled via the standard WB-Program "Commodity Exchange". Special options (see 2.0.1) allow to set the HotKey, the Priority and can specify, if the GUI should pop up or not. Via the HotKey (default : alt esc) SuperView is present everywhere it is needed and even the GUI can appear anywhere as fast as possible, because of the "Commodity Exchange", which allows it to pop up just by pressing the specific button there. 1.0.5 The ARexx-Port The ARexx-Port is another feature, which strenghtens the interactive capabilities of SuperView, because it allows to contact the SuperView Process from nearly anywhere at nearly any time to tell it to do a specific task. Most of the ARexx-Commands are also available as configuration options, so they are described there (see 2.0.6). The name of the ARexx-Port is "SuperView.rx". Only one SuperView Process will own such a port at a time. 1.0.6 The App-Features Another interactive feature of SuperView allows you to install an AppIcon, AppMenu and/or AppWindow. All these are each optionally. The AppIcon is placed on the Workbench and allows direct activation of SuperView, as via ARexx or "Commodity Exchange" (Requester). The AppMenu just works like the AppIcon. The AppWindow only takes place, when the GUI is opened, so that any pictures of which you drop an Icon into the GUI Window will be displayed immediately. 1.0.7 Configuration Commands Because of those many options and features is has perhaps to be explained which order takes place when configuring the program at startup time or later. Here's a table : - Default Options (integrated in SuperView) - ConfigFile (read from Disk, if available) - a) Tooltypes (read from Icon(s) at WB-Start) b) CLI-Options (supplied via CommandLine at CLI-Start) - ARexx-Command (received while the program is running) @ENDNODE @NODE "Control" 2.0 Controlling And Using SuperView As described before, SuperView can either be controlled via Workbench, CLI, "Commodity Exchange", ARexx or its GUI. The Commands, which are available for configuration and interactive ARexx use follow (2.0.1). After that the handling of the GUI is described more detailed (2.0.1). 2.0.1 Options for Configuration and ARexx The letter after the specific command tells you from where it can be reached : C [ Config-File ] T [ Workbench-Tooltypes, CLI-CommandLine] A [ ARexx ] Command Function Usage QUIT Leave SuperView [ A ] HELP Load AmigaGuide DataBase [ C T A ] REQUEST Request for displaying a Gfx [ C T A ] SHOW= Display a specific Gfx [ C T A ] UNSHOW End Displaying / Close Display [ A ] SAVE_ILBM0= Save current Gfx as IFF-ILBM [ A ] SAVE_ILBM1= (dito, as packed IFF-ILBM) [ A ] SAVE_ACBM= (dito, as IFF-ACBM) [ A ] OPTION_LOAD= Disk or ClipBoard loading ? [ C T A ] OPTION_SAVE= Disk or ClipBoard saving ? [ C T A ] ERROR_REPORT= Report Errors ? Or be quiet ? [ C T A ] INSTALL_CX= Install as a Commodity ? [ C T ] INSTALL_AREXX= Provide an ARexx-Port ? [ C T ] INSTALL_APPWINDOW= Provide an AppWindow ? [ C T A ] (only together with OPEN_GUI or CX_POPUP=YES) INSTALL_APPICON= Provide an AppIcon ? [ C T ] INSTALL_APPMENU= Provide an AppMenu ? [ C T ] OPEN_GUI Open the GUI immediately [ C T A ] CLOSE_GUI Close the GUI immediately [ A ] CX_POPKEY= Standard CX_POPKEY command, [ C T ] with ony difference : "+" is needed between keys instead of blank (" ") CX_POPUP= Standard CX_POPUP command. [ C T ] CX_POPUP=YES is equivalent to OPEN_GUI. CX_PRIORITY=<-128..127> Set Priority of SuperView [ C T A ] Process and the Commodity Broker. If called via ARexx only the process priority is set new. The name of the ARexx-Port is "SuperView.rx" (only one is possible at the same time). 2.0.2 GUI and WB-App Handling The GUI mainly consists of three regions which are marked by the specific gadgets with the same name : @{"Load and Display" LINK GADGET_Load_and_Display} @{"Load and Convert to" LINK GADGET_Load_and_Convert_to} @{"Save Screen as" LINK GADGET_Save_Screen_as} More options are available via the "Project" Menu, where you can select between the following actions : @{"FileInfo" LINK MENU_FileInfo} @{"Help" LINK MENU_Help} @{"About" LINK MENU_About} @{"Quit" LINK MENU_Quit} In the "Options" Menu it can be chosen, whether loading ("Load medium") or saving ("Save medium") should be done via conventional disk operations or via clipboard access. If disk access is selected, a FileRequester will appear before loading and saving anything, otherwise just the first clipboard unit will be used. More about clipboard use can be found in your computer's manual perhaps. By pressing HELP while selecting a Menu, or by selecting a Gadget after turning on the Gadget-Help via pressing HELP you may enter the context-sensitive documentation. 2.0.3 Controlling the Display-Screen SuperView opens for each graphic, which has to be displayed, a suitable Screen. This Screen and the attached Window are usually pushed to the Foreground automatically und become activated, just right after the graphic has been loaded. After that you have the possibility, to control the program's behaviour via the following actions : Mouse control : - left Button quits the display - left Button below the graphic, while moving the mouse simultaneously scrolls the graphic : ONLY WITH OS V3.00+ DataTypes (see relating note in the Screen-Titlebar) Keypad control : - Key "L" : Load new graphic - Key "Q" : Quit display - Key "X" : Quit display and leave program - Key "H" : Open GUI (GUI-Screen still in Background) - HELP-Key : Open GUI (GUI-Screen still in Background) - ESC-Key : Quit display and leave program (keep it pressed about 1-2 seconds) @ENDNODE @NODE "Gfx-Formats" 3.0 Information about the supported Gfx Formats 3.0.1 IFF-ILBM IFF-ILBM is the standard Gfx FileFormat for the Amiga. Currently there do exist two versions of this Format : - IFF-ILBM, unpacked - IFF-ILBM, CmpByteRun encoded The difference is, that the second one contains data, which is encoded with the CmpByteRun method, while the data of the first is unencoded. The reason, why both methods are included, is that sometimes it may be more efficient to let the IFF-ILBM file unpacked and then pack it with an other packer instead encoding it with CmpByteRun. Also there may exist some older - actually VERY old - programs, which do not support the packed format. IFF-ILBM graphics may contain Amiga-specific color cycling (CRNG) and ViewMode (CAMG) information. 3.0.2 IFF-ACBM IFF-ACBM is the standard Gfx FileFormat for AmigaBASIC. Currently there only does exist one version of this Format : - IFF-ACBM, unpacked The reason, why the data is unpacked is nearly the same, why IFF-ILBM is not used here : From Basic programmes it is not easy to read packed data anyway and it would slow down the program enormously. Data in an IFF-ACBM is saved BitPlane for BitPlane, to increase the speed of reading. If you use an automatically packing FileSystem or a patched DOS it might be useful to use IFF-ACBM, because the speed of displaying pictures dos not increase only with AmigaBASIC programs, but also with SuperView. And if you use such a method of background packing you will not even need more HardDisk space, which is in fact needed if converting from IFF-ILBM (CmpByteRun) to IFF-ACBM. On the other hand needed space is nearly the same as for unpacked IFF-ILBM graphics - but the speed is higher. 3.0.3 Other File Formats Library-Versions above V2 of the "superview.library" support displaying via SuperViewObjects (SVObjects), which are placed as external drivers inside "LIBS:svobjects/". Nevertheless you may also make use of OS V3.00+ DataTypes. Just select, which one you want to have installed, but please note, that SVObjects will cooperate much more better to superview.library. @ENDNODE @NODE "MENU_FileInfo" - FileInfo Gives information about the currently loaded Gfx, as width, height or color-depth. @ENDNODE @NODE "MENU_Help" - Help Starts this Online-Help. @ENDNODE @NODE "MENU_About" - About Informs about SuperView. @ENDNODE @NODE "MENU_Quit" - Quit Closes the GUI of SuperView (which not necessarily means to quit SuperView itself). @ENDNODE @NODE GADGET_Load_and_Display - Load and Display When clicking on this gadget, a FileRequester will appear and the selected picture - if of a known File-Type - will be displayed immediately and perhaps replace the old display. @ENDNODE @NODE GADGET_Load_and_Convert_to - Load and Convert to Load and Convert begins like "Load and Display", but after loading the picture it will be converted to the FileType selected by the MX-Gadget at the right side. An other FileRequester appears to enter the name of the converted file. @ENDNODE @NODE GADGET_Save_Screen_as - Save Screen as This option allows to save any of the currently opened screens as on of the formats which are selectable with the MX-Gadget on the right side. If the list of selectable Screens is not up-to-date an update can be forced by pressing the "*"-Gadget beside the ListView. The "i"-Gadget presents various information on the currently selected Screen. @ENDNODE @NODE "Bugs" Known Bugs and program limits : - When trying to create some kind of a "slide show", you have to decide how long the user should see a picture displayed, because a mouse click by the user will end displaying as well as sending an ARexx/Commodity/Tooltype command to SuperView, which immediately will cause it to display the new picture. This is not a real bug, this is just because of interactive message receiving while a picture is displayed. Multiple picture displaying is only possible when starting different SuperView Tasks, which then all have to be "quit"ted by a mouse click. - Another point is, that only one currently running SuperView Task can be reached interactively via ARexxPort and Commodity Exchange. This lies in the nature of SuperView and Commodity Exchange. Nevertheless multiple AppIcons and AppMenus - as well as their corresponding tasks - are possible, so do not forget to disable this feature if you don't want to get a Workbench full of SuperView-Icons ... @ENDNODE @NODE "History" The SuperView ILBM-Viewer bases on my older program project "KILBM", which has been designed for usage under older versions of the Amiga OS. SuperView is _not_ related to the program with the same name from AmigaLib Disk 367, about which I read _after_ programming it. V2.5 : - we no longer use fscanf/fprintf for ConfigFile reading, but FGets/VFPrintf of Dos V37+ instead now : this saves about 6900 Bytes Codesize and is as effective as before ! - fixed History : superview.library V3.9 was released as V4.1 - supports direct writing of GfxBuffers with superview.library V6+ (a buffer-Screen is no longer needed). Includes fall-back option for versions below V6 or SVObjects without GfxBuffer-Support. Conversion of large pictures will now be possible with less memory usage in most cases. V2.4 : - use of SAS/C V6.51 - now again supporting amigaguide.library V38 (own risk) - changed/updated documentation - AmigaGuide stuff might not have been closed/removed - removed memory management routines : if needed, we will take them from superviewsupport.library (introduced with superview.library V3.8) - OS version is checked earlier now (>= V37) - the AppIcon now also accepts dropping Icons of Pictures on it, as one would expect (mentioned by Gerd Frank) - SuperView no longer crashes, when started with question mark ("?") from CLI/Shell - removed "anchor window" for the FileRequester - ClipBoard feature did not work with superview.library releases V2.4 to V3.8. You must use V4+ (and the bug-fixed SVObjects) for enabling this again. This was not a bug of SuperView. V2.3 : - SuperView crashed without locale.library, although it shouldn't have been able to do so. (fixed as a result of former bug-reports by Gerd Frank, see amigaguide-fixed in V2.1 and V2.2) - fixed bug in handling underscored Gadgets - added Underscore to "*"-Gadget - added possibility to get information on Screens ("i"-Gadget) (mentioned by Gerd Frank) - completely reworked internal ScreenList creation and handling (also reported by Gerd Frank). Besides, this saves some memory and diskspace. V2.2 : - fixed bug (Guru), which occured, when selecting Help-Menu, while amigaguide-Library V39+ was not available. (mentioned by Gerd Frank) - new "Exit"-Menu, which leaves the program - other than "Quit" completely (mentioned by Gerd Frank) V2.1 : - now under OS V3.00+ the Busy-Pointer is set while calling superview.library - fixed bug (Guru), which occured when calling HELP while amigaguide- Library V39+ was not available (mentioned by Gerd Frank) - accidentally asked for amigaguide.library V38+ instead V39+ - added support for "ESC"aping and "HELP"ing while displaying V2.0 : - needs superview.library V3+ with SVDriver-Support - fixed small bug in memory management routines - localization of program texts (except GUI) for OS V2.1+ - now uppercase (shifted) keys accepted on the Display-Screen - each written PicFile now becomes its own Icon - fixed possible ChipMem-problem with AppIcon-Data V1.4 : - complete recompilation under use of SAS/C V6.5 - fixed bug with wrong SaveType (ILBM1 instead of ILBM0, or totally wrong, if ILBM not installed) - fixed bug in memory usage (not freed) - some improvements and bug-fixes V1.3: - new Library with DataTypes-Support - make use of the new concept of external Viewer-Libraries (svobjects) of superview.library V2+ V1.01 : - forgot to mask BADFLAGS out in CAMG-Write-Routine - BitMap-Height and -Depth is under V39+ now checked via GetBitMapAttr() - improved BODY and ABIT size calculation - own "superview.library" V1+ - and many more improvements - forgot GadToolsBox-Note (Sorry, Jan van den Baard !) V1.00 : first version. @ENDNODE @NODE "Future" Possible future enhancements might be : - a better and more ergonomic GUI - an improved ARexx-Port - better AppIcon-Handling - and more @ENDNODE @NODE "Correspondence" Send donations, bug reports, ideas, etc. to the following address : Andreas R. Kleinert Grube Hohe Grethe 23 D-57074 Siegen Germany For _urgent_ calls : Phone : +49/271/332147 (weekdays later than 18.00h) When reporting any bugs, please don't forget to include a detailed description of the bug and tell me, if it is reproduceable or not. Also mention the version number of SuperView you used and describe your system configuration (Amiga model 500/1000/.../4000-040, Kickstart/OS, RAM, HardDisk, special configurations). If you want to get a newer - and maybe debugged - version of SuperView do not forget to register as an authorized user of SuperView with the included registration form. Nevertheless unregistered users are as welcome to report bugs as users who decide(d) to register. @ENDNODE @NODE "Distribution" Copyright The program SuperView V2.1 and its documentation files are (C)opyright 1993-94 by Andreas R. Kleinert. All rights reserved. The right of using this program is granted to you by paying the SHAREWARE-fee of 30,- DM to the author. Disclaimer The author takes no responsibility for any results of the use of this program. This software is provided "AS IS" and there is no warranty of any kind, so that you use this software at your own risk. Rights Registered users which paid the SHAREWARE-fee get the rights described on the registration form. Distribution The program SuperView V2.1 is freely distributable (SHAREWARE). You may copy it, if the copyright notice is left intact and all of its parts are included in the distribution. This program must not be included in commercial packages or commercial program collections without my written permission. This program must not be sold in any way, but it is allowed to take a nominal fee including the costs for copying. This program may be put on public domain disks or included in public domain disk libraries. Special permission hereby goes to Fred Fish's AmigaLib-Disks and the german series (in alphabetical order) : AmigaSzene, BerndsPD, FRANZ, GPD, TAIFUN and TIME. This program may also be distributed via electronic mail and may be put into mailboxes as long as the redistribution conditions are respected in all points. By using or distributing this program you automatically agree to all of the above conditions and terms. @ENDNODE @NODE "Copyrights" Copyrights Some of the mentioned names or products above may be copyrighted by companies or trademarks of companies. @ENDNODE @ENDNODE