@database "CentreQuest"
@wordwrap
@node main
@title "Contents of CentreQuest"
@{b}The Contents Page@{ub}

@{"Introduction     " link Intro}
@{"Quickstart       " link Quick}
@{"Installing       " link Install}
@{"Instructions     " link Instruct}
@{"Troubleshooting  " link Troubles}
@{"About the program" link Program}
@{"Distribution     " link Distribute}
@{"About the author " link Author}
@endnode

@node Intro
@title "Introduction to CentreQuest"
@{b}Introduction@{ub}

CentreQuest has a mission. It's quest is to prevent those system requesters from always appearing religiously in the top, left hand corner of the screen. Yes, there are others that do it, but I don't like the way they hack into and replace the system routines; and I don't like the look of some of them as well. Sure, some may be a little more animated the the standard one, but all I want is it to appear in the centre of the screen or on the mouse pointer. CentreQuest achieves this, and if it is all you want then this program has an avenue and my work has not been wasted on a fruitless endeavour. It also does it in a system friendly way and unlike the others actually manages to retain the original system requester routines by working around it somewhat. That's the introduction, now lets get on with the quest!
@endnode

@node Quick
@title "Quickstart to CentreQuest"
@{b}Quickstart@{ub}

Simply run the program, and if you encounter no @{"errors" link Troubles} and all goes okay then cause a system requester to appear. CentreQuest will also bring up it's own test requester if set to do so in the icon @{"Tool Types." link Instruct} You can also run the @{i}TestRequest@{ui} program included to bring up a simple test requester. Now watch as it @{i}looks@{ui} completely normal, but has mysteriously opened in the centre of the screen! Viola! CentreQuest fulfilling it's mission.
@endnode

@node Install
@title "How to install CentreQuest"
@{b}Installation@{ub}

By double-clicking on the Install icon will start up a script that will install it for you. Don't worry, it's not too stupid or arrogant. It won't simply copy files without asking. There are two main files to install, the program file, the guide file and their assorted icons. The script will select the WBStartup directory for the program file and the logical assign HELP: for the guide file. Before it copies any files it will bring up a file requester where you can select an alternate drawer if you wish or select "Cancel" to avoid copying particular files. By selecting "Okay" you will give it the go ahead and it will start copying files across. The script requires the command RequestFile to be resident in your C directory. You can off course, copy the files manually yourself, but the script is better than no installer at all. Even if its not the fancy official one used by commercial software.
@endnode

@node Instruct
@title "Instructions on using CentreQuest"
@{b}Instructions@{ub}

CentreQuest can be run from either the Workbench or a CLI window. Workbench Tool Types and CLI Arguments are explained below. If any @{"errors" link Troubles} are encountered they will be reported in a (normal) nice system requester which will also try to explain what went wrong.

CentreQuest runs as a standard commodity and can be enabled/disabled or removed with the commodities Exchange program. It has no hotkey as it has no need for one.

@{fg highlight}Customising it to your requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~@{fg text}
CentreQuest has a list of definable options. These can be set in the Tool Types of the program icon, or in the CLI which will override the Tool Types. The CLI command template is shown below, with the meaning of each argument listed after.

CentreQuest Template:
CX_PRIORITY/N/K,AUTOQUIT/K,CENTRE/K,TEST/K:

Argument Definitions:
@{b}CX_PRIORITY@{ub}
Sets the priority of the Commodity as described in the Workbench Manual. Usually this can be left as is but is provided if it needs to be set. By default is set to zero.

Example:
CX_PRIORITY=1

@{b}AUTOQUIT@{ub}
This tells CentreQuest whether to quit and remove it self from memory if the program is run a second time and is already resident. Set it to YES or NO. YES will quit automatically if ran a second time and NO will ignore it. Default is YES.

@{b}CENTRE@{ub}
This is the major option and sets the type of centring that the program uses. Options are SCREEN, WINDOW, POINTER and GADGET.

SCREEN
This will simply centre requesters in the middle of the screen and is the default option.

WINDOW
This will centre the requester inside the current window if possible or around it. If the requester is not opening on the current windows screen, it will default to centring on the screen it is to open up on.

POINTER
This will centre the requester around the pointers current position taking into account the screens limits.

GADGET
This is similar to the POINTER option but instead will centre the requester's @{i}last@{ui} gadget (for example the Cancel gadget) around the pointers current position again taking into account the screens limits. The last gadget is used because it is usually the cancel gadget and is regarded as safe choice.

Example:
CENTRE=WINDOW

Will now centre requesters within the current windows bounds if possible.

@{b}TEST@{ub}
This tells CentreQuest whether to open up a test requester after it has initialised, useful for testing where a requester will open. Set it to YES or NO. YES will open up a test requester and NO will not. Default is YES.
@endnode

@node Troubles
@title "Trouble-shooting guide for CentreQuest"
@{b}Troubleshooting@{ub}

Should you encounter any trouble or errors when using CentreQuest this section will hopefully help you pinpoint a problem and how to resolve it.

Error: @{i}Program fails to load because it complained about a ToolType.@{ui}
This would usually happen if you entered incorrect data in the icon ToolTypes or if ran from the CLI some bad arguments. CentreQuest tries to be helpful when you have stuffed up a ToolType by telling you what you have put and what your options are. The best advice here would be to take note of what the program tells you and correct it. It should be fairly self-explanatory if you encounter such an error.

Error: @{i}Program fails to load because it could not open required library.@{ui}
Check you have the required libraries in your LIBS: assign. These are version 37 of commodities.library, asl.library, intuition.library and the gadtools.library. And version 36 of the icon.library. CentreQuest also opens version 37 of the dos.library and graphics.library, but that shouldn't cause a problem.
@endnode

@node Distribute
@title "Rules for distribution"
@next Program
@{b}Distribution@{ub}

This program is what I consider to be @{i}EveryWare.@{ui} Since I offer it free I give you the duty of distributing it everywhere. Which you may or may not do, it's your choice. Give it to your friends. Distribute it on the net. Just make sure all the files are together and intact.
@endnode

@node Program
@title "About the program"
@last Distribute
CentreQuest was written using Amiga E. This is the first version of the program released to the public and installed on my harddrive as well.

For the techinically minded interested in how I pulled it off without hacking into the system request routines will find this information beneficial. To do what it does, CentreQuest has to patch something, and it does. But it doesn't completely replace it or try to rewrite unneccesary code. The only routine patched when CentreQuest is fully installed (after it has initialised itself) is OpenWindowTags(). EasyRequest() and BuildEasyRequest() are left completely alone on which this program is actually based around. They are not patched! CentreQuest does not need to patch these functions so the original ROM versions can be used without modifying them. Ingenious or what?! By mentioning OpenWindowTags() I've already given the hint on how this is achieved and I will explain it here. When a program makes a call to OpenWindowTags() my code will check where it was called from and if it was from one the EasyRequest() routines then control is passed over to my centring routines that will set a new window offset. How does it do this? During the initialisation procedure it simply finds the program counter of the routine in the particular EasyRequest() code that makes the OpenWindowTags() call, then stores it for future reference. It is now used for an ID to identify an EasyRequest() function call. Now you know my secrets and can rest assure that you also know what my program is doing or even not doing.
@endnode

@node Author
@title "About the author"
I been programming for about five years and this program is one of my first steps into a high-level language. Future programs of mine will probably sport GUI interfaces. Something I've not gone far with by using assembler. Any way, here are my contact details:

Damien Stewart
41 Kempston St.
Greensborough 3088
[Victoria, Australia]

Ph. (03) 9435 7836


Sorry, you can only contact me by snail-mail or audio-phone contact. I'm probably the only Amiga programmer alive who isn't on the web. Oh dear. Even a modem to connect me to a BBS would do. Text browsing. Yeah!

For the World Wide Webbers you can visit the home page of the AUG (Amiga User Group) I am a member of. The site is at http://www.aug.org.au
Hopefully one day it will appear in the user group section of @{i}CU Amiga@{ui} magazine.
@endnode