**************************************************************************** *** *** *** WimpX v1.5 - Documentation File *** *** *** *** Copyright R.C.Meathrel 1993 *** *** *** **************************************************************************** * 21st NOV 1993 Background & Intro ****************** WimpX is basically a program which allows the intuition environment to be explored and altered. The WimpX project was undertaken due to the appearance in my disk box of a similar style of program - Fenster. After I first came across Fenster and began using it, mainly for the screen save, I was myself inspired(?) to write a similar utility. It might be said in fact that WimpX is very much like Fenster in many respects, ie. Screen layout! My first version of WimpX was, quite frankly, a sorry affair, as those who had the mispleasure of seeing it will undoubtedly tell you. The interface was pretty crap and the coding behind it wasn't that better either, this was a couple of years ago now though when I had only just started in Assembly progging (Yes - WimpX is written in Asm not C, for speed and compactness). Actually WimpX v1.5 is the newest member of the third generation of WimpX, the first two generations having collapsed due to some fairly dodgy coding practice on my part. Development Info **************** The assembler I use to prog WimpX is of course Devpac3 and I use BLink for all of the linking. WimpX presently consists of 7 object files which are linked together and then the final executable is crunched with PowerPacker4. WimpX v1.5 is around 69K uncrunched which is a bit larger than it ought to be given the fact it is in assembler. Version 1.5 has been tested on several Amiga models including the A500,A500+,A600,A1200 and the A4000 under all sorts of kickstarts - V1.2,V1.3,V2.04 and the latest V3. I firmly believe that version 1.5 will work on ALL Amigas bar those with kickstarts 1.1 or previous as WimpX asks for V33 libraries. WimpX has been tested fairly rigorously using a multitude of debugging tools including commodore's own Enforcer (great prog!), although testing using Enforcer was carried out on an A4000 by Dave OJ without my presence, and so I am just trusting him when he tells me that everything is fine! Basic operating instructions **************************** To install WimpX you must either double-click on it's icon if using WB or alternatively type in WimpX preceded by the path if using the Shell or CLI. You may wish to use the 'run' command so that you can still use the CLI to run other programs. When WimpX has installed itself it brings up a small window on the Workbench screen, to access the features of WimpX you must depress the right mouse button whilst the window is active or press the return key. At this point the main WimpX screen should appear (memory permitting) and work can commence. You can return WimpX to it's sleep state at any time by pressing the Return key, or clicking on "Return to WB". Using WimpX *********** Using WimpX is really quite simple and requires little explanation - WimpX was designed to be as intuitive as possible. All you need to utilise WimpX to the full is a working mouse and a bit of common sense. :) The main function of WimpX, as stated above, is to nose around the intuition environment, making changes where and when you want to. The first thing to do is to select what you wish to work on, this will be a particular screen or maybe a particular window in that screen. You make your selection using the list of names in the centre of the WimpX screen. When WimpX is woken up it displays a list of screen names for you to choose from, when you click on your chosen screen name a further list will appear but this time showing all the names of the windows open in the chosen screen. When you have made your selection you may use all of the tools that WimpX provides to alter or investigate the intuition environment. Notes: The 8 chars beside each screen name give some indication of the ****** screen resolution ie. (MEDRES) = Medium resolution eg. 640x256 (PAL) & (HR-LCD) = High resolution interlaced eg. 1280x512 (PAL) HAM - Hold & modify, EHB - Extra half brite & LCD - Interlaced. Click 'Show Screens' to return to list of screen names and click 'Update List' if window/screen activity has occured during the selection/browsing process. Use scroll bar and arrows to advance through the list ---> '#' - Equivalent to Up arrow & '/' - Equivalent to Down arrow. Use keys 1-9,0,- & = to highlight/select one of the 12 screen or window names. Key shortcuts ************* You have probably noticed that some letters have underlines, this means that pressing the lettered key will have the same effect as clicking the mouse for a particular function. Ie. pressing 'o' after selecting a screen will bring up screen information. Important note: Unlike most other WB2 & WB3 utils. WimpX IS case-sensitive, *************** this means that if, in the above example, you pressed shift-o instead of just 'o' then there would be no effect. This might seem a bit silly but, unlike most programs, WimpX has around 30 shortcuts and using a different letter for each one would be impossible. Sorry about this but I believe what I have done is a good idea (honestly). The Screen/Window Functions *************************** Now follows a list of the main WimpX functions and how to use them ---> Screen functions **************** To Front - Moves selected screen to front of display. ~~~~~~~~ To Back - Moves selected screen to the back of the display. ~~~~~~~ Change Title - Brings up another small window and allows name to be altered ~~~~~~~~~~~~ with the limitation that the length of name cannot be extended. Close - Brings up a confirmation requester from which the screen can be ~~~~~ closed. Note: Any windows open in the screen will be closed automatically before the screen closure. Save - Brings up the screen saving suite where you must provide a filename. ~~~~ The screen can be saved in one of 3 different formats. IFF-ILBM saves the screen such that the picture can be loaded in DPaint and most other paint packages. IFF-ACBM is really only there for completeness and will probably only prove useful to those using AmigaBASIC. RAW format saves the screen as a series of bitplanes one after another and will be of most use to programmers. Clicking the 'select...' button brings up an ASL file requester provided that WimpX was able to open the ASL library when it was run. If ASL isn't available then this button will be ghosted. Note: WimpX does not compress the saved screens. ***** Xtra Notes: WimpX v1.5 will save out ANY screenmode currently obtainable *********** from ANY Workbench version including WB3! Ie. FULL support for HAM8 and standard 256 col. modes. Including 8-bit RGB CMAP chunks using the BMHDF_CMAPOK flag. Adjust Cols. - Brings up the WimpX palette editor so that the palette of ~~~~~~~~~~~~ the selected can be altered. No explanation on using PalED is needed, just select your colour from the palette and move the old sliders around a bit. Note: The WimpX PalED recognises both 4-Bit RGB and 8-Bit ***** RGB when READING the screen's colourmap, Eg. each component can have a value 0-255. However, when WimpX alters the palette of a screen it writes the new values as 4-Bit RGB using the LoadRGB4 ROM routine! This is because I have no documentation on the LoadRGB32 routine!!! Now I know this is not on but unless somebody can loan me the new RKMs I can do nothing about it! Information - Brings up the screen information window which gives some ~~~~~~~~~~~ useful information about the selected screen such as the dimensions, memory used, number of bitplanes and a few addresses of related structures. Also the number of windows present in the screen is displayed. Window Fuctions *************** To Front - Brings selected window to front of all other windows. ~~~~~~~~ To Back - Sends selected window behind all other windows. ~~~~~~~ Shrink - If the window is a resizable one this function reduces the ~~~~~~ dimensions of the window to the smallest allowed by the window definition. Expand - Expands selected window to it's maximum size taking into account ~~~~~~ the screen title bar. Close - Brings up a confirmation requester allowing the selected window to ~~~~~ be closed. If the window has a menustrip attached the menustrip is first cleared before the window is closed. IDCMP - Brings up the IDCMP flags suite which shows you what IDCMP flags the ~~~~~ selected window utilizes and allows these to be modified. Gadget ED - Brings up the gadget editor suite which allows all gadgets ~~~~~~~~~ attached to the selected window to be investigated and possibly changed (only of use to programmers - if anyone!). > See below for instructions on how to use the gadget editor < Pointer - Brings up the pointer options window which offers a wealth of ~~~~~~~ choices - not! From here you can opt to use the default pointer for the selected window as opposed to any custom one which might have been installed by the appliprog. Palette - Brings up the 'Palette options' window allowing the selected ~~~~~~~ screen's palette to be saved in one of 3 formats, Colourmap, binary or sourcecode. Palettes saved as colourmaps can be loaded into DPaint for example and used as palettes. Binary saves out the colourmap entries as raw binary, which is mainly of use to programmers. Sourcecode saves out the palette as assembly source, eg. Dc.W $012C,$0000 Dc.W $0FFF,$0127 Use the 'Select...' button to specify a filename using an ASL file requester. Refresh Window - Brings up the 'Refresh options' window allowing the gadgets ~~~~~~~~~~~~~~ and/or windowframe of the selected window to be refreshed. Information - Brings up the window information window which allows the ~~~~~~~~~~~ selected window's name to be altered, the window to be moved about it's host screen using the proportional gadget. Also the window's dimensions are listed together with the number of gadgets attached to the window and a list of related structures. Print - Brings up the printer suite from which you can print out the window ~~~~~ or it's host screen. The 4 toggle buttons at the top control how the picture is to be printed. The default setup should suffice for most users although experienced users might require the use of the extra flags to fine tune the printout. Below the flags are 6 text gadgets which allow the user to specify the area of the window which is to be printed. The PrtHeight and PrtWidth fields determine the width of the resulting printout in printer pixels. This means that the printout resolution is only limited by the output device, this makes printing from WimpX very flexible and worthwhile. Once WimpX has been instructed to print, a small window will open in the middle of the screen, and selecting the STOP gadget will quit the printing process. It is a good idea to manually reset the printer if the printing process has been cancelled otherwise the next print is likely to start off with garbage! The only down side to the printing suite is that if you wish to print the host screen then only the PrtHeight and PrtWidth fields will be taken into account when printing and the remaining fields will be computed automatically. Note: Unlike all previous versions of WimpX, WimpX1.5 checks to make ***** sure that base pointers are valid before attempting to either close a screen or a window. This was included as a kind of safety net and also to stop Dave OJ moaning. :-) The Gadget Editor ***************** The gadget editor is a relatively new edition to WimpX and it lets you investigate and alter gadgets which programs use. If the gadget editor does not appear when you click the button this is because the selected window doesn't have any gadgets attached to it. You can move through the gadget list by clicking on the arrows or pressing '<' & '>'. The gadgettype informs you the type of gadget eg. Boolean. The 4 string gadgets allow you to alter the dimensions of the gadget. Clicking the 'Flags...' button brings up a window displaying what flags are available and which of these are used, these can be altered just as in the window IDCMP suite. Note: Bits 0 & 1 (displayed as $0001 & $0002) determine the gadget's ***** highlighting, here is an explanatory table... Bit 0 | bit 1 | resulting highlighting ------+-------+----------------------- 0 | 0 | GADGHCOMP ($0000) 0 | 1 | GADGHIMAGE ($0002) 1 | 0 | GADGHBOX ($0001) 1 | 1 | GADGHNONE ($0003) Clicking the 'Activation...' button brings up a window similar to the gadget flags window described above. The rendering window which is activated by clicking on 'Rendering...' reveals any border structures or images or intuitexts which the gadget in question uses. Clicking discard on the appropriate item will detach that structure from the gadget, never to be seen again. The 'Special Info...' window contains information regarding either a stringinfo structure or a propinfo structure depending on the gadgettype. Note: 'Rendering...' and/or 'Special Info...' may be ghosted if not ***** applicable to the currently selected gadget. Functions ********* Remove - Removes the current gadget from the list and resets the editor ~~~~~~ to the first gadget in the list. Refresh - Refreshs the current gadget. If you alter the gadget dimensions ~~~~~~~ then you must click on 'Refresh' to let the changes take effect. Note: When you exit from the flags/activation/rendering and ***** special info windows the changes made by you will be installed without the need to click 'Refresh'. Overwrite - Draws a solid box using colour 0 onto the gadgets select box, ~~~~~~~~~ useful when moving imagery around. Note: Doesn't work with gadgets which have relative coords. ***** Preferences *********** Note: If ASL is unavailable then the two menu items, 'Font...' and ***** 'Screenmode...', will be ghosted. The WimpX preferences is accessed via a pull down menu which can be revealed by pressing and holding the right mouse button in the usual way. 4 options are available ---> General - Brings up the general prefs window allowing various paths to be ~~~~~~~ configured and also the maximum number of screen/window names in each of the lists. Note: Pressing 'R' will activate the first string gadget and ***** pressing the Tab key will progress through each of the string gadgets in turn. Font - Brings up the font requester (only if ASL is available) where a ~~~~ suitable font can be chosen. Screenmode - Brings up the screenmode requester (only if ASL is available) ~~~~~~~~~~ where a new mode for the WimpX screen to open in can be selected. Note: The control panel of the palette editor takes the same ***** mode as the main WimpX screen. Save settings - Saves current state of WimpX, including --> ~~~~~~~~~~~~~ 1) The coords of WimpX WB window, 2) The coords of main WimpX screen, 3) List allocation, 4) Colours (First 4) of main WimpX screen, 5) Font used for WimpX screen, 6) Screenmode used for WimpX screen, & 7) Various user paths ...to the current directory. Note: To alter colours of WimpX just select the WimpX screen and then ***** click on "Adjust colours" to bring up the palette editor. You change the WimpX screen colours just as you change any other screen's colours. ARexx support ************* Although WimpX v1.5 does support ARexx the command set that I have provided is somewhat limited and perhaps not greatly useful, however, the reason I have included ARexx support is because I feel that all Amiga programs written now must support ARexx if possible. This will help provide a consistent environment. When writing the ARexx interface for WimpX I had only the small Commodore manual to get info. from and it was not altogether too informative. This means I had to extract structure info. etc. from the include files! I expect that future editions of WimpX will include much more adequate support for the ARexx language. Anyway, here are the commands implemented so far ---> 1) HOME - Moves WimpX window to top-right of WB 2) SCREEN scrnname - Selects a screen to work with, where scrnname is a valid screen name. RC=0 if name is valid. 3) WINDOW windname - Selects a window to work with, where windname is a valid window name. RC=0 if name is valid. 4) SAVEILBM filename - Saves selected screen as an IFF-ILBM file as filename. 5) SAVEACBM filename - Saves selected screen as an IFF-ACBM file as filename. 6) SAVERAW filename - Saves selected screen as a RAW binary file as filename. 7) REFRESHWINDOW - Refreshs the selected window's windowframe and all of the gadgets. 8) DEFAULTPOINTER - Changes the pointer imagery of the selected window to default imagery. 9) CLOSEWINDOW - Closes the selected window. 10) CLOSESCREEN - Closes the selected screen. 11) SHRINKWINDOW - Shrinks the selected window. 12) EXPANDWINDOW - Expands the selected window. Example ARexx prog to save out WB screen **************************************** /* A Simple Screen Saver */ /* By R.C.Meathrel */ Say 'Enter filename to save Workbench screen as...' Parse Pull NAME Address WIMPX /* ARexx port name of WimpX is WIMPX */ SCREEN 'Workbench' /* Select screen - in this case the WB screen */ SAVEILBM NAME /* Save screen */ Exit As you can see, my ARexx skills haven't really taken off as yet! ============================================================================ --- SIGNING OFF --- ******************* Please write to the address that follows with ANY bugs which you might have found in WimpX or ANY suggestions for improvement. My present contact address --> Richard Meathrel 9 Tennyson Close, Westhill, Torquay, Devon England TQ1 4PQ University address (mail here during term time)--> Richard Meathrel Hope Hall, Prince of wales road, Exeter England EX4 4PD Feel free to mail me at --> cs93rcm@exeter.ac.uk with ANY comments. Misc. comments: WimpX is crunched with the excellent Powerpacker. ~~~~~~~~~~~~~~ Main source length : approx. 170K Total source length : approx. 224K Decrunched length : approx. 69K crunched length : approx. 25K Beta tester : David Ockwell-Jenner Linker used : HiSoft's BLink v5.07 Icon made using : DPaint II and Iconmaster Printing tested on : Star LC-10 colour Amiga(s) Used : A1200 {120MB HD} &A500 (Both 2MB) Last Point: WimpX is what i'am going to call "commentware", that is, ********** if you use WimpX you must sent me your thoughts on it to one of the addresses above. Enjoy! :) xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ============================================================================