Amiga Elysian Archive

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

/ Amiga Elysian Archive / AmigaElysianArchive.iso / screen / promo106.lha / Promotor / Promotor.doc < prev next >

Wrap

Text File | 1993-05-31 | 33KB | 911 lines

THE _______ _______ _____ ____ ____ _____ ________ _____ _______ ________ ________ _______ _____ _____ _______ ________ _______ ________ __ __ __ __ __ __ _________ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ ___ __ __ __ __ __ __ __ __ _______ _______ __ __ __ _ __ __ __ __ __ __ _______ ______ ______ __ __ __ __ __ __ __ __ __ ______ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ ____ ____ ____ _______ ____ ____ _______ ____ _______ ____ ____ ____ ____ ____ _____ ____ ____ _____ ____ _____ ____ ____ DESIGNED AND WRITTEN BY KURT HAENEN __ __ ______ ________ _______ ______ __ __ _______ ________ ________ _______ __ __ __ __ __ __ __ __ __ __ __ __ __ __ _ __ __ __ __ __ ______ ____ _______ ______ __ __ ______ ____ ______ ______ __ __ __ __ _ __ __ __ __ __ __ __ __ __ __ __ __ __ _______ _______ ________ ____ ____ _______ _____ ______ ________ ____ ____ ______ ____ ____ _____ ___ ____ __ __ _____ ____ _____ _____ _______ ____ ____ __ __ _______ ____ _________ __ __ ____ __ __ __ __ __ __ __ ___ __ __ __ _____ __ __ __ __ __ __ __ _ __ _______ __ _____ __ __ _______ __ __ __ _______ __ ____ __ __ _______ __ __ __ __ __ __ ___ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ ____ ____ ____ ____ ____ ____ _______ ____ ____ ________ ____ ____ ____ ____ ____ ____ _____ ____ ____ ________ - The Promotor Users Manual - - Table of Contents - TABLE OF CONTENTS 1.Introduction ......................................................... 2 2.Installation ......................................................... 2 3.The Configuration File ............................................... 3 4.The ToolTypes or Command-Line Options ................................ 8 5.The Users-Interface ...................................................9 Appendix A : How To Register .......................................... 10 Appendix B : History .................................................. 11 Appendix C : Future Plans ............................................. 13 - 1 - - The Promotor Users Manual - - Introduction - 1.Introduction First of all, I would like to thank you for taking a look at the Promotor. If you are going to use this program regularly, then take a look at the Registration section in this document. So, what can the Promotor do for you ? People using the AGA chipset and kickstart 3.0 will probably have notice the Mode Promotion toggle in the IControl preferences. This switch should allow a sort of software de-interlacing by changing the screenmode for certain screens. Since, 3.0 came out, people have been complaining that the Mode Promotion feature wasn't good enough. A lot of screens don't get promoted and the user can't indicate what screenmode the system should use for the promotion. So ... Here is the real Mode Promotion utility ... The Promotor allows you to promote screens to any mode you wish. You can give instructions for specific screens, give general promotion rules, promote depending on the mode requested by the program, or depending on the task requesting the screen, the title of the screen or the public screen name for the requested screen. And you can do more than simply change the mode ... You can change the DriPens for the screens, the number of colors in the ColorMap, and a lot more (check out the tags for OpenScreenTags, most of them can be changed using the Promotor). I guess this will have you drooling by now, so this introduction has achieved the right effect ... 2.Installation Well, since you're reading this, you'll probably already have extracted the Promotor.lha archive. Please check the contents of this archive. You aren't allowed to distribute an incomplete version of the archive, so please check if the following files and directories are present in the archive: Promotor.info The icon for the directory Promotor/Promotor The main executable Promotor/Promotor.info Of course, THE icon ! Promotor/Promotor.config A sample configuration file Promotor/Promotor.config.info An icon for the config file Promotor/Promotor.doc The document you're reading Promotor/Promotor.doc.info An icon for the doc file Promotor/Register Program you need to register Promotor/Register.info Icon for the Register proggy To check out the function of the Promotor, you can simply double-click its icon. If you wonna install it on your system disk or onto your hard-disk, you should perform the following actions: - 2 - - The Promotor Users Manual - - Installation - 1. Copy the "Promotor" executable and its icon to the SYS:WBStartup director. 2. Edit the icons tooltypes by clicking on it once and then pressing [right-Amiga] & [I] at the same time (Kickstart 3.0). Now look up the entry starting with "CONFIG=" and change it to: CONFIG=ENVARC:Promotor.config 3. Now, copy the file "Promotor.config" to ENVARC: (this is an assign for SYS:Prefs/Env-Archive). 4. Edit the configuration file to fit your preferences ! And that's all folks ! The next time you reboot, the Promotor will automatically be started by the workbench. If you don't wonna reboot, simply double-click the Promotor icon in your WBStartup directory ! 3.The Configuration File Now, finally we come to the heart of the matter: how can you tell the Promotor, what you want it to do with the screens that are opened ... The current version of the Promotor gets all this information from a configuration file. When starting the Promotor, it uses the name you supplied (on the command-line or in the icons tool-types) or if no name was provided, it uses the default: ENVARC:Promotor.config ! We will now describe the format of this configuration file ... The Promotor considers the config-file as a list of screen-information. Each line describes one entry in the list. At startup (or when loading a new config-file) the Promotor creates the equivalent list in the memory of your computer and this list is used whenever a screen is opened to check whether or not is should be promoted and if so, in what way the Promotor should modify it. There are two things about this method that are important to know: 1. All data concerning one promotion entry has to be on the same line. You should therefor use an editor that can handle long lines (ED, cygnusED, but not MEmacs) to edit the configuration file. 2. The Promotor searches through this list from top to bottom and uses the first entry of which the screen that is to be opened matches the selection specifications. So if you wonna add a rule saying something like "promote all PAL hires interlace screens to DBLPAL", but would like to make an exception for DPaint, you should put in a line like "TASK=DPaint" before the line "MODE=PAL:High Res Laced TOMODE=DBLPAL:High Res No Flicker" - 3 - - The Promotor Users Manual - - The Configuration File - If DPaint opens a screen, the first rule will be used, since it's the first rule whose selection specifications accept screens from the task with the name "DPaint". Other tasks will be served by the second rule. Selection specifications are given by four entries in the configuration rule : TASK, PUBSCR, TITLE and MODE. We'll explain them in a moment. Now let's give the list of specifications and modifications you can put on one config line. First of all : if a configuration line starts with a semi-colon (';') it is regarded as a remark and not as an information line. This way you can add some explanation to your config-file, so you won't forget what the hell that entry was supposed to do ... A configuration line is parsed with ReadArgs, so we'll use the standard syntax for these options, like it is explained in the AmigaDOS 3.0 manual. TASK/K This entry is a selection specification. If it is supplied, only screens opened by tasks whose names match the given pattern are considered for this entry. Patterns can be any AmigaDOS pattern and matching is case insensitive. Example... TASK="Ami#?(A|B)" This will cause this entry to be used only for tasks whose names start with "ami" and end on an 'a' or a 'b'. PROG=PROGRAM/K Processes started from the CLI don't get the name of the executable, but instead they all get "Background CLI". To enable you to select specific CLI-based processes, the shell should provide a Command name in the CLI structure of the process. With this option, you can select screen by the Command name of the process requesting it. Tasks that aren't CLI based are assigned a Command name "" in the Promotor. PUBSCR/K This too is a selection specification. It tells the Promotor to consider this rule only if the public-screen name supplied in the TagList when calling OpenScreenTagList matches the given pattern. Example... PUBSCR="P#?V#?" This entry will only be applicable to screens whose public name starts with a 'p' and contains a 'v' somewhere. - 4 - - The Promotor Users Manual - - The Configuration File - TITLE/K Again, a selection specification. This time the default-title as given in the Newscreen structure or in the taglist is matched. Example... TITLE="#?DiskMaster#?" This entry will only be applicable to screens whose default title contains "DiskMaster". MODE/K And this is the last of the four selection specifications. The screenmode requested for the screen to be opened will be matched with this entry. First the Promotor will try to match the name of the screenmode with this specification (if the screenmode has a name). If this fails, the Promotor will try to match the hexadecimal representation with a leading "0x" and 8 hexadecimal digits with this specification. Do you get this ? Example... MODE="MULTISCAN:Productivity" Will only consider screens that would normally open in MULTISCAN:Productivity mode ... MODE="0x?????(08|0a)?" Will only consider screens whose displaymode ID (in its hex representation with 8 digits) has a 0 as the 6th digit and an 8 or an A as the 7th ! For all of the four selection specifications the following rules apply: 1. IF a specification isn't applied, it will be considered to be "#?", meaning that any screen will match this criterion. 2. The matching is always case insensitive. 3. Several selection specifications can be combined. They form a logical AND, i.e. a screen has to match them all to be considered for the entry. Now, the things you can modify about the screens ... X=LEFT/K/N The left offset of the screen. This can be very useful if you want to center the screen. Notice that no checking is done as to whether the supplied value is legal or not. If the value wasn't legal, the screen won't be promoted ! Y=TOP/K/N I guess I don't have to explain these ... - 5 - - The Promotor Users Manual - - The Configuration File - FAKEX/S FAKEY/S If the task calls GetScreenData, it will get FAKEW=FAKEWIDTH/S the coordinates you provided. FAKEH=FAKEHEIGHT/S HCENTER Instead of specifying X and/or Y, you could VCENTER simply use these, so the screen would open in the centre of the visual area. W=WIDTH/K/N Care should be taken when changing the H=HEIGHT/K/N dimensions and depth of a screen. If the D=DEPTH/K/N program requesting the screen doesn't check the actual size and depth of the screen it got from OpenScreen, your machine may crash ! Use this with extreme caution ! TOMODE/K Here, you can enter the name or ID of the mode you want to promote the screen to. The names you can use can be found in the ScreenMode preferences and may vary depending on the monitor-drivers you have installed. Some modes don't have a name attached to them, but you can still specify them by giving there ID as an 8 digit hexadecimal number with '0x' prepended to it. Example... TOMODE="DBLPAL:High Res" Will promote the screen to the "DBLPAL:High Res" mode if it is available. TOMODE=0x000690A4 Promote the screen to the display-ID 0x000690A4. If I'm not mistaken, this should be a Productivity HAM mode. OVERSCAN/K Here you can specify what overscan preferences should be used to determine the size of the screen you wonna open. You can specify one of the following : TXT, STD, MAX or VID. CMAPENTRIES/K/N This entry allows you to specify the number of entries you want in the colormap of the screen. Not very useful when promoting, but just to be complete ... Oh yeah, look out for this one. If you force a screen to have less colormap entries than the program requesting the screen wanted, the colors on the screen may look a bit weird ! ASCROLL=AUTOSCROLL/K/N If you set this to 1, AutoScroll will be enabled. If you set it to 0, AutoScroll will be disabled. Note that it may be necessary to force AutoScroll on or off (see the force options below). - 6 - - The Promotor Users Manual - - The Configuration File - FULLPAL=FULLPALETTE/K/N Here you can tell intuition whether or not to install its full palette. Again, only 0 and 1 are allowed, since this is a boolean option ! DRAG=DRAGGABLE/K/N With this boolean option, you can specify whether or not the screen should be draggable. EXCL=EXCLUSIVE/K/N With this boolean option, you can specify whether or not this screen is allowed to share the display with other screens. SHARE=SHAREPENS/K/N With this boolean option, you can tell intuition to use shared dripens for the dripens specified with the SA_PENS tag (which you can specify with the (DRI)PENS option). I still haven't figured out what the difference is between a normal dripen and a shared one, but I guess it has to be useful for something. FAST=INTERLEAVED/K/N This boolean option tells intuition to use an interleaved bitmap for the screen instead of one consisting of several uncoordinated bitplanes. This may speed up scrolling, but it may also help programs writing directly into the bitplanes to catch the guru! (Well, he changed his name and his looks, but for me he still is a guru!) So, be sure you know what you're doing with this option! LIKEWB=LIKEWORKBENCH/K/N Another boolean option. This one tells intuition to clone the workbench screen. SYSFONT/K/N Specify the system font to use. Use 1 for the old system font (Topaz) or 0 for the system font you specified in the preferences. PENS=DRIPENS/K This very useful option allows you to modify the dripens of the screen. This is useful for CED, Quarterback and some other programs that haven't noticed yet that 3.0 has some extra bar-dripens. You can specify a complete dripens-table in the following format: "xxxx:xxxx:...:xxxx" where xxxx is a 4 digit hexadecimal number with nothing prepended to it. DEFDRIPENS/S If you don't wonna specify your own dripens, but don't like the default dripens either, you can try out the dripens built into the Promotor. DRIPENS20/S This is a qualifier to one of the other dripens options, which makes sure that the BarBlock and BarDetail dripens are the same as the Block and Detail dripens! - 7 - - The Promotor Users Manual - - The Configuration File - The following switches can be used to tell the Promotor you really wonna change a specific thing about the screen to be opened, even if the program requesting the screen already demanded it to be exactly the contrary. Note that this may result in a clash between the program and the screen you gave it. So, be careful when using this, since it may cause a crash! We haven't given any specific explanation for each of the switches, since their meaning seems clear to me : they ensure you that the option you specified are really going to overwrite any options of the program requesting the screen. FORCEX=FORCELEFT/S FORCEY=FORCETOP/S FORCEW=FORCEWIDTH/S FORCEH=FORCEHEIGHT/S FORCEDEPTH/S FORCEMODE/S FORCEOSCAN=FORCEOVERSCAN/S FORCECMAPENTRIES/S FORCEASCROLL=FORCEAUTOSCROLL/S FORCEFULLPAL=FORCEFULLPALETTE/S FORCEDRAG=FORCEDRAGGABLE/S FORCEEXCL=FORCEEXCLUSIVE/S FORCESHARE=FORCESHAREPENS/S FORCEINTERLEAVED/S FORCELIKEWB=FORCELIKEWORKBENCH/S FORCEPENS/S FORCESYSFONT/S There should be an example configuration in the Promotor distribution. Take a look at it to see how I use the Promotor ... 4.The ToolTypes or Command-Line Options The Promotor can be started from the Shells command line or from the Workbench. In the first case, any options should be specified as parameters on the command-line. If you specify a question-mark, you will be prompted for the options: CFG=CONFIG/K Here you can specify which configuration file should be loaded. The default is "ENVARC:Promotor.config". CX_PRIORITY/N/K The priority of the Promotors commodity handler can be specified here. Default is 0. CX_POPKEY/K Here you can specify the hotkey for the Promotors users-interface. The default is "rcommand rshift escape" CX_POPUP/S This one is ignored at the moment, since the GUI of the Promotor isn't finished yet ... If you start the Promotor from the Workbench, you can use the above entries in the ToolTypes. Note that if any of the parameters contains spaces, you'll have to put double-quotes (") around that parameter. This is valid for both ToolTypes and command-line options. Example: CX_POPKEY="rcommand rshift escape" - 8 - - The Promotor Users Manual - - The Users-Interface - 5.The Users-Interface As stated above, the users interface isn't finished yet, but I have provided a small requester that pops up when the hotkey is pressed and that enables you to: Quit Remove the Promotor from memory. Reload config Reload the current configuration file. New config Load a new configuration file. Cancel Don't do a thing ... Note: When reloading a config or loading a new one, all currently defined entries will be removed. - 9 - - The Promotor Users Manual - - How To Register - Appendix A : How To Register If you have started the Promotor, you may have noticed those annoying requesters that pop up every time you open a new screen. These requesters are meant to be annoying and should remind you of the fact that you really should register ... Now, how do you register? It's very simple: 1. Send me a letter (address listed below) containing: - a note with your address (and email address) - $20 US (20 US dollar) or the equivalent (or more) amount of money in some other currency. If you don't specify your complete address, I won't reply your mail! 2. Wait about 1 week if you gave me your email address or about 2 weeks if you supplied your snail-mail address. (This may be longer in the months june/july/august/september, since I'm studying at that time or I'm on holidays!) 3. You will then receive a note from me containing an alfa-nummeric key in the following form: #beginning of key a421b89a90093dds090asf8fsa9f8afsd9879af0affd9980ddsaffd987sfd98f ds76fd9d9f #end of key Note: The actual key consists of the data listed between "#beginning of key" and "#end of key", without spaces or line-feeds. 4. Start the program called "Register" the was also in the Promotor distribution, by double-clicking it. (Make sure it's in the same directory as the Promotor, or change the tooltypes) 5. Now a window will appear with a text area within it. Type in your key (the thing you received from me) without spaces or line-feeds and select the Continue gadget. If everything went according to plan, the program should now report that you have succesfully registered for the Promotor, and the next time you start this copy of the Promotor, the annoying requesters will disappear. Please note that this key contains information on your name and address, so don't go around spreading your version of the Promotor ... I'm bound to find out you spread it! Whenever a new version of the Promotor comes out, registered users can use their key to register for the new version, which will be distributed in the same way as this one. And now of course, my address: Kurt Haenen Homsemstraat 53 B-3891 Borlo Belgium - 10 - - The Promotor Users Manual - - History - Appendix B : History - Version 1.00 - Released on monday, 19-Apr-1993 - First public release. Handles most of the tags OpenScreenTagList understands and has a very simple user-interface in the form of an EasyRequester ! The definition of all the stuff has to be entered in the configuration file directly, no configuration editor yet. - Version 1.01 - Released on saturday, 24-Apr-1993 - Minor bug-fix to the registration routines. There was a bug that caused some enforcer hits. This would only show up at registered users and since noone has registered yet, I'm not in a hurry to sent out this new version. - Version 1.02 - Released on monday, 3-May-1993 - Major bug fixed : I forgot to fill in the Font tags for the OpenScreen stuff, so screens would normally get your prefered preferences font. This has changed. I've added a SysFont option so you can overwrite the programs requested screen-font by one of your prefered system fonts! - Version 1.03 - Released on friday, 7-May-1993 - Minor bug-fix in the registration check routines. If more people would register, I could find these bugs a lot quicker. The problem was that every time I recompiled the stuff another key was needed. I didn't notice this because I always generate a new key automatically. Thanks to David Nouls for reporting this bug. Registered users will receive new keyfiles and this time they should work on all future versions of The Promotor! - Version 1.04 - Released on sunday, 9-May-1993 - Added screen centering options HCENTER and VCENTER. Added a patch for GetScreenData, so programs using this function to get the default sizes will get the right values for width and height. - 11 - - The Promotor Users Manual - - History - - Version 1.05 - Released on monday, 17-May-1993 - Patching GetScreenData is now optional using the FAKE options. A new selection mechanism was added for CLI processes: you can now specify the Command name as a selection criterion for these processes. Thanks to Arno Hollosi for suggesting this. - Version 1.06 - Released on monday, 31-May-1993 - At last the LIKEWB option works. It seems all other options overwrite LikeWorkbench. The current implementation is so that any of the following options can be used to overwrite some aspects of the LikeWorkbench option: X, Y, Width, Height, ToMode and Overscan. - 12 - - The Promotor Users Manual - - Future Plans - Appendix C : Future Plans o Complete rewrite of the Promotor to version 2.0 (upgrades will of course be for free for registered users. Plans are to give it a better structure, a bit object oriented with clients for different types of promotion. This would include a client for screen-promotion, but also one for window-promotion and maybe gadtools promotion. Also planned is some sort of script-language (probably something lisp-like) to allow much more complex types of promotion. This will probably take me all summer. In the meanwhile I'll still fix bugs in the old version if someone reports them ... If you've got any remarks, I can be reached at the snail-mail address listed in this document, or at the following email addresses: FHGAA99 @ CC1.KULEUVEN.AC.BE at least 'til june. STUD16 @ CC4.KULEUVEN.AC.BE at least 'til end of april. NOTE: At the moment, I'm not able to receive electronic mail. If you wonna contact me, you should use the snail-mail address listed below. Some moron decided to upload some commercial software onto an FTP-site and entered stud15@cc4.kuleuven.ac.be as his user-ID. The FBI contacted our computer-centre and now the direction of our centre has decided to close down the studxx accounts :-( ... If I ever get my hands on that son of a bitch !?&@&! Well, I think that's all for now ... And please guys, register ! I need the money to buy a modem now that my account is going to be killed ! Kurt Haenen Homsemstraat 53 B-3891 Borlo Belgium Author of the Promotor Co-author of the Multiuser-Filesystem /\ /\ /\ / \/ \/ \ / / / \ \ \ \ / /\ /\ /\ /\ \ \/\ \/\ \/ / \ /\ /\ / \/ \/ \/ - 13 -