The Fred Fish Collection 1.5

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

/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / txttools / magpages.lha / Magnetic_Pages.lha / Magnetic_Pages1.30 / Displayer / Displayer.docs < prev next >

Wrap

Text File | 1992-05-20 | 18.9 KB | 401 lines

M A G N E T I C P A G E S: Displayer (V1.30) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduction ~~~~~~~~~~~~ This is the program used to view a magazine. In addition to displaying the magazine, the reader may save text as a standard ascii file, save an entire page as an IFF picture, or print the text and/or graphics on a page. Running the Displayer ~~~~~~~~~~~~~~~~~~~~~ The Displayer can be run from the CLI or the Workbench. In addition to the actual magazine articles, the Displayer requires a special control file which contains information about the magazine contents. This control file is created using the Organiser and unless you have this program you can't make a magazine. Running from CLI: The displayer has one argument, the AmigaDos path/name of the control file. This control file may be called anything and located anywhere on the disk. eg. 1> Displayer My_Mag ^ ^ | | | Control file name | CLI prompt Note that you don't need to use the AmigaDOS RUN command. It will detach itself from the CLI automatically. Running from Workbench: To run the Displayer from Workbench, simply give your Control file a project icon and specify the Displayer as the 'Default Tool'. You can use icon supplied on this disk or make your own using IconEdit. You can have several different magazines on a disk, each with their own control file and icon. Memory Requirements ~~~~~~~~~~~~~~~~~~~ An optimum setup is an Amiga with 512k of Chip ram and 512k of Fast Ram. However it will run on all other configurations. It is up to the magazine editor to make sure that all articles can be displayed on a 512k machine. When an article is loaded, the Displayer will try and load it all into Fast ram. Then when a page is displayed, any graphics, sound or music needed for the page will be copied into Chip ram. As the graphics are copied to Chip Ram they will also be decompressed. If the Displayer is running on an Amiga with only chip ram, then all data must have been loaded into Chip Ram. This means it's not necessary to copy sound/music data from Fast Ram before playing it. If possible, two copies are still made on an all chip machine because when you move to another article you want any background sound/music to continue playing, and the original article containing the sound/music will be erased by the new article. If however there isn't enough ram for two copies of the data, the sound/music is played using the data contained in the article but when the reader loads in a new article, the sound/music will be stopped and the article erased. Using the Displayer ~~~~~~~~~~~~~~~~~~~ Moving around a magazine: The most basic operation is moving around the magazine. On a standard text page, you can use the menus or gadgets. On a custom graphics page you have to use the menu commands. The menu bar is hidden so it is important that people realise this is the only method of getting off a graphics page. The commands for moving around the magazine are as follows: Menu Gadget KeyBoard ~~~~ ~~~~~~ ~~~~~~~~ Next Page > Cursor Right - Takes you to the next page in an article. If you are on the last page of an article, you will be taken to the first page of the next article. Prev Page < Cursor Left - Takes you to the previous page in an article. If you are on the first page of an article, you will be taken to the last page of the previous article. 1st Page |< SHIFT + Cursor Left - Takes you to the 1st page of an article. If you are already on page one of an article or the article only contains one page, this command has no effect. Last Page >| SHIFT + Cursor Right -Takes you to the last page of an article. If you are already on the last page of an article or the article only contains one page, this command has no effect. Next Article >> Cursor Up - Takes you to the next article in the magazine. If you are at the last article of the magazine, you will be taken back to the first article. Prev Article << Cursor Down - Takes you to the previous article in the magazine. If you are on the first article of the magazine, you will be taken to the last article. Contents Contents Space Bar - This depends on the layout of the magazine and where you currently are. For example a magazine may be divided up into various sections. Eg Articles, Reviews, Feedback, Art Gallery, etc. There may also be a main contents page which has icons on it that allow you to branch to the different sections. Once you have branched to a section (eg articles) you should be able to get back to the main contents by selecting the Contents command. As well as moving through a magazine sequentially, a well designed magazine will be divided up into different sections, each with their own contents page. On a contents page, you can select an article to read, or branch to another section by clicking on icons (boxes) on the page. A box that can be clicked on will respond with a push-button effect or with several frames of animation. To get back to the previous contents page, select the 'Contents' command. Sound/Music: Some pages may play a piece of sound or music when you turn to them. This is nothing to be frightened about, it is perfectly normal. If it is a long piece of music or sound, or it has been told to repeat continuously it may not stop until you exit the magazine. You can turn the sound off yourself at any stage by toggling the menu item 'Sound On' in the 'Other' menu. Some pages may also have boxes on them which will play sound/music when you click on them. Sleep: Allows you to free almost all memory used by the magazine. A small window will be displayed in the top right corner of the Workbench screen. To return to the magazine click in this window once with the left mouse button and then once with the right button. Save as IFF: This menu command allows you to save one or several pages as IFF pictures. If you want to save off one page, simply enter the filename at the prompt. To save off a whole article, you use the same procedure. Each page will be saved as filename.PAGENUM, where filename is the AmigaDos path/name you entered at the prompt and PAGENUM is the page number. Only pages from the current page to the end of the article will be saved. For example if an article has 6 pages and you are on page 3 when you select 'Save as IFF', only pages 3,4,5 and 6 will be saved. Save Text: This menu command allows you to save a page of text or all the text from an article. The text will be saved as a standard ASCII file. Simply enter the filename at the prompt. Print: This menu command allows you to print a page, an article, a section or the whole magazine. There are two printing modes available. 'Text Only' will only print out the text on a page. 'Screen Dump' will print out the whole page as a graphics dump, similar to printing on Deluxe Paint. 2 Pages/Single Sheet - If this gadget is selected, 2 text pages will be printed on every sheet of paper. Otherwise every page will be printed on a new sheet of paper. This gadget has no effect when printing in the 'Screen Dump' mode. Note that when you are printing a whole article, section or the entire magazine, printing will always begin with the page you are currently on. This means that if you have to abort printing part way through, you can resume from where you left off. Text Search: This command allows you to search the magazine for a particular word or sentence. You can choose to search the current page, article, section or entire magazine. When you select this command a requester containing several gadgets will be displayed. Firstly enter the word or string of words you want to search for. The 'Case Sensitive' gadget allows you to distinguish between upper and lowercase characters. If this gadget is selected, the strings 'keeP Nz Nuclear free' and 'Keep NZ Nuclear Free' would not match. If 'Case Sensitive' is not selected the previous strings would match. When searching the magazine any multiple spaces encountered between words are removed. This is because the text in a magazine is often right-justified which causes extra spaces to be inserted between words. This means the strings 'Keep NZ Nuclear Free' and 'Keep NZ Nuclear Free' will match. Also any sentences that are split over 2 or more lines, text boxes or pages will be found. To begin a search click on the 'Find' gadget. Unlike the Print command searching will always start at the beginning of an article, section or magazine. If a match is found, the appropriate page will be displayed and the matching text will be highlighted. To continue searching for the next occurence of the string, click on the 'Next' gadget. When no more matches can be found, the message 'No Match Found' will be displayed. To search for a new string or to start searching from the beginning again, click on the 'Find' gadget. If you are searching a section or the whole magazine, you can abort the search by clicking on the 'Exit' gadget. Note that there may be a slight delay after clicking on 'Exit' and the current article will have to be reloaded. ----------------------------------- Customising the Displayer ~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to customise the Help File and all the menu, gadget and requester text used in the Displayer. This allows you to translate the text into your own language, should it be different from English. It also allows you to change the terminology used within the Displayer, should you be using Magnetic Pages for something other than a disk magazine. Help File ~~~~~~~~~ When you request Help from within the Displayer, it will load a special text file from disk and display it in the Help Window. You can customise this file to suit your own requirements using a text editor such as Az (my favourite!), Ed, MicroEmacs, or CED. The help file is called Displayer_Help. You cannot change its name and it must be in the same directory as the Displayer. The help window can display 38 columns and 20 rows. You can have up to 20 pages of help information. Within the Help text you can use the standard ANSI control codes to change the text style and colour. The following ANSI control codes are supported. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ESC [0m - Resets text to default colour and plain style ESC [3m - Italics On ESC [23m - Italics Off ESC [4m - Underline On ESC [24m - Underline Off ESC [1m - Boldface On ESC [22m - Boldface Off ESC [3nm - Set foreground colour (where n = 0 - 9) ESC [4nm - Set background colour (where n = 0 - 9) ESC [6"m - Shadow On { Note: Normal ANSI uses 6"Z ESC [5"m - Shadow Off and 5"Z for Shadow control. } ESC = Ascii code 27 and appears as an inverse left square bracket when using Workbench 1.3 or a small square when using Worbench 2. There should be no space between ESC and the [. In addition to the above escape sequences there are some special ones that I've defined to allow you to display the title bar gadgets in the Help text. This is so the user can see exactly what the gadget looks like that you are describing. The special codes are as follows: ESC [G0m - Display the 'Go to the first page of an article' gadget. ESC [G1m - Display the 'Go to the last page of an article' gadget. ESC [G2m - Display the 'Next article' gadget. ESC [G3m - Display the 'Next page' gadget. ESC [G4m - Display the 'Contents' gadget. ESC [G5m - Display the 'Previous page' gadget. ESC [G6m - Display the 'Previous article' gadget. Have a look at the standard Help file for an example of how to use the escape codes. Once you have set up the Help file as you want it, you can crunch it with PowerPacker to save disk space. Other Languages ~~~~~~~~~~~~~~~ It is possible to redefine all the text used in the Displayer program. The Displayer comes with English built in. When the Displayer starts up, it looks for a file called Displayer_Text. This file must be in the same directory as the Displayer and it cannot be renamed. If it finds this file it will use the text in it and automatically reformat all the menus, gadgets, and requester text. If it doesn't find this file, it defaults to English. The format of this file is quite simple. It is a plain text file, with each text string separated by a line feed. There is a sample file included on this disk called Displayer_Text.example. This is an English version of all the text used in the Displayer. You should edit this file with a text editor (translating the text into your own language) and then save it as Displayer_Text. Below I've listed this file and added comments to explain what the text is used for. Note that you cannot have comments in the real file. Project ; The Menu Text. These are in order from top left Sleep ; to bottom right. Save As IFF » Page... ; Save as IFF Sub Menu Article... Save Text » Page... ; Save Text Sub Menu Article... Print » Page... ; Print Sub Menu Article... Section... All... About... Quit Move To ; The Move To Menu starts here. Next Page Prev Page 1st Page Last Page Next Article Prev Article Contents Other ; The Other Menu starts here. Sound On Text Search » Page... ; Text Search Sub Menu. Article... Section... All... Help... CONTENTS ; This is for the CONTENTS Gadget in the titlebar. OK ; This is for the OK or confirmation gadget used in requesters. CANCEL ; This is for the CANCEL gadget used in requesters. CONTINUE ; This is used for the gadget in Error requesters. Find ; Icon in the Text Search requester. Next ; Icon in the Text Search requester. Prev ; Icon in the Help requester. Exit ; Icon in the Text Search and Help Requesters. Save Page as an IFF Picture. ; Title for the file requester. Save Article as IFF Pictures. ; Title for the file requester. Enter Filename: ; Used in the file requester. Save Page of Text. ; Title for the file requester. Save Article Text. ; Title for the file requester. Print Page ; Title for the print requester. Print Article ; Title for the print requester. Print Section ; Title for the print requester. Print All ; Title for the print requester. Text Only ; Used in the print requester. Graphic Dump ; Used in the print requester. 2 Pages/Single Sheet ; Used in the print requester. STOP PRINTING ; The icon used to abort a printing operation. Search Page ; Title for the Text Search requester. Search Article ; Title for the Text Search requester. Search Section ; Title for the Text Search requester. Search All ; Title for the Text Search requester. Case Sensitive ; Used in the Text Search requester. Enter a Search String ; Used in the Text Search requester. This version belongs to: ; Used in the small loading window. Usage: MP_Displayer [CONTROL FILE] ; The following are error messages. Unable to Load Control File Unable to Open Article Error Reading Article Out of Memory Error This Article has been Encrypted? File Loaded was not an Article Unable to Open File Error Writing File Unable to Open Page Error: Article not in List Can't Create Printer Request Can't Open Printer Device User Canceled Dump ; Printing Error. Not A Graphics Printer ; Printing Error. Wierd Printer Error ; Printing Error. Illegal Dimensions ; Printing Error. Wierd Printer Error ; Printing Error. No Memory For Variables ; Printing Error. No Memory For Buffer ; Printing Error. No Match Found ; Displayed when a Text Search finds nothing. Error Loading the Help File! The Displayer reformats all the Menus and Gadgets automatically, so you can make the text strings longer or shorter. Note however, if you make them too big then they may overrun some of the gadgets and windows. You have to take particular care when designing the menus. If you are going to use low resolution screens, make sure that the menus will fit on. A low res screen is half the width of the standard text screen. Finally once you've redefined the text and save it as Displayer_Text, you can save disk space by crunching the file with PowerPacker. Upgrades ~~~~~~~~ The Displayer is by no means perfect. I will continue to work on it when I get the time. I'm not promising anything but if enough interest is shown in Magnetic Pages, then there are many new features I'd like to add. If you have any suggestions, or complaints please let me know when you register. Mark Gladding.