@DATABASE "PPrefs 2.01 Guide" @WIDTH 80 @node MAIN "PPrefs 2.01 Guide" *************************************************************************** * * * @{b}PPrefs 2.01 Screen Promotion Utility@{ub} * * Freely distributable * * Copyright © 1993-95 The Naughty Bits * * * *************************************************************************** @{" Copyright " link copy} Distribution conditions @{" Overview " link intro} What is PPrefs @{" Requirements " link require} What is needed to run PPrefs @{" Installation " link install} How to install it @{" Prefs editor " link editor} How to edit the preferences @{" PPrefs itself " link prog} Function and options @{" Hints, suggestions, bug reports.. " link probs} @{" History " link hist} PPrefs' history @{" Acknowledgements " link thanks} Some persons I'd like to thank @{" The author " link author} How to contact me _________________ -------------------------------------- _________________ _\___\_o_/___/_ | | _\___\_|_/___/_ _\___(*)___/_ | Olaf "Oil Hog" Gschweng | _\___(|)___/_ / \ | gschweng@informatik.uni-rostock.de | / \ |---| | | |---| -------------------------------------- @endnode @node copy "Copyright notice" PPrefs is Copyright 1993-95 The Naughty Bits, All rights reserved. PPrefs is copyrighted freeware. The programs and files in this distribution may be freely distributed as long as no charge is made other than to cover time and copying costs. The files in this distribution must be kept together in original, unchanged form. The MagicWB-style icons are distributed with the friendly permission of Martin 'MagicWB' Huttenloher. If you want to include PPrefs as part of a commercial package you have to contact the author first. @endnode @node intro "Introduction" PPrefs is a screenmode promotion utiltity which allows you to promote every available screenmode of your system (including HAM and EHB modes) to another mode. You simply select a source and a destination mode and every program that wants to open a screen with the source mode, instead will open a screen with the destination mode. If you want that some very special programs get their very special screenmode or don't get promoted at all, besides that "mode to mode" promotion, PPrefs supports task/screen specific promotion, as well. Mode promotion could be useful in many circumstances: o You own an A4000 and a monitor which cannot display PAL and NTSC resolutions. Unfortunately some of your favourite programs don't allow you to select a screen mode and the system prmotion refuses to promote them to DblPAL or DblNTSC. o You like to use the Euro36 and Euro72 modes instead of PAL/NTSC because you like the higher refresh rates. o You own a graphics card and want your favourite program to open its screen on the card. Unfortunately the program doesn't allow the selection of a screen mode. Perhaps your card comes without a mode promoter, or you don't like the one supplied (like me). Maybe, the time comes where every program provides a screenmode requester - most new programs do so - but there are still lots of older programs which have not to be thrown away. Most could be promoted to other modes and some of them even make use of a bigger display. @endnode @node require "Requirements" PPrefs requires Kickstart 2.0, but should be more useful with Kick 3.x :) You should have asl.library, iffparse.library, mathieeedoubbas.library and mathieeedoubtrans.library in your LIBS: directory. If you use the catalogs you will of course also need locale.library. @endnode @node install "Installation" PPrefs consists of two programs. The program @{"PPrefs" link prog} itself is the promoter and patches the intuition.library/OpenScreen(), OpenScreenTagList() and QueryOverscan() functions. It is now (form version 2.0 on) WB-startable. To install PPrefs permanently you should put it in your WBStartup directory - but you can also put it anywhere else on your Workbench disk, or just put it on top of another thing - you know there are too many things not lying on top of other things.. (sorry, watched Pythons too much) To remove PPrefs, simply start it again and confirm the requester or send it a CTRL-C. The other program is the @{"preferences editor" link editor} of PPrefs which should be placed in the Prefs drawer of your WB disk. The GUI is localized, so if you have 2.1 or above, you can copy the appropriate catalog to your Workbench disk. Currently there are german, french and swedish catalogs available. @endnode @node editor "Edit your preferences" The Preferences Editor The 2 listview gadgets on the top left side allow the selection of the source and destination mode of a @{"mode promotion" link promote}, the button above them allows to @{"remove" link unpromote} these promotions. The pair of listboxes below shows shows various informations on the selected modes. The listview on the right side is for the define of @{"exceptions" link exceptions}. Below it there are some gadgets to set a few @{"options" link opts}. The modes are arranged in sublists for each monitor (ever tried clicking on the slider of the mode selector of DPaint 4.5?) To enter a sublist just click on the monitor name, to leave it click on the top item of the sublist. Note: If you have the OS3.0 standard mode promotion enabled (yes, the little gadget in IControl), then the promoted (i.e. scandoubled modes) appear in the Default: monitor's list. You should better disable it or you could get confused or get problems when you try to promote these modes. The 3 @{"bottom gadgets" link config} just work like those of the standard prefs programs and let you save, use or abandon the settings. The @{"menus" link menus} and @{"tooltypes" link options} are basically the standard preferences stuff, too. @endnode @node promote "How to promote" If you want to promote a mode, just single click on it on the source side so that its properties appear in the listview below. Then select the desired destination mode on the destination side (again a single click is enough) - that's all. If you click on a source mode that is already promoted, its destination mode will automatically appear on the right side; if it has not been promoted yet, the right side will show no selection. Note: The Kickstart 3.0 (i.e. GadTools V39) listviews highlight the selected entry rather than showing its name on the bottom of the gadget as they do under 2.0 - under 2.0 it could look a little confusing. If you have Kickstart 3.x, you will find a "Best xxxx mode" entry in the monitor list and in every mode list of the destination side. With it you can utilize the @{"Best mode promotion" link best} of PPrefs using the new BestModeID() function. @endnode @node unpromote "How to unpromote" To remove a promotion you have to click on the 'Unpromote' gadget above the mode listviews. Alternatively you can select the 'Unpromote' menuitem in the 'Edit' menu. There is also an item to remove all promotions and one to remove all promotions of a monitor. @endnode @node exceptions "Exceptions" If you want to exclude a particular program from the promotion or if you want its screen(s) to be promoted differently than the normal promotion - that's where the exceptions come into action. You can specify these screens by the screen title or by the name of the program that opens the screen. You can choose the appropriate list by clicking on the cycle gadget below the listview. To add an entry click on the 'Add' gadget and then enter the desired name. (The new entry will be inserted above the currently selected entry or on the bottom if no entry is selected.) The program will now get exactly the mode it wanted whether there is a promotion for that mode or not. The names can contain wildcards and are case insensitive. If you want to give a program a particular screen mode just select its entry in one of the exception lists and then select the desired mode in the destination listview. @endnode @node opts "Options" Under pre-AA chipsets the number of colors a mode is able to display, varies. So if you want to promote a mode to another one that only can display less colors than the original mode, it can happen that a program cannot get the number of colors it wants to get. For this case you can specify (separately for each promotion and exception) what should be done here by choosing between keeping the resolution or keeping the colors. The default is to keep the resolution, so the program gets the mode you wanted it to get, but only as many colors as possible. This may have the effect that you can't see everything you should - perhaps you should then better use the other option: to keep the colors and to reduce the resolution of that screen. In this case PPrefs will activate autoscroll (if needed) so you can shift the visible area to see the whole screen. See the @{"Best mode promotion" link best} section for the rest of the options. @endnode @node best "Promote to the best suitable mode" Under Kick 3.0 (or above:) you will find a "Best xxxx mode" entry in the monitor list and in every mode list (on the destination side). This lets PPrefs use the new BestModeID() function to determine a suitable display mode. If you select the global entry then the mode is searched in the whole display database. It could take a noticable amount of time before the screen is opened, depending on the speed and the number of screenmodes of your system. If you selected the entry in one of the mode lists the returned display mode will use the monitor of the selected entry. It seems that the BestModeID() function is hungry for stack, especially if you have some more monitor drivers installed (often on AGA-machines). To ensure sufficient stack space for BestModeID, PPrefs checks for a minimum of available stack memory and swaps the stack if needed. You can adjust the minimum with the Tooltype/CLI option @{b}MINSTACK@{ub}. There are 4 checkboxes to give you the possibility to influence the selection of the best mode: Source mode - this lets PPrefs pass the source mode ID to BestModeID() so that it can take care about a proper aspect ratio and some special properties like HAM etc. Dimensions - this passes the width and height of the requested screen to BestModeID() to ensure that the screen could be displayed entirely using the desired mode. Aspect ratio - this overrides the aspect ratio of the source mode and uses the width and height of the screen to determine the desired aspect ratio. No lace - this restricts the search to modes without interlace. @{b}However, the BestModeID() function has some peculiarities, so you should restrict the use of the best mode promotion to the exceptions. For regular mode to mode promotion it should be better to select a real destination mode.@{b} @endnode @node config "Configuration" If you quit the editor via the 'Use' gadget the configuration will be saved to ENV:promotion.prefs. You can edit your prefs even if PPrefs is not currently running. If you 'Save' the prefs, they will also be written to ENVARC: so they'll survive the next reset. If PPrefs is currently running it will immediately use the new configuration. @endnode @node menus "Non-standard PPrefs menus" @{b}Unpromote@{ub} - does the same as the corresponding button @{b}Unpromote monitor@{ub} - deletes all promotion entries of the currently selected source monitor @{b}Unpromote all@{ub} - deletes all promotions (both regular entries and exceptions) @{b}Loadmode@{ub} - select the @{"loadmode" link loadmodes} @endnode @node loadmodes "The new file format and loadmodes" PPrefs 2.0 introduces a new prefs file format. Now it does not only save the mode IDs but also their names. This is useful for graphicboards where the IDs are changing from revision to revision or could be changed by defining new modes with the included software (both being the case for the PicassoII). However, only the prefs editor can make use of this feature - the promoter always uses the IDs, not the names. There are 2 loadmodes available for the editor - one uses the modeIDs, the other uses the modenames to build up the promotion database. To switch between them use the Loadmode menu item or set the MODE tooltype to NAME or ID. If you know that some modes got different IDs, start the editor - be sure to set the loadmode to names or you will lose all promotions with these modes without warning! If the loadmode is set to IDs, toggle it and use the "Edit/Restore" menuitem to reload the prefs file. Have a look if now everything is like it should be, then quit with the "Save" gadget. PPrefs 2.0 can still read the old file format but only saves the new one. In a next version this might change, so better save your prefs now. Note: As the saved names are not the normal modenames but those built up by the editor (displayed in the modelists), this feature works also for modes that normally don't have a name. @endnode @node options "The editor's options" Supported tooltypes: @{b}CREATEICONS@{ub} @{b}PUBSCREEN@{ub} @{b}MODE@{ub} - Set the @{"loadmode" link loadmodes} to NAME or ID. @{b}LANGUAGE@{ub} - Select the language of the user interface. For preset files the tooltypes @{b}SAVE@{ub} and @{b}USE@{ub} are supported. For commandline usage: "FROM,EDIT/S,SAVE/S,USE/S,PUBSCREEN/K,MODE/K" @endnode @node prog "PPrefs" The PPrefs program patches the OpenScreen and OpenScreenTagList functions of intuition.library, in such a way that OpenScreen is completely replaced by OpenScreenTagList. Since version 2.0 it also patches the QueryOverscan() funtion to ensure that programs that check the size of overscan regions before they open a screen get the those regions of the promoted modes. However, this works only for mode to mode promotion and for exceptions specified by tasknames. As QueryOverscan obviously doesn't supply a screenname PPrefs couldn't check for it and so could promote it differently as when opening a screen with the same source mode. PPrefs looks for a promotion entry in the screenlist, the tasklist and the normal promotion array (in that order). If it finds one, it searches for an appropriate overscan region, checks if it fits entirely on the screen, and if not, enables AutoScroll. It then will center the screen or at least look if the left/top coordinates don't exceed the overscan region. PPrefs has some options which could be given on the commandline or as Workbench tooltypes: @{b}NEWLOOK@{ub} Enable newlook for promoted screens. @{b}NOCENTER@{ub} Don't try to center the screen. @{b}STDOSCAN@{ub} Adjust overscan only up to standard (graphics) overscan which is editable via Preferences. The default is maximum overscan which is not editable but fixed. @{b}MINSTACK@{ub} Set the minimum size of available stack for use with best mode promotion. @endnode @node probs "Problems" I cannot have all the programs you may have and so cannot test PPrefs with every program available for the Amiga. Of course I tested it with the programs I use and some problems that I could not imagine appeared with some of them and I changed PPrefs to work with those programs. So if your favourite program does not work well with PPrefs - I cannot do anything to fix this if I don't know about it - you have to tell me! I have included a special version of PPrefs called PPrefsDBug that prints a few informations when a screen is opened. To use it, you should abort the normal PPrefs program and start PPrefsDBug. When you have a program that makes problems with PPrefs you should @{"send me" link author} the output that PPrefsDBug makes. You could also use it to determine the modeIDs and screen/task names of the screens. I had some replies from people using PPrefs with their AGA-machines but I also like to hear if anyone succesfully uses PPrefs with the Spectrum or some other graphicboards. @endnode @node thanks "Thanks" I'd like to thank: Matt Dillon for his DICE system Sylvain Rougier and Pierre Carette for their fantastic BrowserII Dirk "Max" Moritz for his CD-ROM drive :) especially Torsten "Tigy" Gebert for his original 'all to VGA'-patch, for the stack swapping code and for testing PPrefs and all persons who sent reports and suggestions A special thank goes to the translators: Sylvain Rougier (french) Martin Henkel (swedish) @endnode @node hist "History" I wrote PPrefs because all the other promotion utilties I tried and used didn't offer the features I wanted. After trying several of them I used ForceMonitor but I was not fully satisfied with it. After I bought my PicassoII gfx card, I needed a good promotion utility even more because I don't like that ChangeScreen utility included with the Picasso so much. Tigy had an A2000 and a VGA monitor without a flickerfixer some time. Therefore he wrote a little patch which worked quite well but it offered no oppurtunities to edit - it just promoted everything to VGA. So I wanted to build an editor for it and he should change his patch so that they work together. But as we didn't see for quite a time I did the patch myself. (actually I was just wondering if it is possible to do that beast in C:) @{b}1.0 (06.09.93)@{ub} o Initial release. @{b}1.0a (13.09.93)@{ub} (not released) o Added screen centering. o Does not use any global data for the taglist extension anymore. @{b}1.1 (26.10.93)@{ub} o Redesigned GUI and the font-sensitive code. o Added "Best mode" promotion. o Gets name of CLI started programs from process. o Added semaphore protection. o Reworked screen centering, left/top adjust and overscan handling. @{b}2.0 (04.10.94)@{ub} o Editor now understands commandline options. o Modelists display full modenames. o New prefs file format includes modenames. o Some minor changes in the GUI layout. o Gives some more error messages. o PPrefs is now WB-startable and could be removed from editor. o Now also patches QueryOverscan(). o Refuses to remove if another program patched one of the functions or if one of them is currently active. o Added stackswapping for BestModeID() function. (swap.o was done by @{b}Tigy@{ub} - who is a naughty bit, indeed) @{b}2.01 (03.01.95)@{ub} o removed a bug that caused enforcer hits when reading the prefs file. (thanks to Peter Marquardt for reporting) o there is still a bug with CED 3.5 - GetProgramName() causes an enforcerhit - no idea how to fix this o the requesters now block the main window and show busypointers @endnode @node author "Contact me" If you have problems, suggestions,etc., I can be reached via EMail (preferred) : @{b}gschweng@informatik.uni-rostock.de@{ub} or via snail mail: Olaf Gschweng Riefstahlstr. 33 17235 Neustrelitz Germany The stack swapping code was done by Torsten "Tigy" Gebert, who could be reached at: @{b}gebert@informatik.uni-rostock.de@{ub} This could very likely be the final release of PPrefs. As I use more and more time with my new PC running Linux, I have less time to play around with my good old Amiga. (But the babe is still on my desk and will stay there.) @endnode