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 / prog_oth / gadtlbox.lha / GadToolsBox.DOC < prev next >

Wrap

Text File | 1992-09-26 | 110.6 KB | 2,099 lines

GadToolsBox 1.4 (The Sequel) v37.177 (c) Copyright 1991,92 Jaba Development Written using DICE C v2.06.40 by Jan van den Baard Bakkerstraat 176 3082 HE Rotterdam Holland Fido: 2:285/502.7 Oberon Source Generator by Kai Bolay (AMOK) Hoffmannstraße 168 D-7250 Leonberg Germany Fido: 2:247/706.3 UUCP: kai@amokle.adsu.sub.org User Manual (c) Copyright 1991,92 Jaba Development This program uses both the powerpacker.library and reqtools.library (OS 2.0 version) These two libraries are (c) Copyright Nico François __ __ / / / \ __ / / / /\ \ _____\ \__/ /_/ /_/ /_____ (__________________________) »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » How to obtain an update. » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» Many people have written to me asking for updates. This kind of gotton out of hand (it was beginning to cost me a lot of money) so here is the way to get an update directly from me. Send me a self addressed envelope, 1 US dollar (EUROPE) or 2 US dollars if you don't live in europe and a 3½" disk. Then I will send you an update as soon as it becomes available. Disclaimer................ 1 Copyright/Distribution.... 2 Electronic Distribution... 3 Introduction.............. 4 Requirements.............. 5 Starting GadToolsBox...... 6 Making a Gadget........... 7 Program Menus............. 8 The Project Menu........ 8.1 The Gadgets Menu........ 8.2 The Window Menu......... 8.3 The Screen Menu......... 8.4 The Menus Menu.......... 8.5 Gadget Kind Requester..... 9 The CheckBox Gadget..... 9.1 The Integer Gadget...... 9.2 The ListView Gadget..... 9.3 The Mx Gadget........... 9.4 The Cycle Gadget........ 9.5 The Palette Gadget...... 9.6 The Scroller Gadget..... 9.7 The Slider Gadget....... 9.8 The String Gadget....... 9.9 The Number Gadget....... 9.10 The Text Gadget......... 9.11 Menu Requesters........... 10 The Menu Requester...... 10.1 The (Sub)Item Requester. 10.2 The Generated Source...... 11 The IDCMP handler....... 11.1 The Keyboard & Mouse...... 12 The GetFile Boopsi image.. 13 Adapt Font................ 14 Keyboard Shortcuts........ 15 Oberon Source............. 16 Notes..................... 17 Credit.................... 18 __IMPORTANT__............. 19 »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 1) Disclaimer » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» The author cannot be held liable for the suitability or accuracy of this manual and/or the program(s) it describes. Any damage directly or indirectly caused by the use or misuse of this manual and/or the program it describes is the sole responsibility of the user her/him self. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 2) Copyright/Distribution » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox, (c) Copyright 1991,92 Jaba Development. All rights reserved. This program is FREEWARE so no financial donations are required ( but welcome ). This program may be freely distributed as long as all source code, documentation and executable(s) remain unchanged and are included with the distribution. Also no profit is to be made by selling this program. You may not charge more than Fred Fish does for a single library disk. When you use this program on a regular base I would appreciate a postcard of your home town. If this program is used to create a GadTools user interface for commercial or shareware programs I would appreciate a little note about this in the program it's documentation. Commercial distribution is NOT allowed without written permission from the author. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 3) Electronic Distribution » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» It is allowed for non-commercial BBSs to distribute an archive with only the following files in it to save your users some money when they want to download this program. NOTE: All files listed below MUST be distributed together. None of the files listed below may be distributed on it's own! They may of course be archived with LHarc or any other archiver. GadToolsBox - Main Program GadToolsBox.info - Main Program icon. GadToolsBox.DOC - Main Program Manual (This file) nofrag.library - Shared library ( (c)1991,92 Jaba Development ) reqtools.library - " " ( (c) Nico François ) powerpacker.library - " " ( (c) Nico François ) boopsi.s - Boopsi routine source boopsi.o - Boopsi routine link object code OberonBoopsi (dir) bases.s - Library base definitions source bases.o - Library base link object code boopsi.s - Somewhat adjusted boopsi routine source boopsi.o - Somewhat adjusted boopsi link object code getfile.mod - Oberon interface module for the boopsi image You may NOT upload this or any other form of this software on BBSs that claim copyrights on the uploaded material! »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 4) Introduction » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox is a program that will save you a gigantic amount of time and anguish in creating a GadTools user interface for your programs. This program is a follow-up of my other source generator "PowerSource". It's main purpose is to let you create your user interface without having to type in the necessary code and structures yourself. This version of GadToolsBox has the following features: -: A complete intuition/gadtools user interface -: Editing on many different screen resolutions -: Editing/Generating source on/for big autoscrolling screens -: All GadTools gadget kinds supported + a custom gadget -: GadTools menus supported -: Full control over the window flags and most tags -: Editing IntuiTexts for the window -: Editing, loading and saving of colors (ILBM) -: Fully mouse and keyboard controlled -: Generation of complete routines in either C, Assembly & Oberon -: Generation of "RAW" Assembly source (No headers necessary) -: Generation of "static" data -: Binary saving for later loading and editing -: The possibility to save powerpacker __CRUNCHED!__ binaries. -: The ability to print a status report. -: Multiple windows -: User selectable font -: The editing of "DRIPENS" (what gives OS 2.0 that special look) -: The possibility to change screen resolution while editing -: The possibility to edit "BevelBoxes" -: Editing in a user-definable grid -: The editing of minimal window border offsets -: Easy gadget alignment and spacing -: The generation of font-adaptable code (Thanks Sebastiano...) -: Multiple gadget moves, deletes, edits and copies. -: The generation of event-handlers. -: etc. etc. etc........ »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 5) Requirements » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox was programmed with DICE C v2.06 (Thanks Matt) on an Amiga 2500 Kickstart V37.175 Workbench V37.67 with 7 MB memory + ECS + A2630 accelerator card + 52 MB harddisk. It should however run happily on a 1 MB machine without a harddisk and special chips but at least 1.5 MB is suggested. It MUST have Kickstart V37++ and Workbench V37++. A C Compiler ( try registering DICE ) and/or an assembler with the 2.0 headers can also come in handy when you try to compile/assemble the generated source. Note however that the program can generate assembler source which does not require the headers to assemble. The program needs the following libraries: reqtools.library version 38 or better (required) icon.library version 36 or better (required) nofrag.library version 2 or better (required) diskfont.library version 36 or better (required) iffparse.library version 37 or better (required) powerpacker.library version 35 or better (optional) If you have the nofrag.library v2.2 please use it instead of v2.1. Version 2.2 is identical in function except that it has some bugs removed. When you also install the powerpacker.library v35++ you are able to load and/or save crunched binary files. I have had a user saying that GadToolsBox requires 70000 bytes of stack! I'm using 4096 bytes and haven't encountered any problems yet. If you have problems try to up the stack size you are using. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 6) Starting GadToolsBox » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» You can start GadToolsBox from either the Shell or the Workbench. To start GadToolsBox from the Shell you must type the following: GadToolsBox [filename] Where filename is an optional name of a previously created file which you want to edit. To start GadToolsBox from the workbench you must either double-click the program it's icon or one of the ".G" icons. When you have started GadToolsBox without any arguments the program opens a screen in the workbench resolution with a little window on it. This window is the "drawing board" on which you design your GUI. When it's started with a ".G" file as an argument the contents of the file will be in the window. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 7) Making a Gadget » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» To make a gadget is quite simple. Move the mouse pointer to the place where you want the top-left of the gadget to be. Now click the left mouse-button once and move the mouse. You'll see a box which will size according to your mouse moves. When the box is the size you want it click the left mouse button again. Now a window pops up which allows you to edit the gadget kind specifics ( refer to the "Gadget Kind Requester" for more info) After you have edited the gadget specifics click on OK and the gadget is on the window ready to be played around with. NOTE: When you are making a CheckBox, Mx or GetFile gadget the box appears after the first mouse-click. This is because these kinds of gadgets have a fixed size. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 8) Program Menus » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox uses a set of menus to let you control the program. The program supports multi-selection of menus although in some cases the multi- selection loop will break. The following describes each menu and it's items. »»» 8.1) The Project Menu About............. This opens a little window with some information about the copyright, author and memory status. Just click on the Continue gadget to get rid of it. New............... Reset's the program to the default deleting every change made sofar. When there are changes made that are not saved yet the program asks for confirmation. NOTE: All windows currently in memory will be deleted by this!!! Load.............. This opens the FileRequester in which you can select the file you want to load. The program can only load binaries created by GadToolsBox. Any other kind of file will simply be refused. NOTE: When a requester pop's up telling you that the file uses a monitor that isn't available it means that either you have not added the monitor by clicking on the specific monitor icon in the MonitorStore drawer of your Extras disk or you don't have the ECS chips installed. If this is the case the program just opens a screen in the standard resolution. Save.............. This will save the GadTools interface to the default file name. NOTE: The default name is "unnamed.g". When the crunch gadget is enabled (Preferences) and the powerpacker.library was opened successfully a window opens which will keep you informed about the crunch progress: Crunched » This indicates the percentage of the file crunched sofar in a human readable form and a graphical form. Saved » This indicates the percentage of the file saved by the crunching sofar in a human readable form and a graphical form. Stop » Clicking on this gadget will stop the crunching. NOTE: The file will still be saved only it won't be crunched. Save As........... This opens the FileRequester in which you can select the path and file name under which the GadTools interface is saved. Generate Source... C.............. This opens the FileRequester in which you can select the path and file name under which the generated C source will be saved. Assembler...... The same as C only the generated source will be in 68000 Assembler. Preferences....... This opens the preferences window. In this window you will see the following gadgets: Static Data » When this is switched on the C source will only contain static data and routines. The assembler will not export (XDEF) any globals RAW Asm source » When this is switched on the Assembler source generated can be assembled without the OS 2.0 headers. Co-ordinates » If you want the mouse coordinates to be displayed constantly you should switch this gadget on. NOTE: The displayed coordinates are relative to the top-left corner of the window. Write Icon » When this is switched on every binary written by GadToolsBox has an icon to accompany it. Gen. OpenFont » When this is switched on and the used font is a diskfont the source generator automatically generates code that opens/closes the font. NOTE: This has no effect if the "Adapt. Font" option (see below) is turned on. GZZ Adjust » When this is switched on the program automatically will change the gadget positions when the WFLG_GIMMEZEROZERO flag is set or cleared. When it's on and you switch the WFLG_GIMMEZEROZERO flag on or off the gadget and text positions will visibly stay the same. Close WBench » This allows you to let the program try to close the workbench screen upon startup. NOTE: When this is selected and you press "Use" the program will also try to close the workbench screen. Crunch » When this gadget is checked and the powerpacker.library V35+ has been opened successfully the saved binaries will be crunched. This can save upto 85% of the original size. Please note that you must have the powerpacker.library v35++ in your LIBS: for this. Password » When this gadget is checked and the "Crunch" gadget is checked you can protect your creations with a password. Note that this is only available with crunched binaries! Speedup Buffer » This cycle gadget allows you to set the preferred speedup buffer that should be used by the powerpacker library to crunch the binary files. Crunch Depth » With this cycle gadget you can set the crunch depth to use. Adapt. Font » When this gadget is checked the source generator will generate source that automatically adapts the gadget, bevel-box and window sizes and positions to the active font. Use Amiga.Lib » When this is switched on the assembler source generator creates XDEFs to the _LVO table from the amiga.lib instead of using the constants normally generated. Use SysFont » When this is switched on the generated font adaptive source will use the system default font instead of the screen font. Note that the screen font can be a proportional font. The font adaptive code might not always have a pixel-perfect result with proportional font's although I have not seen it fail yet. Overwrite » With this switched on GadToolsBox won't pop up the requester telling you that a file you want to save to already exists. Instead it will overwrite the file immediately ASL FReq » When this is switched on GadToolsBox will use the ASL FileRequester which enables you to use the "Magic File Requester" and all other sorts of ASL patches you desire. Pragmas » This will tell the C Source Generator to include the pragma headers to. It will use SAS names when the "Aztec C" switch is of and Manx names when it's on. Aztec C » When you use the Aztec compiler you _MUST_ turn this switch on before source generation. This will tell GadToolsBox to use a special type cast in the generation of the gadget tags. Templates » This will tell the source generator to also generate a template file. Note that the templates file will only be generated when you turn the option from below on. Gen. Handler » This will tell GadToolsBox to also generate a IDCMP handler. Currently only the C source generator supports this. Save » Opens the FileRequester in which you can select the path and name under which the preferences are saved. Load » Opens the FileRequester in which you can select a GadToolsBox preferences file to load. NOTE: The program does NOT check if it's really a GadToolsBox preferences file you are loading so loading a strange file can have wierd results Use » This tells GadToolsBox to use the preferences you have set. CANCEL » This cancels the operation. Close Workbench... This will try to close the workbench screen so that you can use the memory it took up. When this item reads Open Workbench it will try to open the Workbench screen again Quit.............. This will quit the program after asking for confirmation »»» 8.2) The Gadgets Menu In the following lines I talk a lot about "selected gadgets". When I say selected gadgets I mean gadgets that are selected to perform a certan action with. To select gadgets you must do the following simple thing: Click on the gadget. When a box appears arround the gadgets it means that it is selected. When the box dissapears it means that the gadget is not selected. To select more than one gadget you must keep the shift key pressed whilst clicking on the gadgets. Kind.............. This item has the program supported gadget kinds as sub-items attached to it. Selecting any of these sub- items will change the editing for that gadget kind. The first kind "GETFILE" is a custom gadget which is the same as the gadget which you find in the "Fountain" program left of the filename gadgets. This gadget should be used to let the user open the FileRequester to select the file/path instead of typing it in the string gadget. Add............... GadToolsBox will only allow you to add gadgets to the window when this menu-item is checked. This will allow you switch off the add mode and click in your window without accidentally creating a gadget. This item should also be turned on before you can select gadgets to perform operations like edit, move etc. on. Move.............. This will allow you to move all currently selected gadgets to another place. When this is selected you will see a rubber-band box which overlaps all selected gadgets. Now move this box to the place you want the gadgets and click on the left mouse button to confirm. Size.............. This asks you to click on the gadget that you want to re-size. When you click on a gadget a box is drawn around the gadget. Just move the mouse to adjust the size of the box and click on the left mouse-button to confirm the size. NOTE: The minimum possible size depends on the gadget kind and the font size. Copy.............. This will allow you to make a copy of all selected gadgets. When this is selected you must do the same as with moving gadgets. Delete............ When you select this a requester pops-up to ask you if you are sure that you want to delete those gadgets. Just click on "Delete" in that requester and all the selected gadgets are gone. Edit.............. This will bring up the editor of all gadgets that where selected. Please refer to the "Gadget Kind Requester" for more info about these requesters. Join.............. This will Join ListView gadgets and String gadgets. When you have selected, for example, three listview gadgets and two string gadgets the two string gadgets will be joined to listview gadgets. This joining means that the String gadget will be filled with the entry name of a clicked entry in the ListView gadget. NOTE: Due to a bug (or something) the GadTools library requires the String Gadget to be of the same Width as the ListView gadget. This is done automatically by the program and it cannot be stopped. Also the GadTools library will force the string gadget directly below the ListView gadget. This also cannot be stopped. Split............. This will do the opposite of Join. This will split up all selected "joined" gadgets. NOTE: After the Gadgets have been split the string Gadget returns to the place where it has been originally drawn. Align Left........ This asks you to click on the gadget that has the left edge you want the other selected gadgets to have. When you have clicked on the gadget all the selected gadgets will inherit the same left edge. Align Right....... The same as "Align Left" only the gadget right-edge is used to align the gadgets. Align Top......... The same as "Align Left" only the gadget top-edge is used to align the gadgets. Align Bottom...... The same as "Align Left" only the gadget bottom-edge is used to align the gadgets. NOTE: This may not work for ListView and Palette gadgets because GadTools sizes this gadget in the area given by you when first drawn. This means that the gadget is almost always smaller than you have drawn it. Close Size........ This does the same as the "Align" routines mentioned above only this time it will clone the size of the gadget. The MX, CHECKBOX and GETFILE gadgets will not be affected by this. Set X Spacing..... This will pop up a requester in which you can set the size in pixels of the horizontal spacing of the gadgets. When the number is entered the selected gadgets will all have an equal distance horizontally from eachother. Set Y Spacing..... The same as with "Set X Spacing" only the vertical positions are affected. Spread X.......... When you have selected this you will see a vertical line which can be moved using the mouse. This line is used to set the left coordinate of the spread area. Just click on the left mouse button to confirm it's place. Now you must do the same thing, positioning the line, to set the right coordinate of the spread area. When you are done all selected gadgets are evenly spread in the area you selected. Spread Y.......... The same as with "Spread X" only now the gadgets will be spread vertically in the window and you must set the top and bottom coordinate of the spread area. »»» 8.3) The Window Menu New............... This will add a new window to the windows already in memory. NOTE: Only the currently selected window is visible on the screen. Delete............ This will pop-up a window in which you must select the window you want to delete. The following gadgets are in the window. ListView gadget » This gadget lists the windows currently in memory. Just select the name of the window you want to delete. OK » Clicking on this gadget will delete the selected window including all gadgets, menus, texts and boxes that where attached to it. NOTE: You can also double-click the project window name to select it. CANCEL » This will cancel the operation. Other............. This brings up the window-selector again in which you can select the window you want to edit. Edit Data......... This brings up a small requester in which you can set some data for the current window. In the requester the following gadgets can be found: Project name » In this gadget you can give the window a name. You should name all windows so it's easy to keep them apart. NOTE: This name is used by the source generator. Start ID from » In this gadget you can type the GadgetID from which you want the program to start numbering the ID's of the gadgets. This can come in very handy if you plan to make windows that share a global IDCMP port. Min X Size » In these gadgets you can type the Min Y Size » minimum/maximum dimensions that the Max X Size » can be sized to with the sizing Max Y Size » gadget. The program will try to prevent you from entering wrong dimensions. NOTE: The tags for these positions will only be generated when the window has a sizing gadget. OK » This will set the desired changes. CANCEL » This will cancel the operation. Print Info........ This will open the Project Selection window again. Now you can select the project of which you want to print the information or click on OK right away to get a printout of all projects. In the printout the gadget id's, gadget array constants, number of gadgets kinds, number of menus, number of texts and the number of BevelBoxes are listed. GadToolsBox first checks to see if your printer is online and has paper before it starts to print the projects. Note however that this check only works with parallel printers. Edit Flags........ This opens a requester in which all window flags are listed using CheckBox gadgets. Just (de)select the flags you want. Clicking on OK will set these flags and CANCEL cancels the operation. NOTE: Only the SIZEGADGET, DRAGBAR, DEPTHGADGET, CLOSEGADGET, SIZEBRIGHT, SIZEBBOTTOM, GIMMEZEROZERO, BORDERLESS and BACKDROP flags are (un)set on the edit window. The rest of the flags will only turn up in the generated source code. NOTE: When you set the WFLG_BACKDROP flag in the window The program will automatically re-size the window to the same size as the current screen. You can also switch the size gadget on or off by pressing the F10 key while editing. Edit IDCMP........ This opens a requester in which all window IDCMP flags are listed using CheckBox gadgets. Just (de)select the flags you want. Clicking on OK will set these flags and CANCEL cancels the operation. NOTE: The GadTools specific IDCMP flags will always be set according to the kind of gadgets on the window. The Three HIGHLIGHTED flags you see on the bottom of the window are three of the flags much used by some gadtools gadgets. If you need them for your own purpose then you will have to check them to to get them to appear in the event-handler The flags are IDCMP_INTUITICKS, IDCMP_MOUSEBUTTONS and IDCMP_MOUSEMOVE. See the "The IDCMP handler" chapter for more info. Edit Tags......... This will open a window in which some special window tags can be edited. In the window you'll see the following gadgets: InnerWidth » When this gadget is selected the generated source will use the WA_InnerWidth Tag instead of the WA_Width Tag. The value next to the gadget is the current window InnerWidth. InnerHeight » When this gadget is selected the generated source will use the WA_InnerHeight Tag instead of the WA_Height Tag. The value next to the gadget is the current window InnerHeight. MouseQueue » When this gadget is selected the source will contain the WA_MouseQueue tag. In the integer gadget next to this gadget you can type the amount of MouseQueue's. NOTE: This value cannot be smaller than 1 RptQueue » When this gadget is selected the source will contain the WA_RptQueue tag. In the integer gadget next to this gadget you can type the amount of RptQueue's. NOTE: This value cannot be smaller than 1. AutoAdjust » Selecting this will cause the generated source to contain the WA_AutoAdjust tag. Zoom » When this gadget is selected the WA_Zoom Tag is generated in the source code. In the Left, Top, Width, Height gadgets you can type the Window it's alternate positions. NOTE: This gadget is only enabled when the window sizing gadget is turned off. This can be done in the "Edit Flags" requester. Default Zoom » This will tell GadToolsBox to generate source that will calculate the zoom positions at run time. The Zoom positions will be the same as the Zoom positions of the preferences programs. NOTE: This gadget is only enabled when the window sizing gadget is turned off. This can be done in the "Edit Flags" requester. WindowTitle » Type the Window title in here. If this Gadget is empty the WA_Title tag will not be generated. ScreenTitle » Type the Screen title in here. If this Gadget is empty the WA_ScreenTitle tag will not be generated. OK » This will set the desired changes and resume to editing. CANCEL » This will cancel the operation. Edit Grid......... This will open a window to edit the grid size. The grid, which is invisible, is used to let the gadgets be moved and sized with a specific amount of pixels at the time. This can be VERY useful to get your gadgets the same size and in line with each other. If you for example have both the X and Y grid spacings on 4 the gadget-box will size/move 4 pixels at the time but only when the mouse has moved four pixels from it's previous position. If this sounds a bit confusing you should try it out. It makes it a hell of a lot easier to place/size the gadgets on the right spot. In the grid window you will see the following gadgets: Grid X Size : Type the X spacing of the grid in here. NOTE: This may not be less than 2 or more than 100. Grid Y Size : Type the Y spacing of the grid in here. NOTE: This may not be less than 2 or more than 100. Grid On : When this gadgets is checked the grid is switched on. OK : Clicking on this gadget will set the desired grid changes. CANCEL : This will cancel the operation. NOTE: When the grid is switched on all coordinates are updated according to the grid sizes! Edit Offsets...... This will open a window to edit the border offsets. The border offsets are used to create a working space within the window borders. This means that if you have set the horizontal offset to 4 and the vertical offset to 2 the gadgets cannot be moved/sized closer than 4 pixels to the window left and right borders and not closer than 2 pixels to the window top and bottom borders. Horiz. offset : Type the offset in pixels you want to have from the left and right window borders here. NOTE: This may not be less than 0 or more than 20. Vert. offset : Type the offset in pixels you want to have from the top and bottom window borders here. NOTE: This may not be less than 0 or more than 20. Offset On : When this gadgets is checked the offsets are switched on. OK : Clicking on this gadget will set the desired offset changes. CANCEL : This will cancel the operation. Texts............. Add........... This will open the IntuiText editor window. In this window you'll find the following gadgets: Enter Text » In this gadget you must type the actual text you want. JAM1 JAM2 COMPLEMENT INVERSVID » These four gadgets determine the drawmode used to paint the text in the rastport. FrontPen » With this palette gadget you can select the FrontPen (text) color which is used to draw the text. BackPen » With this palette gadget you can select the BackPen (background) color which is used to draw the text. OK » This gadget will close the window and let you position the text in the edit window. Clicking on the left mouse-button will confirm the place. NOTE: You can also double-click the text to select it. CANCEL » This will cancel the operation. Now you must move the text with mouse to where you want it and click the left mouse-button. To get your text in The middle of the window horizontally you must move the text to the vertical position you want it and press the F1 key. Then the text will be moved to the center of the window. Edit.......... This will put up the text selection window if there was more than one text added. In this text selection window you'll see the following gadgets: Available Texts » In this ListView gadget the texts currently in memory are listed. Clicking on the text will select it. OK » This will select the text for the operation that has to be done. CANCEL » This will cancel the operation. Now the IntuiText Editor opens with the selected text already in it. Now you can edit the text the way you want. Delete........ This will put up the text selector again if more than one text is added to the window. Just select the text and it's gone. NOTE: When only one text is available the text is deleted immediately. Move.......... The text selector pops up again if.... Now you can move the text around in the edit window. Just click on the left mouse-button to confirm it's new place. You can center it with F1 of course (see Add a text). BevelBoxes........ Add............ When this item has been selected the program will ask you to click on the place where you want the top-left corner of the BevelBox. When clicked you can drag a box just like when you are editing gadgets. Just click on the left mouse button again to confirm that the box is the way you want it. NOTE: By default the box is "raised". Look at the "Flip BevelBox" item to get it "recessed." Move........... This works the same as moving a gadget with the exception that multi-selection isn't available. Size........... This works the same as sizing a gadget with the exception that multi-selection isn't available. Delete......... This works the same as deleting a gadget with the exception that multi-selection isn't available. Flip Recessed.. By default all created BevelBoxes are "raised". To get a BevelBox "recessed" you must select this item and then ( when the program asks you to ) click inside the box and it will be recessed. Flip DropBox... This ask you to click in the box you want to make into a Icon Drop box or in the Icon Drop box you want to flip back into a normal box. The usage of the Icon Drop box is described in the "User Interface Style Guide". »»» 8.4) The Screen Menu Palette........... This will open the palette editor. In the palette editor you'll see the following gadgets: Red » With this slider gadget you can adjust the Red intensity of the currently selected color. Green » With this slider gadget you can adjust the Green intensity of the currently selected color. Blue » With this slider gadget you can adjust the Blue intensity of the currently selected color. Colors » This gadget consists of 2, 4, 8, 16 or 32 colored gadgets and a color indicator left of it. Just click on the color you want to edit to switch to editing that color. OK » This will close the Palette editor and set the desired colors on the edit screen. Load » This opens the file requester in which you can select the name of an IFF-ILBM file from which you wish to load the colors. Save » This opens the file requester in which you can select a name. The selected colors will then be saved to an IFF-ILBM file. The generated IFF-ILBM file is compatible with DPaint IV it's palette files. Reset » This will reset all colors to what they where before the palette editor opened. CANCEL » This will first reset all colors and then exit the palette editor. Load WB Colors.... This will load the workbench colors from the file "ENV:sys/palette.ilbm". Note that this will change. Get Font.......... This will open the FontSelector for you to select a new font. To select a font you must first click on the desired font name and then enter or click on the desired font height. Clicking on Ok will set the font on the screen and clicking on Cancel will cancel the operation. NOTE: When the "Adapt. Font" switch in the Preferences window is switched on then this item cannot be selected. Set DriPens....... This will open the DriPen editor. DriPens are the pens which the system uses to give that special new OS 2.0 look to the window and gadgets etc. The following gadgets are in the DriPen editor: Pens » This cycle gadget is used to select the DriPen you want to edit. The following DriPens are available: DETAILPEN This is the same as the standard NewScreen detailpen. BLOCKPEN This is the same as the standard NewScreen blockpen. TEXTPEN This is the pen used to draw the gadget text and the Window title. SHINEPEN This is the pen used to draw the "light-side" of the gadget and window borders. SHADOWPEN This is the pen used to draw the "dark-side" of the gadget and window borders. FILLPEN This is the pen used to backfill the gadget when it's clicked and the window border when it's active. FILLTEXTPEN This is the pen used to draw the text of a clicked gadget and the Window title of an active window. BACKGROUNDPEN This pen is used to fill the background of an unselected gadget. HIGHLIGHTTEXTPEN This pen is used to draw the text of a gadget with the HighLight switch turned on. Palette » This gadgets contains the current screen colors. Clicking on a color will set the currently displayed DriPen in the Cycle gadget to that colors. OK » Clicking on this gadget will set the desired DriPens. CANCEL » This will cancel the operation. Edit Tags......... This will open the screen tags window. In this window the following gadgets are located: AutoScroll » With this gadget checked the generated source will contain the SA_AutoScroll tag. Type » This cycle gadget has the supported screen types in it: CUSTOMSCREEN The generated source will contain the screen tags and data. The window will use this screen to open on. WBENCHSCREEN The generated source will not contain the screen tags and data. The window will use the Workbench screen to open on. CUSTOMSCREEN The generated source will not contain the screen tags and data. The window will use the default public screen to open on. Title » In this string gadget you can type the title of the screen when no windows on the screen are activated. NOTE: When this gadget is empty the Tag will no be generated in the source. OK » This will set the desired tags. CANCEL » This will cancel the operation. Change Type....... This will pop up the Screen Type requester which enables you to change the screen you are working on. NOTE: When you have (for example) edited gadgets on a hires screen and you change the resolution to a lores screen the gadgets that are located outside the lores screen range (gadget left-edge > 320) cannot be reached anymore (unless you switch back to the hires screen of course)! The screen mode requester has the following gadgets: Available modes » In this gadget you see a list of available display modes. Just click on the desired display mode. NOTE: The program currently only checks for the availability of the LORES, HIRES, SUPER-HIRES, PRODUCTIVITY and A2024 modes for the PAL, NTSC, VGA and A2024 monitors. Also the interlace modes are supported except for the A2024 modes because they do not support interlace. THE VGA AND A2024 MODES MAY ONLY BE USED WITH VGA/ MULTISYNC OR A2024 MONITORS USAGE OF THESE DISPLAY MODES ON A STANDARD RGB MONITOR MAY RESULT IN SERIOUS DAMAGE TO THE MONITOR. Min. Width » This gadget shows the minimum width the screen can have. Min. Height » This gadget shows the minimum height the screen can have. Max. Width » This gadget shows the maximum width the screen can have. Max. Height » This gadget shows the maximum height the screen can have. Width » In this gadget you can type the width of the screen you want to have. NOTE: This cannot be smaller/larger than the values described above. Height » In this gadget you can type the height of the screen you want to have. NOTE: This cannot be smaller/larger than the values described above. Depth » This slider gadget lets you adjust the screen depth. The screen depth determines the amount of available colors. Depth = 1, Colors = 2 Depth = 2, Colors = 4 Depth = 3, Colors = 8 Depth = 4, Colors = 16 Depth = 5, Colors = 32 OK » When this gadget is clicked the program will try to open the desired screen and start the editing. NOTE: You can also double-click the desired display mode to select it. CANCEL » Clicking on this gadget cancel the operation. »»» 8.5) The Menus Menu Edit.............. This will open the Menu Editor window in which you can edit a complete menu-strip. Refer to the "Menu Requesters" chapter for more information. Test.............. This will set-up the menus, items and subitems to be tested by you. When the message "TESTING MENUS! ESC TO QUIT..." is printed in the screen and window title bar you can browse through the menus like you normally do. You must press the ESC (escape) key to resume to editing. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 9) Gadget Kind Requester » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox supports all gadget kinds which all have their own window in which the gadget kind specifics can be edited. The following gadgets can be found in nearly all gadget kind requesters and are there for the same reason: Text » In this gadget you can type the text which is displayed with the gadget. Label » In this gadget you can type the source code label which is used to define some important values in the generated source. Refer to the "Generated Source" chapter for more information. Underscore » When this gadget is selected the character in the GadgetText preceded by a '_' will be underlined which specifies the keyboard shortcut. Disabled » When this gadget is selected the gadget will be disabled. The gadget will only be disabled in the generated source. NOTE: Not all gadgets support this switch. High Label » This tells that the GadgetText must be drawn in the highlight text color. NOTE Not all gadgets support this switch. Text Place » This cycle gadget determines where that gadget text is placed. The possibilities are IN, LEFT, RIGHT, ABOVE and BELOW. NOTE: Only the Button gadget supports IN. OK » This gadget will add the gadget with the selected specifics to the edit window or set the desired changes. CANCEL » This will cancel the operation. Following is a description of the extra specifics of the different gadget kinds supported by GadToolsBox. »»» 9.1) The CheckBox Gadget Checked » When this gadget is switched on it tells that the gadget is checked by default. »»» 9.2) The Integer Gadget Placement » In this cycle gadget there are three choises. LEFT, CENTER and RIGHT. These represent where the cursor should appear when the gadget is activated. ExitHelp » When this gadget is selected you will get a GADGETUP message with 0x5F as code to indicate that the user has pressed the HELP key in the gadget. TabCycle » When this gadget is selected the integer gadget will cycle to the next/previous integer/string gadget when the user presses TAB or SHIFT+TAB. MaxChars » You must type the maximum possible digits plus one that may be typed in the gadget. NOTE: This cannot be smaller than 2 Number » Type the default number in this gadget that the resulting gadget has in it. »»» 9.3) The ListView Gadget Read Only » When this gadget is selected the ListView Gadget will be read-only. NOTE: The ListView will only be read-only in the generated source. ShowSelected » When this gadget is selected the active (clicked) entry in the listview gadget will be shown below the listview gadget NOTE: This option is only available if the ListView isn't ReadOnly. Spacing » Type the extra number of pixels GadTools must insert between the listview entries. NOTE: This value cannot be smaller than 0. Scr. Width » Type the width of the scroller gadget next to the ListView gadget in here. NOTE: This value may not be smaller than 16 Labels » This is a ListView Gadget combined with a string gadget. In the string gadget you can type the entries that the listview must have. To edit an entry you must first click on the entry in the listview and then edit the entry in the string gadget. NOTE: The "!!ACTION GADGET!!" entry is always in the list and cannot be removed or edited. This entry is necessary to keep the ListView selectable in the program. This entry will of course not showup in the source generated. Remove » This gadget enables you to remove entries from the list. Just click on the entry in the ListView gadget and then on this gadget and the entry is gone. Up » With this gadget you can move the selected label one place up in the list. Down » With this gadget you can move the selected node one place down in the list. »»» 9.4) The Mx Gadget Spacing » In this gadget you can type the spacing in pixels that GadTools should insert between the items of the MX gadget. Labels » This is a ListView Gadget combined with a string gadget. In the string gadget you can type the entries that the mx must have. To edit an entry you must first click on the entry in the listview and then edit the entry in the string gadget. NOTE: You must enter at least two entries for the MX gadget. Remove » This gadget enables you to remove entries from the list. Just click on the entry in the ListView gadget and then on this gadget and the entry is gone. Up » With this gadget you can move the selected label one place up in the list. Down » With this gadget you can move the selected node one place down in the list. »»» 9.5) The Cycle Gadget Labels » This is a ListView Gadget combined with a string gadget. In the string gadget you can type the entries that the cycle must have. To edit an entry you must first click on the entry in the listview and then edit the entry in the string gadget. NOTE: You must enter at least two entries for the Cycle gadget. Remove » This gadget enables you to remove entries from the list. Just click on the entry in the ListView gadget and then on this gadget and the entry is gone. Up » With this gadget you can move the selected label one place up in the list. Down » With this gadget you can move the selected node one place down in the list. »»» 9.6) The Palette Gadget Width » In this gadget you can type the width of the color indicator if you want one on the left of the gadget. NOTE: any value smaller than 9 will indicate that you do not want a color indicator. Height » In this gadget you can type the height of the color indicator if you want one above the gadget. NOTE: any value smaller than 9 will indicate that you do not want a color indicator. »»» 9.7) The Scroller Gadget Immediate » When this gadget is selected you will hear any IDCMP_GADGETDOWN message through the window IDCMP port that this gadget generates. RelVerify » When this gadget is selected you will hear any IDCMP_GADGETUP message through the window IDCMP port that this gadget generates. Horizontal Vertical » With this gadget you can determine whether this gadget can be moved horizontally or vertically. Top » In this gadget you can type the top of the area the scroller is used for. Total » In this gadget you can type the total of the area the scroller is used for. Visible » In this gadget you can type the visible part of the area this scroller is used for. Arrows » In this gadget you can type the size in pixels of an arrow. NOTE: Specifying a value smaller than 8 says you don't want arrows. »»» 9.8) The Slider Gadget Immediate » When this gadget is selected you will hear any IDCMP_GADGETDOWN message through the window IDCMP port that this gadget generates. RelVerify » When this gadget is selected you will hear any IDCMP_GADGETUP message through the window IDCMP port that this gadget generates. Horizontal Vertical » With this gadget you can determine whether this gadget can be moved horizontally or vertically. Min » In this gadget you can type the minimum value of the slider. Max » In this gadget you can type the maximum value of the slider. Level » In this gadget you can type the initial level the slider must have. Level Size » In this gadget you can type the maximum amount of characters that may be used to print the slider level. Format » A formatting string ala RawDoFmt() which specifies the way the slider level should be printed. NOTE: When this is omitted the slider level won't be printed. Lev. Place » With this gadget you can specify where GadTools is to print the slider level. The possibilities are LEFT, RIGHT, ABOVE and below. »»» 9.9) The String Gadget Placement » In this cycle gadget there are three choises. LEFT, CENTER and RIGHT. These represent where the cursor should appear when the gadget is activated. ExitHelp » When this gadget is selected you will get a GADGETUP message with 0x5F as code to indicate that the user has pressed the HELP key in the gadget. TabCycle » When this gadget is selected the string gadget will cycle to the next/previous integer/string gadget when the user presses TAB or SHIFT+TAB. MaxChars » You must type the maximum possible characters plus one that may be typed in the gadget. NOTE: This cannot be smaller than 2. String » Type the default string in this gadget that the resulting gadget has in it. »»» 9.10) The Number Gadget NOTE: During the editing the number gadget can be selected to be moved, sized, deleted etc. This is only possible in the program! The gadget generated in the source will NOT respond to clicking in it! The NUMBER kind of gadget is a READONLY gadget which is used to display numbers. Border » When this gadget is checked it means that a "recessed" border will be drawn around the gadget. Number » In this gadget you can type the default number that the gadget should display. »»» 9.11) The Text Gadget NOTE: During the editing the text gadget can be selected to be moved, sized, deleted etc. This is only possible in the program! The gadget generated in the source will NOT respond to clicking in it! The TEXT kind of gadget is a READONLY gadget which is used to display informative texts. Border » When this gadget is checked it means that a "recessed" border will be drawn around the gadget. NOTE: When you did not enter a text in the "Def. Text" gadget the border is switched on no matter what this gadget says. CopyText » When this gadget is checked the gadtools.library will make it's own private copy of the text. Def. Text » In this gadget you can type the default text that the gadget should display. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 10) Menu Requesters » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox uses three (actually two) windows to let the user edit complete menu-strips. Following is a description of those windows. »»» 10.1) The Menu Requester This requester is used to edit the menus. In the window you'll see the following gadgets: Menus » This listview gadget contains the names of the menus currently in memory. Below this ListView gadget a string gadget is located which is used to enter/edit the menu names. To add a new menu to the list you must enter it's name in this string gadget and press return. To edit a menu name you must first click on the name in the listview gadget and then edit the name in the string gadget. Disabled » This CheckBox gadget tells GadToolsBox whether you want the menu to be disabled or not. ItemEd » This gadget must be clicked when you want to add some items to a menu. To do this you must first click on the menu name in the listview gadget which you want to edit items for and then click on this gadget. If all goes well you will be presented with the "(Sub)Item Requester" (see below). Delete » When you want to delete a menu you must click on it's name in the listview gadget and then click on this gadget. Then a requester pops up asking for confirmation. NOTE: Deleting a menu with items attached to it will also delete those items. Up » This gadget will put the selected menu one place up in the list. Down » This gadget will put the selected menu one place down in the list. DONE » Clicking on this gadget will close the requester and resume to gadget editing. »»» 10.2) The (Sub)Item Requester This requester is used to edit (sub)items for a specific menu. This requester is the same for editing items and subitems. The following gadgets are in the window: (Sub)Items » This listview gadget contains the names of the (sub) items currently attached to the menu. Below this ListView gadget a string gadget is located which is used to enter /edit the (sub)item names. To add a new (sub)item to the list you must enter it's name in this string gadget and press return. To edit a menu name you must first click on the name in the listview gadget and then edit the name in the string gadget. Checkit » This will turn the intuition CHECKIT flag on/off for the (sub)item. Disabled » This CheckBox gadget tells GadToolsBox whether you want the (sub)item to be disabled or not. Checked » This will turn the intuition CHECKED flag on/off for the (sub)item. MenuToggle » This will turn the intuition MENUTOGGLE flag on/off for the (sub)item. ShortCut » You can add a keyboard shortcut for the (sub)item by entering the shortcut key in this gadget. NOTE: The program will detect it when you try to use a shortcut key that you have already used. Source Label » In this gadget you can type the suffix of the label that the routine for the edited item will have. For example: When your window is called "FileRequester" and you type "Open" in this gadget the routine label called by this item will read "FileRequesterOpen()". See the "The IDCMP handler" chapter for more information. BarLab » When you click on this gadget a separator bar (NM_BARLABEL) is inserted in the list automatically. SubEd » This gadget must be clicked when you want to add some subitems to a item. To do this you must first click on the item name in the listview gadget which you want to edit subitems for and then click on this gadget. If all goes well the requester will switch to subitems editing. NOTE: This gadget is disabled when the requester already is in the subitem mode. Delete » When you want to delete a (sub)item you must click on it's name in the listview gadget and then click on this gadget. Then a requester pops up asking for confirmation. NOTE: Deleting a item with subitems attached to it will also delete those subitems. Up » This gadget will put the selected (sub)item one place up in the list. Down » This gadget will put the selected (sub)item one place down in the list. MutEx » Clicking on this gadget enables you to set the Mutual- Exclusion of (sub)items. When you click on it you will see the message "DRAG_SELECT ITEMS TO EXCLUDE" in the title bar of the item editor window. Now you must press the right mouse button to select the items to exclude. The item that excludes the items is always ghosted. To select the items you must move the mouse pointer to the item you want to exclude and press the left mouse button whilst holding down the right button. All checked items will be the items that are excluded by the ghosted item. DONE » Clicking on this gadget will close the requester and put you back in the menu requester. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 11) The Generated Source » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» The source output of GadToolsBox is divided into two separate files. The first file is a header (.h|.i) containing EXTERNS or XREF'S to the data in the generated main source and CONSTANTS for the gadget ID's and the positions of the gadgets in the Gadget Array. The second file (.c|.s) (from here on referred to as "main file") contains all data and routines to set-up things. From here on when I refer to <Project_Name> I mean the name entered in the "Edit Data" requester from the Window menu and when I refer to <Gadget_Label> I mean the name you have typed in the "Label" gadget of one of the gadget kind requesters. When I refer to <Menu_Label> I mean the label you have typed in the "Source Label" gadget of the (Sub)Item editor. In the main file the following routines are generated: »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » long SetupScreen( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» This routine will open or lock the screen and get it's visual info. When requested (see Preferences Menu) this routine will also open the font. Also it will setup the boopsi image for the GETFILE gadget when such a gadget is used. This routine can return one of the following errors: 0 = No errors. 1 = Could not open or lock the screen. 2 = Could not get the screen it's visual info. 3 = Could not set-up the GETFILE boopsi class. 4 = Could not get a GETFILE boopsi object. 5 = Could not open the font. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » void CloseDownScreen( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» This routine will free the resources taken by "SetupScreen()". You must still call this routine when "SetupScreen()" failed to close and free the resources that didn't fail to open!!! »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » long Open<Project_Name>Window( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» There are as much of these routines as there are Project Windows in the file you have generated. These routines will set-up the gadgets and menus and open the window. These routines can return one of the following errors: 0 = No errors. 1 = Could not create a gadget context. 2 = Error during the gadget creation. 3 = Could not create the menus. 4 = Could not open the window. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » void Close<Project_Name>Window( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» There are as much of these routines as there are Project Windows in the file you have generated. These routines will free all resources that the "Open<Project_Name>Window()" routine has taken. You must still call this routine if "Open<Project_Name>Window()" has failed! »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » void <Project_Name>Render( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» Each Project Window which has texts and/or BevelBoxes attached to it will have a routine which renders these texts and/or BevelBoxes in the window. This routine must also be called by the user program upon receiving a IDCMP_REFRESHWINDOW message at the window port. When such a message is received this routine must be called between the GT_BeginRefresh() and GT_EndRefresh() calls. Here is a small example of what I mean: while( 1 ) { WaitPort( <Project_Name>Wnd->UserPort ); while( imsg = GT_GetIMsg( <Project_Name>Wnd->UserPort )) { Class = imsg->Class; GT_ReplyIMsg( imsg ); switch ( Class ) { case IDCMP_REFRESHWINDOW: GT_BeginRefresh( Project_Name>Wnd ); <Project_Name>Render(); /* re-draw texts and boxes */ GT_EndRefresh( <Project_Name>Wnd, TRUE ); break; ..... } } } Note that the above is automatically done by the generated IDCMP event-handler. The main file also has the following globals defined which are shared by all project windows: struct Screen *Scr; A pointer to the opened/locked screen APTR VisualInfo; A pointer to the visual info The following globals are only generated when the file contains gadgets or menus and when the OpenFont routine is generated and when the window must have a zoom gadget: struct Gadget *<Project_Name>GList; A pointer to the created gadgets struct Menu *<Project_Name>Menus; A pointer to the created menus WORD <ProjectName>Zoom[4]; The window alternate positions struct TextFont *Font; A pointer to the opened font Also generated are pointers for each project window that is in memory. Also the window title is generated as a global pointer. These pointer are generated as follows: struct Window *<Project_Name>Wnd; A pointer to the window; UBYTE *<Project_Name>Wdt; A pointer to the window title; When you have generated source for the Workbench or Default Public screen a global is generated which is a pointer to the name of the public screen to open on. It is generated as follows: When generated for the Workbench screen: UBYTE *PubScreenName = "Workbench"; When generated for the Default Public screen: UBYTE *PubScreenName = NULL; This will allow you to change the name of the public screen to open on with out having to hack in the generated source. Four words are generated for each window. These words contain the window it's left and top-edge and the window it's width and height. These globals are build as follows: UWORD <Project_Name>Left; Window left-edge UWORD <Project_Name>Top; Window top-edge UWORD <Project_Name>Width; Window width UWORD <Project_Name>Height; Window height These words should be changed by the application if the user has re-sized or re-positioned the window. This way when the window is closed and then re-opened again it will be opened the size and position it had the last time it was open. Note: When the user has changed the window you _must_ substract the window top-border size from the window height before setting in the "<Project_Name>Height" global. Here is a little example of what I mean: int <Project_Name>ChangeWindow( void ) { <Project_Name>Left = <Project_Name>Wnd->LeftEdge; <Project_Name>Top = <Project_Name>Wnd->TopEdge; <Project_Name>Width = <Project_Name>Wnd->Width; <Project_Name>Height = <Project_Name>Wnd->Height - Wnd->BorderTop; return( 1 ); } Or when the IDCMP handler isn't generated: while( 1 ) { WaitPort( <Project_Name>Wnd->UserPort ); while( imsg = GT_GetIMsg( <Project_Name>Wnd->UserPort )) { Class = imsg->Class; GT_ReplyIMsg( imsg ); switch ( Class ) { case IDCMP_CHANGEWINDOW: <Project_Name>Left = <Project_Name>Wnd->LeftEdge; <Project_Name>Top = <Project_Name>Wnd->TopEdge; <Project_Name>Width = <Project_Name>Wnd->Width; <Project_Name>Height = <Project_Name>Wnd->Height - Wnd->BorderTop; break; ..... } } } Also the main file contains the Gadget Array's for each project window which are define as follows: struct Gadget *<Project_Name>Gadgets[]; To access the pointers in this array the program generates DEFINES or EQU'S in the header file which specify the position of a certain gadget in the array. These defines are build as follows: #define GDX_<Gadget_Label> Be sure that the "gadtools.library", "intuition.library","graphics.library" and "utility.library" are all open BEFORE any of the generated routines are called. When you use a diskfont and the "Gen. OpenFont" switch is on in the Preferences window the "diskfont.library" must also be opened. For the assembler source the valid pointers to these libraries must be stored globally with the names "_GadToolsBase", "_IntuitionBase", "_GfxBase", "_UtilityBase" and "_DiskfontBase" otherwise you get problems linking. »»» 11.1) The IDCMP handler In this version of GadToolsBox (37.168) the C source generator will generate an IDCMP handler when wanted. This IDCMP handler is a bit experimental and it will be changed. The generated IDCMP handler will work for most people but some may not like the way it has been done. As of version 37.157 GadToolsBox generates an IDCMP handler routine for each IDCMP flag. This handler will process all incoming IDCMP messages from the window and it will also process all gadget and menu events. GadToolsBox generates the following routine(s) for the event-handling: »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » int Handle<Project_Name>IDCMP( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» This is the main IDCMP event-handler. There will be as many of these routines in the file as there are windows in the file you generated. You must call this routine when you have received a signal that there is a message pending at the window port. This routine will return the value that the IDCMP specific routine returns. This return code can be used to quit the program etc. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » int Handle<Project_Name>Verify( void ); » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» All windows in the generated file which has one or more of the VERIFY flags turned on will have this routine. The handling of the VERIFY events differs from the normal event in that the routine is called _BEFORE_ the message is replyed. This means that the routines for these verify messages should _NOT_ take to long to return. The routine labels called for by the various IDCMP messages are constructed the following way: Flag Routine Name -------------------------------------------------------------------- IDCMP_MOUSEBUTTONS <Project_Name>MouseButtons(); IDCMP_MOUSEMOVE <Project_Name>MouseMove(); IDCMP_CLOSEWINDOW <Project_Name>CloseWindow(); IDCMP_MENUVERIFY <Project_Name>MenuVerify(); IDCMP_MENUHELP <Project_Name>MenuHelp(); IDCMP_REQSET <Project_Name>ReqSet(); IDCMP_REQCLEAR <Project_Name>ReqClear(); IDCMP_REQVERIFY <Project_Name>ReqVerify(); IDCMP_NEWSIZE <Project_Name>NewSize(); IDCMP_SIZEVERIFY <Project_Name>SizeVerify(); IDCMP_ACTIVEWINDOW <Project_Name>ActiveWindow(); IDCMP_INACTIVEWINDOW <Project_Name>InActiveWindow(); IDCMP_VANILLAKEY <Project_Name>VanillaKey(); IDCMP_RAWKEY <Project_Name>RawKey(); IDCMP_NEWPREFS <Project_Name>NewPrefs(); IDCMP_DISKINSERTED <Project_Name>DiskInserted(); IDCMP_DISKREMOVED <Project_Name>DiskRemoved(); IDCMP_INTUITICKS <Project_Name>IntuiTicks(); IDCMP_IDCMPUPDATE <Project_Name>IDCMPUpdate(); IDCMP_CHANGEWINDOW <Project_Name>ChangeWindow(); This means that when you receive an IDCMP_MENUHELP message at your window the IDCMP event-handler will automatically call <Project_Name>MenuHelp(). The Menu and Gadget events are processed a little differently. For each gadget and menu a reference to a routine is generated. The gadget routine labels are constructed as follows: <Gadget_Label>Clicked(); And the menu routine labels are constructed as: <Project_Name><Menu_Label>(); None of the routines called for by the generated event-handler will be passed any arguments. You can get the IDCMP event specific data from a global copy of the arrived message. Each window in the generated file will have a copy of the IntuiMessage that arrived at the window port. The source generator will generate a struct IntuiMessage for each window and the label for those IntuiMessage is constructed as follows: struct IntuiMessage <Project_Name>Msg; The contents of the message that arrives at the window port will be copied into this IntuiMessage before the IDCMP specific routine is called. This way you can get the data you need from the IntuiMessage. When you have the "Templates" switch in the Preferences window switched on the source generator will also generate a file with template routines for each routine the IDCMP event-handlers will call uppon. The name of the generated sources is constructed as follows: When you generate your source as "Source(.c|.s)" the files generated will be called: Source(.c|.s) - The main source file Source(.h|.i) - The source header file Source_temp(.c|.s) - The template source file The way the gadget and/or menu routines are called is done by setting the address of the routine in question in the UserData field of the gadget/menu Then when the IDCMP event-handler receives a gadget/menu message the routine address is picked out of the gadget/menu structure and then called. This is a whole lot smaller and faster than to setup a big switch/case table. To keep things clean the source generator will not generate routines for Menus, Items with subitems, BARLABEL (sub)items, TEXT gadgets and NUMBER gadgets. These menus and gadgets never generate an IDCMP event so it's not necessary to generate routines for them. The generated menu-event handler supports drag-selection which is the only official way to handle menu messages. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 12) The Keyboard & Mouse » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» There are a few keys which perform more or less important functions during the editing. This chapter will describe what certan keys do in which situations: When you are draging the rubber-band box to add, move, copy or size a gadget or when to add, move, size a bevel-box: Key: Action: »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» x This key, while pressed, will block the horizontal movements of the rubber-band box. The movements will be released when you release this key again. y This will do the same as the x key only now the vertical movements will be blocked. ESC When you press this key the action will be cancelled and no change whatsoever is made to the gadget. When you are in the edit window not doing anything in a requester or with gadgets, boxes or texts: Key: Action: »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» F10 This will turn the sizing gadget of the window on when it's off or off when it's on. This is just a shortcut to the WFLG_SIZEGADGET flag. a This will select all gadgets in the window. Shift+a This will de-select all gadgets in the window. When you are prompted via the screen & window title to do something: Key: Action: »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» ESC This will cancel the operation for which you are promted to do something. You can double-click a gadget to put up it's editor(s). »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 13) The GetFile Boopsi Image » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» When you use the GetFile gadget and you generate the source you __MUST__ link with the supplied object code "boopsi.o"! This contains the code that will set-up a private sub-class which will handle the drawing of the GetFile Image. The source of "boopsi.o" has been included with the distribution so you can see how it has been done. The code of the boopsi image is re-entrant so it can be used in residentable programs and libraries etc. Please note that the Boopsi image is _NOT_ public domain. It is freely distributable and remains © Copyright 1992 Jaba Development. You may however distribute it with your program no matter whether your program is public domain, freeware, shareware or commercial. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 14) Adapt Font » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» When the "Adapt. Font" option in the Preferences window is switched on the source generators will create source that will automatically adapt the gadget, bevel-box and window sizes and positions to the active font. The resulting source also checks to see wether or not the window will fit on the screen. If it doesn't fit anymore the topaz 8 font will be used. GadToolsBox forces you to use the topaz 8 font when creating a user interface with the "Adapt. Font" option on because when you would have a larger font and you would (for example) create a SCROLLER of 10 pixels high and at run time a smaller font is active the routine that re-calculates the gadget could make the SCROLLER to small. In the generated source a routine called "ComputeFont()" is generated. This routine calculates the font size and it will check if the window still fit's on the screen using the font. If the window does not fit anymore this routine will automatically switch to the topaz 8 font. This routine is always static and you should never need to call this yourself. Two kinds of adaptable source can be generated. The first kind uses the font of the screen on which the window opens and the second, when the "Use SysFont" switch in the preferences window is on, will use the system default font (GfxBase->DefaultFont). Also two routines called "ComputeX()" and "ComputeY()" are generated which re-calculate the horizontal (X) and vertical (Y) values for the gadgets, bevel-boxes, windows and texts. NOTE: You should take special care when you place fixed-size gadgets like the CheckBox, GetFile and MX gadgets. Because they have a fixed size the gadgets are not "size-adapted" with different fonts. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 15) Keyboard Shortcuts » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» GadToolsBox always offered keyboard shortcuts for most of the requester gadgets. Now the working of those shortcuts has changed. To operate them correctly you must know the following things: Button (Action) Gadgets -: Pressing the underlined key will do the same thing as clicking on the gadget. Cycle Gadgets -: When you press the underlined key the gadget will be cycle one choise forward. If you press the underlined key together with a SHIFT key the gadget will cycle backward. MX (Radio) Gadgets -: Pressing the underlined key will select the choise. String/Integer Gadgets -: Pressing the underlined key will activate the gadget. CheckBox Gadgets -: Pressing the underlined key will toggle the checked mode of the gadget. It used to toggle the mode when a key was repeating but this doesn't work that way anymore. Slider Gadgets -: Pressign the underlined key will slide up one digit and pressing the underlined key with SHIFT will slide down one digit. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 16) Special note about the generated Oberon-Source » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» The generated Oberon-Source is much like the C-Source because the Oberon- Sourcode-Generator was derived from the C-Sourcecode-Generator. The functions (procedures) and variables are (nearly) named the same and have the same function. An example of a sourcecode (FAdaptPAL.mod) is provided. There is a little difference if you use a GetFile gadget. In this case the generated source imports from the module "GetFile". After you compiled the source for this module you must join the generated object file ("GetFile.obj(%|a|s|as)") with the supplied object code "boopsi.o" and "bases.o" or link with these files. The Oberon manual describes this procedure in detail. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 17) Notes » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» At this time there really isn't much to say about the program. It is a tool that will ( or at least should ) save you a lot of time in creating a GadTools user interface for your programs. I've done some testing using "Enforcer" and "MungWall" and I didn't find enforcer hits and the program (as far as I know) handles low memory conditions well. When a big font is used in the program it can happen that some requesters won't fit on the screen anymore. Intuition will automatically re-size the requester so that it will fit on the screen but some gadgets might not be reachable anymore. When you want to save the binaries crunched you must copy the V35+ version of the PowerPacker.library in your libs: directory and you must set-up T: as a logical device. To do this you must have something like this in your startup-sequence: MakeDir RAM:T Assign T: RAM:T If someone wants to translate this manual into her/his language permission is hereby granted. The only thing I ask is that you send me a copy of the translation so that I can distribute it with the next release of the program. When you use a screen bigger than the normal display mode size and you are on a part of the screen that doesn't display the screen it's top-left corner you will not see the title messages GadToolsBox displays sometimes. So if gadtoolsbox doesn't seem to respond to your input move to the top-left of the screen or window and read the message. Although this program itself does not follow all the rules described in the "User Interface Style Guide" I still strongly suggest you try to follow the rules described in in that guide. From v1.3 on GadToolsBox has an embedded version string in the "User Interface Style Guide" format. When submitting a bug-report please tell me the version of the GadToolsBox program you are using. This can be established by typing "Version GadToolsBox" in the shell. Also before you start sending me bug-reports and suggestions please read the "TODO" file first. This is a program for programmers. A lot of things in the manual might not be clear to other Amiga users. If you plan to program the Amiga you should atleast buy the RKM manuals: Libraries, Devices, Includes and AutoDocs, User Interface Style Guide. Also one or two good books concerning the language you wish to learn are essential. I'm not saying this because I like to see you throwing your money away but it's almost impossible to program the Amiga without good documentation. Also do not use an illegal copy of your favorite programming language because a manual can be worth it's weight in gold and using an illegal copy makes you a thief. Never make changes to the source that GadToolsBox generates. You should not do this because each time you re-generate the source you have to make these changes again. You should always code your program specific routines and stuff in one or more seperate modules. This way you can always add things to your GUI using GadToolsBox without having the trouble of adding other things to the GadToolsBox generated source over and over again. Although GadToolsBox generates very compact source there might be some things that you think are strange. For example when you generate source for a window with ten GETFILE gadgets and you look at the source the Gadget Kind array will show GENERIC_KIND 10 times and the gadget TagItem array will show TAG_DONE 10 times. This is the way the source works. Do not try to enhance it to save a couple of bytes in the resulting executable. Please remember that it's machine generated source. Coding this stuff by hand might save you a few bytes on the executable size of the resulting program but using GadToolsBox will save you hours and hours of boring GUI coding. Some people have asked me how they could determine the size of the window they had created. This is really simple. Move the mouse pointer past the right and bottom edge of the window and the coordinates will tell you the size the window has. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 18) Credit » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» I would like to thank the following people for their many suggestions and bug reports. Without these people GadToolsBox wouldn't be where it is today ________ T H A N K S ________ Wolfgang Küting, Kasper Peeters, Stefan Becker, Nico François, Sebastiano Vigna, Andreas Jung, Ken Simpson, Kai Bolay, Ola Olsson, Richard Waspe, Carsten Feilhaber, Garry Glendown Jochen Kreimer, Georg Hessmann, Martin Laubach, Eugene Pang, Klaus Nachtigall, Andreas R Kleinert, Gael Marziou, Rene Petersen, Magnus Holmgren, Greg Woolley, Marcel Offermans, Peter Kunst, Reza Elghazi, Steve Loughran, Ugo Paternostro, Franz Schwarz And special thanks to: Matthew Dillon For his incredible Dice ( you should register.... ) Stefan Becker For sending me my Dice update Fred Fish For the huge pile of AmigaLibDisks he produces Huub Schuivers For installing 2MB on my A2630 card Andreas Jung For his donation Ingo Sabel For his donation Frederic Hahn For the bottle of white wine Andreas R Kleinert For his donation Klaus Nachtigall For his donation Sebastiano Vigna For the font adaptivity idea (and the way to do it) U2 For the _great_ concert in the Westfalenhallen in Dortmund. It's to bad that someone banged up my car that day..... If you have a chance you really should go and see U2 on their ZOO TV Tour. Nico François For sending me ReqTools 2.0. Kai Bolay For the solution to the Mutual-Exclude bug and for writing the Oberon source generator. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» » 19) __IMPORTANT__ » »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» Due to a bug in the previous releases of GadToolsBox (v37.79--) it's possible that you have binary files which contains a corrupt menu strip. This because the program counted sub-items for items which didn't have any sub-items. This would cause the binary file routine to write the sub-items that didn't exist to the file. To fix these files you must load them in this version of GadToolsBox and go into the Menu Editor ("Edit Menus..." under the "Menus" menu). Now select the first menu and click on "ItemEd". Now select each non-NM_BARLABEL item which should _NOT_ have any sub-items and press "SHIFT+E". Each time the requester pops-up and you are sure that you have selected the right item you should click on "Yes" in the requester. You must repeat this action for all menus and then (when you are finished) save the file again. I know that this could mean some work with big menus but I think it's better to do this than to re-create the whole user-interface. I'm very sorry for this bug but it was one of those famous ones that only occurred sometimes. NOTE: BINARIES CREATED WITH V1.0 OF GADTOOLSBOX CANNOT BE READ/REPAIRED BY THIS VERSION OF GADTOOLSBOX. ONLY THE BINARIES CREATED WITH V1.2++ CAN BE READ/REPAIRED BY THIS VERSION OF GADTOOLSBOX. »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»» Bug reports, suggestions, postcards, flames, criticism, contributions, ideas, gifts, opinions about the new U2 cd 'Achtung Baby', how to make a million (the easy way....), inspirations, flowers, etc., etc., etc.... to: Jan van den Baard Fido: 2:285/502.7 (Jan van.den.Baard) Bakkerstraat 176 3082 HE, Rotterdam Holland »» "Trust me. I know what I'm doing." -: Sledge Hammer «« »» "Life sucks." -: Al Bundy «« »» "Hasta la vista, Baby." -: The Terminator «« »» "Make noise, Tell the world to fuck off!" -: Bono «« »» "The most mercifull thing in the world, I" "think, is the inability of the human mind" "to correlate all it's contents. " -: Propaganda «« »» "Normal is boring." -: Fido Dido ««