PowerWindows 2.5 is the interactive, interface programming aid for the Amiga computer. It provides you, the programmer, the ability to quickly create and edit screens, windows, menus, and gadgets for your programs, with none of the fuss or tedium of codin create new screens and windows; edit old screens and windows; "grab" (import) windows running elsewhere in the system; add, move, delete, or edit window text; modify window characteristics; include or exclude IDCMP or other window flags; add, move, edit or delete a menu; add, move, edit or delete items and subitems in a menu; add gadgets, move gadgets, clone gadgets, re-size gadgets, set gadget characteristics, enter gadget text, and delete gadgets; add and manipulate Knob, PopUpMenu, and DragGadget constructs as used with InovaTools1; include IFF brush imagery in your gadgets or menus; generate source code for all of the above; and save your creations on disk for future editing. PowerWindows provides you with instant feedback, allowing you to see exactly how your creation will look without the trial-and-error of the edit/compile/examine loop. You can effectively see your windows outside your program, complete with menus, menuitems, subitems, text and gadgets -- almost as if you were already running your program. When you are satisfied, select your language and PowerWindows creates the structures for you. Save your design in the intermediate file format so that it will be available should you ever need to modify or add to it, or generate the same data for a different language. NOTE: You will need to provide the necessary entry points or procedure names to properly interface the generated code with your program. REQUIREMENTS: Amiga with 512K RAM and at least one disk drive, with KickStart/Intuition version 1.2. Also required are the necessary include files for the language of your choice which define the Intuition structures that PowerWindows generates. GETTING STARTED: PowerWindows requires no installation. We recommend that you make a copy of PowerWindows and put the original in a safe place, away from hazards like fire, strong magnetic fields, and pirates. Use the copy as a "master", and use the original only for making new legal copies. Unlike the program, you might require some installation yourself. This software expects you to be familiar with the Amiga and with the programming language of your choice. This means that we won't be defining terms like drag bar (no jokes, please) or gadget. PowerWindows is a serious tool for serious programmers. PowerWindows can be run from either the Workbench or the CLI environments. PowerWindows starts with a blank, 640 x 200 window, on the Workbench screen. This is the "command window". To see just how simple it is to create a PowerWindows interface design, get PowerWindows running and press the Right-Amiga N key. This will open a new window on the Workbench screen called "Your new window". At this stage you could immediately generate source for "C" or assembler which would create the data needed to exactly duplicate that window. But first, let's dress it up a bit.. Start by resizing the window and positioning it any way you like. It is a real Intuition window so the drag bar, depth-arrangement and sizing gadgets all work. Next, press Right-Amiga A and read the message in the requester that pops up at the top of the screen. This message explains how to use the Add a gadget command that we have just invoked. When you have finished reading the text, press the OK gadget on the requester and position your mouse somewhere over the center of "Your new window" and click the left button. This tells PW2.5 where you want the TopLeft pixel of your gadget's border to be drawn. Now drag the mouse inside the window and PW2.5 will follow your movements and size the area of the gadget accordingly. After you have dragged the mouse around for a bit, press the HELP key on your keyboard and PW2.5 will redisplay the original message describing what you are doing. If you forget which action you are expected to take or just want to CANCEL an action once it has already begun, you can always press the HELP key for a reminder and a chance to change your mind. For now, just press the OK gadget and put your mouse back into "Your new window". PowerWindows , waiting for you to make a final decision about the size of the new gadget. Click inside the window to tell PW when you are done. Now you have a real window with a real BOOLEAN gadget in it, but we still need a menu. So press Right-Amiga M and PW will open a requester used to specify several options about menus, but right now we just want to key in a name for our first menu, so just type in "My First Menu" into the preactivated string gadget labeled MENU TEXT. Next press the OK gadget and the requester will close. Your window now has a real menu attached to it with one menuitem called "dummy". If you need proof, click on the drag bar of "Your new window", followed by the right mouse button. Your menu is there and it looks exactly the way it would look in your program if you generated source code for this window right now. So let's do that right now. Press Right-Amiga G and a requester will open with the names of the three language generators that PW2.5 has built-in listed in gadgets at the top. Press on the language you want and then press on the word OUTPUT (not in the string gadget to the right of the word) and the InovaTools1 file requester will open allowing you to specify the complete filename for the output file you want to generate. Choose a filename like "ram:test.c", or at least some filename that you wont mind letting PW use. Once you have specified a filename for our little test window's source code, the file requester will close and stuff the filename into the OUTPUT string gadget. If you already know the filename, of course you can key it directly in this box. Finally, press the OK gadget on the source code generation requester and PW2.5 will write a file with all the data you need to duplicate this simple interface in your own software. Now, we want to save this design for later editing, of course, so press Right-Amiga S and the file requester will reappear to let you indicate a save filename. By default PW will save your file with the ".pw" extension added to the name, but you can use any extension you want by typing into the box on the file requester labeled Type and pressing RETURN, or use no extension at all by deleting all characters in this field and pressing RETURN. Once you have specified the filename press the Save gadget on the file requester and the save will be made. In the case of a disk error, PowerWindows will report it to you and allow you to try the save again. Now that the file is saved, you can Quit PW2.5 and come back to that same file anytime using the Right-Amiga L option, and then just pick right up where you left it last time. That was a simple PowerWindows 2.5 editing session. Now use the menu button to see the main menustrip, which consists of seven primary menus: Project Screens Windows Menus Gadgets Knobs Preferences Each of the menus listed above are discussed in the sections following. This manual is organized in the same way that the menus are organized. PROJECT: Under the Project menu you will find the following: Generate source code Save configuration Save screen and/or windows Load screen and/or windows Kill everything Quit... Generate source code is the whole point of PowerWindows. This command lets you specify the language of your choice and several other options. (For languages other than "C" and 68000 assembler, you must use the specific language translator program provided for that language, which you will find on your distribution disk. These translator programs use the intermediate file format generated by the Save screen and/or windows command.) Before starting the code generation, you must specify the OUTPUT filename. If you don't know the filename to use, you can click on the word OUTPUT for a file requester. You may also specify a HEADER filename. The HEADER file is a file that you wish copied into the start of the source generated by PW. This file may contain definitions, include statements, or anything else. You may click on the word HEADER for a file requester if you need one. You can also control which "sections" of the source code to generate. For example, assume you have created a source file with PowerWindows, and then edited it for some particular purpose; if you need to edit that design in the future and regenerate the source code, PW will allow you to generate source for only those parts of the design that have changed. Just turn off the sections that you do not want generated. The sections include: SCREEN, PALETTE, WINDOWS, GADGETS, MENUS, WINDOWTEXT, RENDER (BORDER ONLY and IMAGE ONLY gadgets), and EVENTS (the event handler). The LOCAL STRUCTURES option instructs PW to make all structures generated local, if the target language supports such a concept. An example is static structures in C. Finally, the BORDERS/IMAGES GADGET option tells PW to generate a special gadget as a link for the render of any BORDER ONLY or IMAGE ONLY gadgets (see Define gadget type for details) that may exist in your design. In other words, rather than create the standalone linked list of Borders/Images that would normally be created, PW will link those lists into a gadget designed just for rendering that data. The gadgets have a size of zero, use no highlighting and are placed in the extreme TopLeft corner of the window that they inhabit. Save configuration lets you save your current Preferences settings to a file called "devs:pw2-configuration". This file is automatically loaded when PW is invoked. Note that your preferences are also saved to every PW intermediate file that you make, and are loaded from those files. Save screen and/or windows will save information to a file about your screen and windows in a format that PowerWindows can read to recreate it. If you wish to retain the ability to edit your current design, you must use this option. We suggest that you append ".PW" to the filename to indicate what kind of file your are saving. (The file requester also automatically looks for .PW files as a default.) At any time in the future, you can select Load screen and/or windows from the Project menu and read this file to examine and edit this design. Your PW Preferences settings and source code generation options are also stored in this file. Note that additional PW support programs, such as generators for other languages, use this type of file. In the future, INOVATRONICS will provide tools allowing other uses for this format. Load screen and/or windows loads a file generated in the above manner and opens the windows and screen contained therein. Note that PW will merge the incoming windows with any current windows you are working with. If a custom screen is found in the file, and you already have a custom screen, PW will prompt you to ask if you wish to replace the current screen with the one from the file. The Preferences in use are always those from the most recently loaded intermediate file. Once you have loaded a file in this way, you can manipulate all of the objects in your design, exactly as if you had just created them. This allows you to easily play with interface designs, move this object here or there, and experiment. One extremely practical way to make use of this feature is to create a "toolbox" window of gadgets or knobs that you use on a regular basis, then save that window as a normal PW intermediate file. Then, whenever you need a gadget just like one of the ones in your toolbox, you can re-load the window and move or clone a gadget out of that window, and into the one you are currently designing. After you have what you need from your toolbox, you can simply remove it with the Kill window command. Kill everything will close any custom screen and all windows with which you are currently working. There is no undo feature. Be warned. Quit... means just that. Make sure you've saved an editable file if there's any chance you might need to change the display on which you are working. (Re-creating a complex window with many menus and gadgets is far easier with PowerWindows than without it, but it IS still work.) PowerWindows will ask you if you wish to abandon any changes you have made, if you have not saved at least an editable file to disk. SCREENS: You can design custom screens and palettes with the Screens functions. Define screen type will present you with a window with which you can determine your screen's dimensions, the number of bitplanes it uses, the pen numbers, default font and title for the screen. Use these gadgets to control the type of screen you get, select the CUSTOMSCREEN gadget, and press OK. A new screen will appear with the indicated characteristics. All windows that you later open will appear on this screen, or, if you already have windows open, they will be moved to this screen. Four gadgets are provided for selecting any one of the four standard NTSC screen sizes, however you may key any dimensions you like into the Width and Height gadgets at the top of the requester. PW will not verify that the numbers you have chosen are legal; this is your responsibility. To return to a Workbench screen, select the WBENCHSCREEN gadget and press OK. Several flags appear under the Screen Flags section of this requester which are not WYSIWYG, but will be generated in your source code. The same applies to the CUSTOMBITMAP POINTER string and the GADGETLIST string. To move quickly between the PW command window, which is on the Workbench screen, and your custom screen, you can use the F1 and F2 keys. Screen Palette brings up a palette editor which you can use to change the RGB settings for your screen's colors. The colors on the requester are oriented left-to-right beginning with color 0. You can use the READ PALETTE FROM IFF gadget to specify an IFF brush filename from which to read a palette. If you need a file requester to help you select the proper file, click over the phrase READ PALETTE FROM IFF. If you modify your palette, only to later change your screen definition, the palette changes may be lost. A color palette is maintained through screen definition changes only if the number of bitplanes used in the old and the new custom screens is the same. WINDOWS: PowerWindows 2.5 lets you work with any number of windows simultaneously. However, all the commands relating to windowtext and menus operate only on the context window. For example, if you have two windows open and you tell PW to Redisplay, it will redisplay the current context window. You switch context windows by clicking inside the window that you want to become active. You can switch context windows only when PW is waiting for input at the main menu level. Under the Windows menu heading you'll see: Open new window Grab a window Redisplay Clean up Edit window characteristics Kill window Write window text Move window text Edit window text Delete window text Open new window opens a new Intuition window on the Workbench screen or on your custom screen if you have made one. You can do anything to this window that you like because it is an actual window. At various times, PW will read information from this window's structure regarding its position and size, but you can play with it freely. The new window automatically becomes the context window for windowtext and menus. To quickly reselect the PW command window, you can press F1, click inside the PW command window, or if Auto select is on, just click inside any one of your edit windows. Grab a window is one of the most powerful PW commands. It allows you to import any window running at the time as a PowerWindows construct and edit it as if you had generated it manually. After selecting this option, you will have a new menustrip with the following menus: Screens Other On the Screens menu you will find a list of all screens open at that moment, and a list of all windows open on each screen will be shown as subitems to that screen. The windows and screens are identified by their titles. If a screen or window has no title, its item will appear as a blank. To grab one of the windows listed, just select its name. The window, with all of its menus and gadgets will be imported into PW for instant editing. Note that some things are not grabbed, such as imagery, borders, or text that were drawn into the window individually and are not connected to any gadget or menu. For each gadget grabbed that uses a border for render, a custom border is created. You may delete or replace this border by doing border work on that gadget. All menus are set to USER FORMATTING when grabbed because PW wants to maintain the original look and positioning of the grabbed menus. If you are grabbing a window from a screen of a resolution different from the one you are designing, PowerWindows may have to change the size or origin of the window to make it fit. The Other menu allows you to return to the main menu. Redisplay refreshes your current window, cleaning up any display problems that might result from your editing. The raster of your window is blanked, then all gadgets, knobs and windowtext are redrawn into it. Clean up is provided to ensure that all gadgets and knobs in your window are actually in the displayable area of your window. For example, if you have put a knob or gadget in the far right-hand side of your window and you then make the window more narrow by resizing it to the left, those gadgets and/or knobs may be no longer in your view. This can cause problems, because in order to manipulate a gadget or knob with PowerWindows, you must be able to select it with the mouse. The Clean up command will move any gadgets or knobs which are outside the display area back into it. Also, because of gadget WYSIWYG relativity, it is possible for you to create a gadget with a hitbox which has a negative size. PW will detect any such problems and correct them when this command is used. Edit window characteristics gives you the opportunity to specify the following: Detail and block rendering pens; Minimum and maximum window dimensions: Current window dimensions; Current window position; Window title; Window type (window or requester) Window ID prefix (added to all structure names for this window IDCMP flags and window flags The IDCMP flags in this window can be toggled ON or OFF to include them or not in the generated source code, but during editing the window has IDCMP flags used by PowerWindows internally. (To see what they are, try grabbing one!) Of the normal window flags, these are WYSIWYG: WINDOWCLOSE, WINDOWDRAG, WINDOWDEPTH, WINDOWSIZE, SIZEBBOTTOM, SIZEBRIGHT, BACKDROP, and BORDERLESS. See the Amiga ROM Kernal manuals for complete descriptions of the flags listed on this display. If you want PW to make a Requester structure rather than a NewWindow structure at source code generation time, you can hit the gadget labeled TYPE, and it will toggle between WINDOW and REQUESTER. Kill window will remove the current window. Be sure to select the window you want to destroy before using this option, as there is no UNDO command. Write window text lets you write a string of text to be displayed in your window. After keying in the text, click OK and move your pointer to the location in your window where you want the upper left-hand pixel of the first character of the text to appear. Click here (the text appears) and drag the pointer to position the text more exactly. Click again when your text is properly positioned. (Windowtext and gadgettext are different. Windowtext is relative to a window and in the source code is generated as a linked list of IntuiText structures that you can draw into the window yourself with a single PrintIText call. Gadgettext is relative to a gadget. If you move the gadget, the text will move with it. If you delete a gadget -- BAM! -- the text is gone too. Gadgettext is also generated in source as a linked list of IntuiText structures, but they are referenced by the gadget they were designed with and will be automatically rendered when their parent gadgets are rendered.) Edit window text displays as subitems one or more text strings that you have previously entered for this window. (If none have been entered, this and subsequent menuitems are disabled.) Just select the text string subitem that you would like to edit. This gives you a window from which you can choose text pens, drawmode and font (default, TOPAZ-SIXTY or TOPAZ-EIGHTY) as well as edit the text and its offsets from the TOPLeft corner of the window. All source code needed to duplicate your text will be generated by PowerWindows, including TextAttr structures for the fonts. After editing, the window will be redisplayed with any text changes shown. Move window text gives you the ability to move individual strings of window text around in the window. The movement of the text within the window will be relative to the position of your pointer when you first click inside your window. This gives you the ability to click somewhere near your text, but not on it, so that you can see the entire text string as you move it. Delete window text enables you to remove unwanted text from your window. Just select the text to kill and POOF! It's gone. MENUS: Making menus with PowerWindows 2.5 is very easy. The menus that you create are, at all times, real menus, attached to the window with which you are working. Therefore, you can see what your menu looks like at any time. Plus, if you are working with a custom screen, you can see the menu in the resolution in which it will be used. To see the menus for a particular window, you must select that window. If the Auto select preference is ON, you can only select the window by clicking on one of its system gadgets, like a drag bar or foreground gadget. If the window has no system gadgets, you can add them with the Edit window characteristics command, or you can turn off Auto select and just click inside the window. Under normal conditions, all menu elements are automatically positioned by Power Windows. This is called AUTO FORMATTING. PW will always do its best to see that the menuitems and subitems are visible when the menus are rendered, and are attractively arranged. However, you can position the items yourself, if you like, by setting the USER FORMATTING flag for the menu or item and specifying the needed pixel values. But be careful; if you use irrational values, your computer will respond irrationally! If you do not set the USER FORMATTING flag, PW will ignore any pixel values that you set. The Menus menu deals with menus, menuitems, and menu subitems for your current window. Your menus are dynamically updated every time you make a change to them. You can append a menu to the end of the menu tree, or you can insert a new menu in front of others. You can rearrange the menus, delete them, etc. You can also do the same things with the menuitems for each menu and with the subitems for each menuitem. You can attach Amiga-keys to menuitems and subitems, and have the items checked/unchecked or enabled/disabled by Intuition. You can instruct Intuition to un-check certain menuitems or subitems when others are selected. You can also load imagery for the rendering of menuitems and subitems. The Menus menu shows you: Append a menu Insert a menu before... Move a menu Edit a menu Work on menuitems for... Delete a menu Append a menu lets you to enter the name of a new menu, choose AUTO or USER FORMATTING, and set/reset the MENUENABLED flag. After you OK the settings, PowerWindows creates a menu with that name and attaches a "dummy" menuitem to it. (This dummy goes away when you add a real menuitem to the menu.) All menus created in this manner are appended to your menustrip (i.e., list of menus). Insert a menu before... shows you the menus that exist. When you select one of them, you will be prompted for the name of the new menu to insert before the selected one. Please note that only the first 15 characters of each menu name will be displayed here; the full menu name will be used in your window and in any generated source code. This truncation applies to menuitem names, subitem names, gadgettext and windowtext, as well. Move a menu lets you move a menu toward the back of the list (the end) or toward the front of the list (the start). You can move a menu only one position at a time, so you may have to invoke Move a menu several times to get things just so. Edit a menu lets you change all the settings of a selected menu. Work on menuitems for... allows you to attach menuitems, subitems, and their options to the menu you select. See the next section for details. Delete a menu removes the selected menu from the menu tree. Use this one with caution, as it removes everything having to do with that menu, menuitems, subitems and all. MENUITEMS: When you select a menu form Work on menuitems for..., you are given a completely new menustrip from which to work. It has two menus: MenuItems Other Menuitems looks, and is, similar to the Menus menu, but "menuitem" replaces "menu" and "subitem" replaces "menuitem", and there is one more choice on the menu; Work on images for..." Basically, however, you can do to menuitems what you did to menus: Append a menuitem Insert a menuitem before... Move a menuitem Edit a menuitem Work on images for... Work on subitems for... Delete a menuitem Under AUTO FORMATTING the width of the longest hit box in your menuitem list determines the width of all the menuitem hit boxes in the menuitem list for that menu. You can pad your menuitem names with spaces to make the box wider, or play with the choices you get in the editing window. Append a menuitem, Insert a menuitem before..., and Edit a menuitem all use a window that allows you to specify a number of Intuition menuitem flags, text for the item, as well as an alternate command key for the item. You can also control the presentation of the IntuiText rendered in your window with this option. The ROOM FOR CHECK and ROOM FOR ALTKEY provide some additional spacing to the left and right of the item render for a checkmark and an alternate command key, respectively. The FUNCTION gadget lets you key in a function or vector name for execution when this item is selected. This execution is performed in conjunction with the event-handler (please see Using the event handler for details.) Also contained in this window is a menu which allows you to specify the items which the current item should mutually-exclude. (Mutual-exclude refers to one item which, when selected, will un-check a list of other items on the same menu, or other subitems of the same menuitem.) Notice that the item upon which you are working is also listed here because it is perfectly legal to make an item exclude itself, though it rarely makes any sense. As you move, insert or delete items from the menu, these mutual-exclude values are automatically maintained by PW2.5. Work on images for... allows you to load or delete IFF brush imagery to use for menuitem rendering. You can load both the render (unselected) and select (selected) imagery. PW automatically makes the select boxes of the items in the list wide enough for the images to be attractively integrated, even if you mix images and text on a single item list. Work on subitems for... sets up yet another new menu, just slightly different from the last one: Append a subitem Subitem columns(1) Insert a subitem before... Move a subitem Edit a subitem Work on images for... Delete a subitem The slight difference is Subitem columns. With this option you can display your subitems in up to 9 columns. Other on the Subitem menu offers a return to the Main menu or a return to the Menuitem menu, while Other on the Menuitem menu only lets you return to the Main menu. GADGETS: All gadgets created by PowerWindows are rectangular, but they can be virtually any size from a few pixels to the entire area of the window, and with the Clone a gadget feature you can make very professional-looking screens filled with gadgetry of varying sorts and colors. PW lets you create all three Intuition gadget types, BOOLEAN, STRING and PROPORTIONAL and work with them in a what you see is what you get fashion. You can also load custom imagery for the the render (unselected) and the select (selected) fields of a gadget. Additionally, most of the flags which control the gadget's appearance are also WYSIWYG. With PowerWindows version 2.5, you can also work with two special types of BOOLEAN gadgets: PopUpGadgets and DragGadgets. Both of these new gadget types are meant to be used with the InovaTools1 package available from INOVATRONICS, Inc. If you do not intend to use InovaTools1 with your software, then do not use these new gadgets types in your design. PW2.5 has the support routines for the InovaTools1 functions built-in to it, so you can design these special items, even if you cannot use them in your own programs. PopUpGadgets are BOOLEAN gadgets that, when pressed, will display a menu of your design under the mouse and allow the user to select a menuitem or subitem just as if a normal intuition menu were being used. You specify that you want a gadget to be a PopUpGadget through the Define gadget type command. Then you may edit the menu attached to the gadget through the Work on PopUpGadget menuitems command. After making a PopUpGadget, when you click on the gadget your special menu will be displayed under the mouse. DragGadgets are BOOLEAN gadgets which use an image for render and may be dragged around the screen. You can make the gadget stay where it is put or rubber-band back, move around just in the window in which they are defined or allow them to move anywhere on the screen! You can also control the way in which the render image is displayed while the gadget is being dragged, and the dimensions of the area in which the gadget can move. Once you have created a DragGadget, you can click on it and drag it anywhere in your window. Both of these gadget types are fully WYSIWYG within PowerWindows. A full discussion of their properties and how to control them are beyond the scope of this documentation. You must refer to the InovaTools1 manual for further information. Under the Gadgets menu you'll find: Add a gadget Move a gadget Clone a gadget Re-size a gadget Define gadget type Work on gadget borders Work on gadget text Work on gadget images Work on PopUpGadget menuitems Move gadget to start of list Choose gadget successor Move gadget to end of list Delete a gadget Add a gadget waits for you to click in one of your windows to position the TopLeft corner of your gadget's border. Drag the mouse to size the gadget appropriately. Click the mouse button again and the box becomes a real BOOLEAN gadget, hooked into your window. Note that your ability to size the gadget, and then later to move it, may be impeded by the status of the Gadget collision checking flag which, when on, will prevent the bisection of one gadget by another. You may wish to disable this function for special applications, but be aware that the designers of Intuition strongly discourage the practice of overlapping or intersecting gadgets. Move a gadget lets you change the position of a gadget by clicking inside the gadget and dragging it to a new location. Any associated gadget text will be moved also. That is, its position relative to the gadget will not change. When moving STRING gadgets, after selecting the gadget, press return. After that, the gadget may be moved normally. Press the left mouse button when it is properly positioned. Similarly, always move PROPORTIONAL gadgets by their knobs, not by clicking inside the gadget's container. You may move a gadget from one of your windows to another by simply picking the gadget to move and moving your mouse until it is over the window to which you wish to move the gadget. Then click the mouse again and the gadget will be removed from the old window and deposited in the new window. Clone a gadget lets you duplicate a gadget exactly, both in terms of hitbox size and in terms of gadget flags, text, and imagery or borders. Select the gadget to clone and a new gadget, slightly offset to the BottomRight, will be created. Now drag the pointer to position the duplicate gadget and click the left mouse button when you are finished. You can clone gadgets from one window to another in exactly the same manner as they are moved from one window to another, as described above. Re-size a gadget gives you another opportunity to get that gadget just right. Click and hold the select button when the pointer is on the desired gadget. Dragging the mouse around will re-size the gadget. Click the button again when the gadget is the correct size. Define gadget type, after selecting a gadget to work on, gives you a new window full of various flag settings and decisions you can make concerning your gadget. From this screen, you can determine the gadget type, set its size and origin locations, and specify various data for the generation of your gadget's source code. A few Define gadget type notes: The relativity flags GRELRIGHT, GRELBOTTOM, GRELWIDTH, and GRELHEIGHT, if selected, ARE put into effect while in PowerWindows. Therefore, any changes made to the size of the window in which the relative gadgets reside, will effect the position and/or size of the relative gadgets. Be careful: it is possible, for instance, to make a gadget with the GRELWIDTH flag set, then resize its containing window to be so small that the gadget attains negative dimensions. Intuition will not object, but it will be impossible for your user or yourself to select this gadget. Use the Clean up command from the Windows menu to fix any problems arising from the use of this WYSIWYG feature. BORDER-ONLY and IMAGE-ONLY gadgets are gadgets only in the context of a PowerWindows editing session. At the time of source code generation, all of the borders of the BORDER-ONLY gadgets will be written as a linked list of Border structures, one for each BORDER-ONLY gadget, and likewise for the IMAGE-ONLY gadgets. Any text associated with these gadgets is NOT GENERATED AT ALL. Use BORDER-ONLY gadgets to draw boxes around groups of gadgets and text, as we have done with this screen, and use IMAGE-ONLY gadgets to place various images around your display. PopUpGadgets are BOOLEAN gadgets that have a PopUpMenu attached to them for use with InovaTools1. DragGadgets are BOOLEAN gadgets that can be dragged around the display and use imagery for render. Selecting this option will bring up a requester allowing you to indicate the dimensions of the DragGadget's bounding-box, as well as the various flags used by DragGadgets. Also, if the language you are working with supports vectored execution, you can specify a routine to be executed each time the DragGadget is moved by the user. The string describing this routine is generated in your source code. In the BOOLMASK gadget, you can specify a pointer to a BOOLMASK for use in a BoolInfo structure. PW will not generate a BoolInfo structure unless you put a string into this field. In the EXCLUDE, GADGETID and USERDATA gadgets, you can enter any text strings that you want used for these same fields in the Gadget structure. Because these fields are not used by Intuition, you can use them for your own data. You must provide any data necessary to resolve these references at compile or run time. The FUNCTION gadget lets you specify a function or vector which is to be executed when this gadget is selected. See Using the event-handler for more details. In the SOURCE LABEL gadget, you can enter the exact text for the structure name to use when generating source for this gadget. Does not apply to BORDER-ONLY or IMAGE-ONLY gadgets. The number in the string gadget LENGTH field must include one extra byte for the end-of-line null byte required by Intuition. If you turn on the UNDOBUFFER gadget, PW will generate one undo buffer for all those gadgets that refer to it. The buffer will be as large as the largest string gadget buffer. The HBODY and VBODY values are a convenient way to indicate the size of the AUTOKNOB of proportional gadgets and the distance which the knob can move each time the gadget's container is hit. A value of 10, for example, will make the AUTOKNOB 1/10 the size of the entire container and it will move 1/10 of the container each time the container is hit. Please see the Amiga ROM Kernal manuals for complete descriptions of all the Gadget flags listed on this screen. Work on gadget borders concerns your control of a gadget's border. After you choose the gadget to work with, you have a new menu with the following topics: Borders Other On the Borders menu, you will find three functions for the drawing of custom borders (1. freehand - where you click in your window, drag and click to set the end-point of that vector, and double-click when down; 2. rectangle - where you click for the TopLeft corner of the rectangle, drag and click when done; and 3. square - in which you click to set the center of the square and drag to define its size), a command to edit the offsets, drawmode and pen number of the border (for custom border or standard border), and a command to delete any custom border. The Other menu lets you turn off the standard border, pick a new gadget to work on, or return to the main menu. If you turn off the standard border (not the same as border-only), the gadget border will still be displayed by PowerWindows for purposes of editing and identification. Any source code generated, however, will not have a gadget border structure referenced or generated. In order to generate a gadget with absolutely no render, you MUST turn off the standard border. Work on gadget text gives you a new menu that is identical in function to the functions concerning windowtext in the Windows menu. Note, however, that windowtext is relative to a window and gadgettext to a gadget. Otherwise the principles are the same. Write the text, position it in the window by clicking and dragging the mouse, and click again when all is as it should be. Work on gadget images lets you pick a gadget for which to load imagery, then gives you a new menustrip relating to imagery for that gadget. You can load an IFF brush for the gadget render of the gadget select image, edit the offsets for the image, make the gadget hitbox the exact same size as the image, or delete image. PW will automatically set the correct flags in the gadget structure allowing you to use the image, delete it, etc., without worrying about the render or highlighting flags. Work on PopUpGadget menuitems allows you to edit the menu attached to a PopUpGadget just as if it were a normal PowerWindows menu. After choosing this option, simply click on the PopUpGadget with which you wish to work, and PW2.5 will give you a new menustrip for editing the menuitems attached to your PopUpGadget. You can do anything to a PopUpGadget's menuitems that you can do to a normal menu's items, including the use of imagery, subitems, various highlighting methods and mutual-exclusion of other items on the same PopUpMenu. You cannot, however, use alternate command key sequences for PopUpGadgets because Intuition would confuse these keys with those reserved for common Amiga menus. Move gadget to start of list lets you pick a gadget to move to the start of the gadget list. This command and Move gadget to end of list can be used to crate lists of gadgets in an exact order. This lets you use only part of a gadget list in a given situation. Specify gadget successor lets you indicate that "this" gadget comes right after "that" gadget in the list. In the event that two gadgets overlap, this command lets you control which gadget is in "front". Delete a gadget deletes whatever gadget you choose. To delete a string gadget, you must select and press RETURN. Be careful! There is no going back. KNOBS: Knobs are special, new input devices supported by InovaTools1. They have the appearance of circular, analog-type dials. They can be rendered in any of the standard resolutions and are highly configurable. To use a knob, simply click in the body of the knob. If the arrow of the knob (the dial, in other words) is not already at the position on the knob where you clicked, it will move there. Then, as you move the mouse the knob arrow will move around the knob to a new setting. To stop moving the dial, just release the mouse select button. A complete discussion of knob properties can be found in the InovaTools1 documentation, and you must have that software in order to make knobs function in your software. If you look at the Knobs menu, you will see the following options available: Add a knob Move a knob Clone a knob Re-size a knob Edit knob parameters Delete a knob Add a knob works very much like Add a gadget. After choosing this option, click at the point inside your window at which you want the center of the knob to appear. Then you simply drag your mouse to size the knob. When the outline of the knob's diameter looks correct to you, click on the mouse again inside the window and a real Knob will be added to your window. You can change its size, position and many other options with the other commands from this menu. Move a knob works in this way: click on the knob you want to move, drag it (even to a new window if you like) and click again when it is properly placed. If you move a knob to another window, the knob will be removed from the window of origin, and appended to the KnobList of the destination. Clone a knob is the functional counterpart of Clone a gadget. Just click on the knob to clone and an exact duplicate knob will be created that you can then move to someplace in that same window or to another window if you so choose. Re-size a knob allows you to click on the knob to resize, drag the mouse and then click again when the knob has reached the desired dimensions. Because certain rasters and memory must be allocated in order to fill a knob with a particular color, making a knob too large can result in a knob that cannot be filled. Edit knob parameters will wait for you to select the knob you want to edit with the mouse, then will open a requester with gadgets inside it for all of the various flags and settings that can be determined for knobs. Although you must refer to the InovaTools1 manual for a thorough discussion of all these parameters, below is a short list of the items you can control with this command: X and Y coordinates of the knob's center; knob flags, including DRAW, FILL, COMPLEMENT, RANGED, CALCVALUE, MARKED, and MARKENDS; the current settings for the knob's position, range of movement, and the number of unique steps in its range; the radius of the knob and the length of the knob's arrow (dial); the colors used for rendering the knob; the label to be used in the generated source code for this knob; fields to name the text strings for the UpdateRoutine, KnobID, and UserData fields of the Knob structure. When you have properly set all of the knob's parameters click on the OK gadget and the knob you changed will be redisplayed, reflecting your changes. Note that if you happen to accidentally move a knob beyond the edge of your window, you may use the Clean up command to bring all knobs and gadgets back into the boundaries of a selected window. Delete a knob waits for you to click on the knob you want to delete and then removes it from the KnobList of its window. The window is then redrawn without the knob. PREFERENCES: This menu gives you some flexibility in using PowerWindows 2.5. In it, you'll see: OK prompts PW backdrop Auto Redraw Auto Select Mouse coordinates Gadget collision checking Image color remapping Image compression Trim extra bitplanes Source code comments Source code spacing (TAB) The default condition for all of these settings is ON, except for the PW backdrop option. However, these settings, along with other relevant data, are stored in each PW intermediate file that you save, and are restored when the PW intermediate file is reloaded. OK prompts, when checked, gives you a prompting requester at the start of many gadget and text related functions. At these prompts, you also have the ability of cancelling your action. You can disable these prompts by un-checking OK prompts in this menu. You can get the prompt back at any time in the middle of a function by pressing the "HELP" key. You will get the original help prompt back with the same chance to cancel the operation. PW backdrop controls the PW command window. If this is checked, then it becomes a backdrop window. This means that no window opened can appear behind the PW command window. Normally, this provides a working area for your custom window design. However, if you wish to make the PW command window smaller, or design your own backdrop window, then use this option to make PW use a standard window. Auto redraw lets you stop PowerWindows from redrawing your window after every change you make. Auto select, when checked, tells PowerWindows that each time you click the left mouse button, or select a gadget, in one of your windows, that the PW command window should be activated. This way, the PW menus are always available. However, if you are doing a significant amount of menu editing, and are not using a drag bar in your window for safe selects, then you may wish to turn this function off so that you can easily select your window in order to inspect your menus. Mouse coordinates, when set, shows the absolute X and Y coordinates of the mouse on the right side of the PW command window's title bar, during certain gadget and text related functions. Gadget collision checking, when checked, makes sure that your gadget hit boxes do not bisect one another. If you disable this, gadgets can appear on top of each other, which can cause some problems for the user. Note that the creators of Intuition strongly discourage this practice. Image color remapping instructs PW to modify the colors of each IFF brush image that you load. The purpose of the modification is to best realize the original intent of the colors used in the IFF image, when working with a palette which is different from that of the image. Image compression makes PowerWindows detect and remove any bitplanes in an image which are all 0 or all 1. The image variables, PlanePick and PlaneOnOff are adjusted accordingly. This saves memory and reduces the amount of ImageData PW generates. Note, however, that if PW performs Image color remapping on an image, then planes that were candidates for compression may be used to represent the remapped colors. Trim extra bitplanes forces each image loaded to consist of no more bitplanes than in the screen onto which it is loaded. If the image is not to be moved at runtime, from one resolution to another, this option simply throws away undisplayed data. Source code comments, when checked, lets you tell PowerWindows to include a comment for almost every line of generated source code, explaining what element of each structure that source line represents. Excluding the comments results in a smaller, less understandable source file. Source code spacing allows you to set the number of spaces PowerWindows will indent each source line with. Alternatively, you can choose TAB as a separator, which is the default. OTHER TOPICS: Repeating commands: The F10 key will repeat the last menu command that you gave to PW. In several instances, however, PW will not allow a command to be repeated because it is no longer valid or because your verification should be required, as in the deletion of text or menus, etc. Cancelling commands: When using the gadget and text commands which require you to click in your window, you can press the "HELP" key at any time to redisplay the OK prompt that explains the current procedure. From that prompt, you can press CANCEL to abort the current command. Using the event-handler: The event-handler that PowerWindows can generate uses the data that you would normally receive in an IntuiMessage from Intuition. You can specify function addresses for gadgets, nemuitems and subitems. There is a string gadget labeled FUNCTION found on the editing requesters for each of these objects which you must fill in with the proper text for your target language. PowerWindows will generate a single event-handler for all of these structures. You process your IntuiMessages in the following ways: Gadgets: wait for an IntuiMessage of GADGETUP or GADGETDOWN get the object address from the IntuiMessage (this is the gadget_address) Reply the message to free Intuition for other tasks invoke the event-handler with HandleEvent(gadget_address) MenuItems and Subitems: wait for an IntuiMessage of MENUPICK get the code field from the IntuiMessage (this is the MENUNUM) Reply the message to free Intuition for other tasks get the item_address from Intuition with itemAddress(MENUNUM); invoke the event-handler with HandleEvent(item_address); The event-handler will, if the gadget or menuitem is matched, execute the indicated function, passing the same object address through to the function as a parameter. Please see the example file for the language your are working in for specific details. Troubleshooting: "I can't get PW to show its menu!": Try clicking in one of your windows and pressing F1. This will bring PW to the front and activate its window. "I can't get my custom menu to display!": Turn Auto Select off and click in your window. Press F1 when finished to return to the PW main menu. Or, select the drag bar, foreground or close gadget of the window and then you can look at your menu. Click inside it again to go back to the PW command menu or press F1. "How do I make a custom knob for a PROPGADGET?": Declare a proportional gadget and load in the IFF brush for the knob. You can load brushes for both the unselected and selected knob render. Ta-da! "When I load in an image, PowerWindows seems to HANG!": PW is just remapping the image. Sometimes, it can take a while. A 320 x 200, 5-bitplane image can take up to 16 seconds to remap. Don't panic, just wait. Or, if you don't need color remapping, turn off the Image color remapping flag under the Preferences menu. "I'm lost and I don't know what to do!": You are probably in the middle of a gadget command. Press HELP. It will tell you what you are doing and let you cancel or continue doing it. If that doesn't work, click inside one of your edit windows or the PW command window and press F1. This should return you to the PW command level.