OVERVIEW: wIconify is an Intuition enhancement program that allows you to "iconify" any Intuition window on any screen. Iconified windows become small icons on at the bottom of the screen, and they can be opened again by double-clicking them, and operate in a fashion similar to Workbench icons. Smart-refresh windows can be turned into simple-refresh windows during iconification in order to save memory. wIconify also allows entire screens to be iconified, though no memory savings occurs by doing this. Past versions of wIconify only allowed windows on the Workbench screen to be iconified, but the current version works for windows on ANY screen. wIconify also includes features that allow you to turn any screen into "a workbench screen"; that is, windows that normally open on the Workbench screen can be redirected to open on any screen whatever. Furthermore, wIconify allows you to open new screens easily for just this purpose. When used with its companion utility, wIconSetter, wIconify allows you to customize the icon imagery for specific windows so that your favorite programs can have distinctive icons. wIconSetter provides a number of methods of producing icon imagery, including converting Workbench .info files to wIconSetter icons. Finally, wIconify provides a programmer's interface that includes all the procedures necessary to create and manipulate icons from within a user- written program. Several examples are provided, including an icon clock with hands that change as time passes. INSTALLING AND REMOVING WICONIFY: To install wIconify, place the WICONIFY command in youre C: directory (or in your current command PATH), and WICONIFY-HANDLER in the L: directory. Alternatively, create a directory named wIconify on you system disk, place WICONIFY and WICONIFY-HANDLER in that directory, and use the PATH ADD command to include this directory in your command path (see the CLI documentation for information on the command path). Now use the ASSIGN command to assign the name WICONIFY: to the directory where you put the WICONIFY command (usually C: or the wIconify directory). You probably want to include this command in the startup-sequence found in the S: directory (see the Workbench 1.3 or 2.0 documentation for information on the startup-sequence file). To start wIconify, simply issue the command 1> wIconify [initfile] where 'initfile' is the name of an optional initialization file that can be used to customize wIconify (see CUSTOMIZING WICONIFY below). If no file is specified, wIconify will look for WICONIFY:wIconify.init or S:wIconify.init as the initialization file. You will probably want to add the WICONIFY command to your startup-sequence. If so, you should be aware that its position in your startup-sequence may be important to the correct operation of wIconify (see WICONIFY AND THE STARTUP SEQUENCE and INTERACTION WITH OTHER PROGRAMS below for more information). There is no need to RUN wIconify, as wIconify will create a new process for the wIconify-Handler automatically. To stop wIconify once it is running, simply issue the wIconify command again, or use the END menu item of wIconify's ICON menu. There are some important subtlties involved with ending wIconify which you should understand; see ENDING WICONIFY below for details. WICONIFYING WINDOWS: Once wIconify is running, you should be able to iconify any window on any screen. To do so, select the window you want to iconify by clicking the left button, and, while holding down the left mouse button, press and release the right mouse button. This is called a "left-right" click. It may feel a little awkward at first, but it will become natural very quickly. Note that this operation is similar to the extended menu selection process already defined by Intuition in which you select multiple menu items by clicking the left button while you have a menu open with the right button (this is called a right-left click). The button or key-stroke that iconifies a window can be customized using the wIconify.init file (see CUSTOMIZING WICONIFY below). When you left-right click in a window, it will disappear and be replaced by a small icon in the lower-left of the screen on which the window was open. Note that the program controlling the window is still running, and can update the window even while it is iconified. Also note that SMART_REFRESH windows will take up MORE memory when they are iconified than when they are visible. This can be altered (for a price); see WICONIFY AND SMART_REFRESH WINDOWS below. The icon will have the same name as the window title so that you can identify the window belonging to each icon. To restore a window from its iconified form, click on the window's icon and select the OPEN item from the ICON menu, or simply double-click on the icon you want to open. The window will be restored and its icon removed. By default, all window icons use the same imagery. This image can be customized using the initialization file (see CUSTOMIZING WICONIFY below). If you use the companion program, wIconSetter, you can use custom icons for individual windows. wIconSetter is easy to use, and makes wIconify much more visually appealing; its use is strongly recommended. See the wIconSetter documentation for more information. Window icons can be manipulated in a fashion very similar to that of Workbench icons: you select one by clicking on it; you select (or unselect) additional icons by clicking them while holding down the SHIFT key; you can drag them from one location to another on screen; finally, you can open icons by double-clicking them. In addition to these operations, the ICON menu includes items that allow you to OPEN iconified windows (restore their windows and remove the icons), CLOSE icons (close the windows associated with the icons), LOCK and UNLOCK icons (prevent them from being moved from their current locations), CLEAN UP the icons ("snap" them to the grid), ORGANIZE the icons (move them all down to the bottom of the screen again), and OPEN ALL icons. See the WICONIFY MENUS section below for more details. Normally, when you open an icon, its last position on screen is retained so that when you iconify the window again, its icon will appear where it was before, unless some other icon already is occupying that spot. Thus you can move an icon to a selected location and expect it to stay there without having to use the LOCK command. Note that programs that use the wIconify programmer's interface may specify that their icons are locked, or that they can not be closed, or that they do not save their last positions, or that their windows can NOT be iconified, so some icons may not respond as the default window icons do. ICONIFYING SCREENS: In addition to being able to iconify windows, wIconify gives you the ability to iconify entire screens, that is, the screen itself will disappear and will be replaced by an icon on the Workbench screen. To do so, simply left- right click in the wIconify backdrop window on the screen you want to iconify (that is, attempt to iconify the wIconify window). The programs using the screen will still be running, and will be able to continue to use and update the windows on that screen, but they no longer will be visible. To get the screen back, double-click on the screen's icon on the Workbench screen. The screen should reappear. By default, screen icons have a different image from window icons, so it should be easy to distinguish them on the Workbench. You can customize the screen icon using the intitialization file (see CUSTOMIZING WICONIFY below). Screen icons can be manipulated just like any other icon; see ICONIFYING WINDOWS for more details on icons and their properties. Since screen icons only appear on the Workbench screen, it is not possible to iconify the Workbench screen itself. The memory in use by a screen is still in use when that screen is iconified, so there is no memory saved by iconifying a screen. It is simply a method of organizing your work area better. ICON LAYOUT: When windows or screens are iconified, their icons appear at the bottom of the screen starting at the lower left-hand corner. As new icons appear, they are placed to the right. This makes it easy to shrink the size of a window slightly, if necessary, to get access to the icons (or you could just iconify the window that's in the way). Alternate columns of icons are staggered (slightly lower) so that long names do not over-write one-another. Once an icon appears on the screen, you can, of course, drag the icon to a new location. Under usual conditions, the icon will retain this position after it is opened and re-iconified, so you should be able to place an icon where you want it to be, and expect it to stay there. Icons will not be placed on top of other icons (unless you drag them their yourself, or unless they are LOCKED), so the screen layout should be realtively easy to view. If it becomes messy, however, there are two menu items that can help. The CLEANUP item of the ICON menu will cause all selected icons to be "snapped" to the icon grid. That is, they move to the closest (unused) grid position to their current location. If no icons are selected, then all the icons on the screen will be cleaned up. Icons with the LOCKED or NOORGANIZE flag set will be unaffected by the CLEANUP command, however. The ORGANIZE item of the ICON menu will cause all icons to "fall" to the bottom of the screen; that is, any icons that have been moved away from the bottom will be put back along the bottom. This puts all icons into their "natural" positions on the screen. As before, and icons marked as LOCKED or with the NOORGANIZE flag set are not affected by ORGANIZE. Currently, there is no method for customizing the initial positions of icons, but a future enhancement may provide the ability to specify that icons should form along the right-hand edge, for example. WICONIFY AND SMART_REFRESH WINDOWS: When a window is covered by another window, and then becomes uncovered, the portion of the window that was obscured must be refreshed to redisplay the information that it contained. Intuition provides windows with a number of refresh methods, the most common being SMART_REFRESH and SIMPLE_REFRESH. The first of these is the easiest and fastest to use, but the most memory- intensive: when a part of the window is covered, Intuition copies the obscured portion to an off-screen memory area and when the window is uncovered again, Intuition restores the contents of the window automatically from the saved data. The program that owns the window never even knows that the window was partially covered. The restoration of uncovered windows is very fast, but if large portions of large windows become covered, this can use up a lot of CHIP memory. The second refresh method (SIMPLE_REFRESH) takes up no additional memory, but requires special programming to implement. In this case, when a portion of window is covered then uncovered, Intuition informs the program that part of its window must be restored, and then the program is required to redraw the information into the window itself. This usually takes longer, depending on the amount of data to be restored, but has the advantage of requiring no additional memory regardless of the size of a window or the amount of it that is covered. There are many situiations when this is an appropriate refresh method; for example, if a window contains only text (no graphics), as in a terminal communications program, it takes far less space to store the contents of the window as ASCII text than as a bit-mapped image. In a nutshell, SMART_REFRESH windows save in program complexity but require more memory when covered, while SIMPLE_REFRESH windows require more programming, but no additional memory. Most programs use SMART_REFRESH windows because they are less complicated and operate faster; for example, the CLI windows are SMART_REFRESH even though they usually include only textual data. wIconify iconifies a window by pushing it behind its own backdrop window, thus covering up the window completely. For SIMPLE_REFRESH windows, this is no problem, but this forces SMART_REFRESH windows to take up the maximum amount of memory (the entire window is copied to memory off-screen). For example, a full-sized CLI window, when iconified, will take up the same amount of memory as the screen itself. The effect of this is that SMART_REFRESH windows typically use up MORE memory when iconified than when displayed. This is unfortunate, but practically unavoidable. Under certain circumstances, however, this behavior can be changed. wIconify provides a method by which you can specify that SMART_REFRESH windows should be treated as SIMPLE_REFRESH windows when they are iconified: if you hold down the left ALT key (called the change-refresh key) when you iconify the window, wIconify will convert the refresh type of the window to SIMPLE_REFRESH while it is iconified (it will be restored to SMART_REFRESH when it is opened again). This means you may save memory when you iconify the window. (The change-refresh key can be changed using the initialization file; see CUSTOMIZING WICONIFY below). Unfortunately, there is a catch. Since the data in SIMPLE_REFRESH windows is lost when they are covered (the program itself must refresh it), and since programs that use SMART_REFRESH windows do not expect to have to refresh their windows, when you restore a window that has been changed to a SIMPLE_REFESH window, its contents will have been lost. Intuition will redraw the border and usually its gadgets (drag bar, depth gadgets, etc.), but any other data in the window will be lost. In particular, it may be impossible to tell where buttons or other "active areas" of the window are located! This may be OK for CLI windows, where the data in the window can be lost without harm, but it may be devastating for programs that have no other copy of the data except for what's in the window itself (art programs, for example). The moral is, use the change-refresh key with care. It can be a big help when you need to save memory, but it can lose information with no hope of recovery! WICONIFY AND THE WORKBENCH WINDOW: In version 1.3 and earlier versions of the Workbench, the Workbench program used a backdrop window on the Workbench screen in order to display and maintain the Workbench icons. For this reason, past versions of wIconify "hooked into" this workbench window in order to place additional icons on the screen. This may have looked good, but was somewhat unreliable in practice, and took considerable and complicated coding to accomplish. In version 2.0 of the Workbench software, it appears that the Workbench program will use a standard (non-backdrop) window with drag bar, sizing gadgets, and other standard Intuition accoutrements. It seems inappropriate, then, for wIconify to continue to hook into this window, so the current version of wIconify opens its own backdrop window instead. This is fine for version 2.0, but what about those of us who still use version 1.3, where the workbench still has its own backdrop window? The Workbench backdrop window will cover up the wIconify window so that it is very inconvenient to get at the window icons. The solution is actually very simple: wIconify converts the Workbench backdrop window into a non-backdrop window and adds the standard gadgets. Take care, however, since this means that the Workbench window will be smaller. Although the Workbench will not move icons outside the visible area of the window itself, you can move them there yourself by shrinking the size of the window. There is no way to get to these icons without enlarging the window again. In order to take advantage of this feature of wIconify, you must start wIconify BEFORE loading the Workbench; that is, the wIconify command must come before the LoadWB command in your startup sequence. wIconify will not modify the Workbench window if it is already open. WICONIFY AND PROGRAM SCREENS Whenever a new screen opens, wIconify attempts to create a backdrop window on that screen. This is were the icons for that screen will be displayed when windows become iconified. It also provides you with the wIconify menu bar on each screen (when the backdrop window is the active one). The backdrop window may provide a number of complications, however. Some programs open their own backdrop windows (art programs for example) which usually are as large as the screen itself. Such windows will completely obscure the wIconify backdrop window, making it impossible to see the icons or even activate the wIconify window to get at its menu bar. The best solution is to iconify the backdrop window that is in the way. This will give you ready access to the wIconify backrop window. If the window is a smart-refresh window, however, this may be inappropriate since it would take up a lot of memory when iconified. Another solution is to press the "activation key" which tells wIconify to activate its backdrop window on the current screen. Usually, this is the F1 function key with SHIFT held down, but it can be changed using the initialization file (see CUSTOMIZING WICONIFY below). This at least gives you access to the wIconify menus, although you still will not be able to see the wIconify backdrop window. The pressence of additional backdrop windows (i.e., the wIconify backdrop window) may cause trouble for some programs. For example, a program that draws directly into the screen's RastPort rather than into its own backdrop window as the Intuition guide suggests, will draw right over top of the icons provided by wIconify. More severe difficulties also are possible; some badly-behaved programs may even crash the system due to the presence of the wIconify backdrop window. In this case, you will want to tell wIconify NOT to open a backdrop window on these screens. You can do so through the IGNORE_SCREEN command in the wIconify initialization file (see CUSTOMIZING WICONIFY below for details). Any screens specified by an IGNORE_SCREEN command will be ignored by wIconify. That is, wIconify will not open a backdrop window on it. Of course, this also means that you will not be able to iconify any windows on that screen either, nor will you be able to iconify the screen itself; wIconify will not re-route workbench windows to this screen, or affect it in any way. If for any reason wIconify fails to be able to open a backdrop window on a newly created screen (for example, there is not enough memory), then wIconify will treat the screen as an ignored screen as described above. SCREEN MANAGEMENT WITH WICONIFY: In addition to its ability to iconify windows and screens, wIconify a provides number of screen-management functions, as described below: Some programs (particulary older software) do not provide access to their screen's depth gadgets, which makes it very inconvenient to have more than one screen open while they are running. wIconify provides SCREEN TO_FRONT and SCREEN TO_BACK menu items which can be used to depth arrange any screen with a wIconify backdrop window. The ICONIFY menu item in the SCREEN menu causes the current screen to become iconified. This is useful on screens where you do not have easy access to the wIconify backdrop window (in order to left-right click it). wIconify gives you the ability to toggle the title bar on or off on any screen (wIconify error messages appear here, but some screens don't have their screen title bars showing). More importantly, however, wIconify gives you the ability to turn any screen into a Workbench screen, that is, a screen that can be shared by windows from many different programs. Normally, a window that does not specify a custom screen will be opened on the Workbench screen. wIconify lets you redirect these windows to any screen. There are a number of features that control this aspect of wIconify. First, the OPEN_WINDOWS submenu of the SCREEN menu controls the screen on which workbench windows will be opened. There are three choices: ACTIVE_SCREEN Open windows on the currently active screen CURRENT_WB Open windows on the screen currently marked as the Workbench screen via the MAKE_WB menu item REAL_WB Open windows on the real Workbench screen The first of these is the default; new windows will appear on whichever screen you are using. Sometimes this is not the most convenient method, however, particularly if you must give a command on another screen in order to open the window you want to appear on the current screen. In this case, the second option might be more appropriate. Using this method, you can mark a screen as the one you want to use, then select some other screen to give one or more commands that usually open windows on the Workbench screen; all these windows will open on the screen you have marked as the WB screen via the MAKE_WB menu item. This is particularly convenient if you are using wIconify as part of your startup sequence and you want windows to be moved to other screens as your machine is booting (see WICONIFY AND THE STARTUP-SEQUENCE below). The WB_TO_FRONT menu item will bring the current WB screen to the front of the display. If you select MAKE_WB, the screen becomes the current WB screen, and CURRENT_WB mode is selected automatically. Finally, if you do not want wIconify to change the screens where windows are opened, select the third option above. Note that only those windows that don't request a specific screen are effected by the OPEN_WINDOWS settings; all windows that usually open on a custom screen will still open there regardless of the setting of OPEN_WINDOWS. The OPEN_WINDOWS submenu also includes a SIZE_TO_FIT option. Since some screens are not as large as the Workbench screen, some windows that usually open on the Workbench screen might not be able to open on the active screen. For this reason, wIconify may resize a window in order to make it fit on the screen. When a window would not fit on the specified screen, wIconify first looks to see if the window has a drag bar; if it does, then wIconify tries to move the window so that it will fit on the screen. If not, or if the window is still too big, wIconify checks to see if the window has a sizing gadget (or if it accepts NEWSIZE messages). If so, wIconify will change the size of the window to fit on the screen, and will send a NEWSIZE message to the altered window. If none of the above conditions hold, wIconify will attempt to open the window unaltered. Some badly-behaved programs, however, use the failure of an OpenWindow() call to determine whether the Workbench screen is interlaced or not by attempting to open a very tall window. In this case, wIconify may "fix" the window to fit, and the program will incorrectly believe that the screen is interlaced when it may not be, and will overestimate the amount of space available to it. Under such circumstances, you may wish to turn off the SIZE_TO_FIT menu. If you do, wIconify will never attempt to alter the size of a window when it is opening. This may cause some windows to fail to open, particularly on small screens. You can customize the initial settings of the OPEN_WINDOWS submenu using the wIconify initialization file (see CUSTOMIZING WICONIFY below). One of the reasons that Intuition usually does not allow programs to share a screen is that one program could close the screen while the other was still using it, which would cause a system crash. wIconify overcomes this problem by keeping track of the windows that it has opened on other screens; a screen will not be allowed to close until all "foreign" windows have been closed first. Thus it is completely safe to use wIconify to open windows on other screens. SCREENS CREATED BY WICONIFY: Since wIconify allows you to turn any screen into a Workbench screen (as described in SCREEN MANAGEMENT WITH WICONIFY above), it is convenient to have a method of creating screens expressly for this purpose. wIconify provides this in the form of the NEW_SCREEN submenu of the SCREEN menu, which lets you choose the depth and resolution of the screen to be created. To create a new screen, choose the resolution options you want (HIRES, LORES, INTERLACE, HAM), and then select the depth. When you choose a depth item, wIconify opens the new screen with the given specifications. The resolution items are updated to the values for the current screen whenever the active screen changes, so it is most convenient to create a new screen from one that is already of the resolution you want. The actual width and height of the new screen are calculated from the width and height of the current screen (doubling or halving as necessary to accommodate the resolution requested). The depth, of course, is up to you, except for HAM mode screens, which always are 6 bitplanes deep (select any depth for HAM screens; wIconify will substitute 6 automatically). The colors for the new screen are the Intuition default colors, unless you specify a new color map using the initialization file (see CUSTOMIZING WICONIFY below). Once the screen is created, it becomes the current WB screen automatically (although the OPEN_WINDOWS option is not changed, so if ACTIVE_SCREEN is selected the current WB will have no effect). The new screen is activated and ready to be used. You can open as many wIconify screens as you have memory for. wIconify screens can be very useful for keeping your Workbench less cluttered. If you want to close a wIconify screen, use the CLOSE_SCREEN item of the SCREEN menu. It will be available only on wIconify-created screens, and only when the screen has no windows or icons open on it. All the menu items (except screen depths) have visible command-key equivalents. The depths have command-key equivalents as well, but they are not visible. The right-Amiga key together with a number from 1 to 5 (either on the keypad or the main keyboard) is equivalent to selecting one of the depths in the submenu. NEWCLI'S CREATED BY WICONIFY: Another useful feature of wIconify is its ability to create new CLI processes at will. The NEW_CLI item of the SCREEN menu causes wIconify to attempt to start a new CLI process on the screen where the command was given. The default command used by wIconify is NEWSHELL, but you can customize this in the initialization file (see CUSTOMIZING WICONIFY below). In fact, you can give a separate command for HIRES screens and LORES screens, in case you need to specify window sizes in the command. When you select NEW_CLI, the active screen becomes the current WB screen, but the setting of the OPEN_WINDOWS menu does not change. wIconify uses the AmigaDOS Execute() routine to perform the NEW_CLI command. The Execute() routine requires that you have the RUN command available in your C: directory (it does not look through the command path, but looks in C: directly), so if you get a system requester for your startup disk, that's probably why. There are a number of important aspects of the newly created process that you should be aware of when you use the NEW_CLI menu. First, due to the way the wIconify process is set up initially, the newly-created process does not inherit a command path. Second, despite the best efforts of the author, it does not inherit a current directory, either. The current directory turns out to be NULL, which is supposed to mean the root of the initial startup disk. Unfortunately, this does not always seem to operate correctly. It is a wise precaution to perform a CD command even if you want to use the root of the startup disk. Third, the newly-created process's system-error screen is by default the (real) Workbench screen. Fourth, the command stack size of the new precess is not inherited; you will have to set this yourself if necessary. Finally, the newly-created process has input and output redirected to NIL:. There are a number of methods you can use to overcome these problems. For the first two problems, you can explicitely state the path to the command (or use an ASSIGNED path if you want to be able to change it). For the third problems, wIconify provides a separate utility program called wSetSysRequest that set the screen for the system error messages to the currently active screen. You should create a file that contains the wSetSysReqest command on one line then the command you want executed on the next. Finally, have NEW_CLI perform an EXECUTE command specifying the file you just created as the file to perform. You any also want to include a PATH and CD command in the file. For the fourth problem, you need to add a STACK command to the file that you EXECUTE. Finally, for that last problem, simply include command redirection on the command you want to perform so that it opens a CON: or NEWCON: window itself. If you want the NEW_CLI menu to perform a NEWCLI or NEWSHELL command, there is a particularly easy way to do this. Create a file in your S: directory called 'wIconify-CLI-Startup' that includes the CD, PATH, wSetSysRequest, and STACK commands described above. Then, use the initialization file to specify the NEW_CLI command to be NEWCLI FROM S:WICONIFY-CLI-STARTUP or NEWSHELL FROM S:WICONIFY-CLI-STARTUP according to your preference of CLIs. This will cause the NEW_CLI command to open a new CLI that already has the proper CD, PATH, etc. set up. You may also want to include the command EXECUTE S:CLI-STARTUP or EXECUTE S:SHELL-STARTUP if you want the new CLI to perform the startup commands you usually use (see the AmigaDOS manual for more information on the CLI, Shell, and startup files). THE WICONIFY MENUS: Every wIconify window has two main menus, the ICON menu and the SCREEN menu. These are described below: The ICON menu includes the items that manipulate icons: OPEN Opens all selected icons (restores their windows and removes the icons from the screen) CLOSE Attempts to close the windows associated with the selected icons. This option is only available to windows that have Intuition close gadgets. LOCK Marks the selected icons as locked; that is, wIconify will not allow them to be moved by dragging, and they will be unaffected by the CLEANUP and ORGANIZE menus. UNLOCK Unlocks the selected items; i.e., allows them to be moved again. CLEAN UP Moves the selected icons to the closest "grid" positions. If no icons are selected, all (unlocked) icons are cleaned up. ORGANIZE Moves all (unlocked) icons to the bottom of the screen. OPEN ALL Opens all icons on the screen (without your having to select them all). ABOUT Displays a short message detailing the program name, author and copyright notice. This display appears in the screen's title bar area. END Attempts to end wIconify. This requires the RUN command in the C: directory, and access to the wIconify command in the WICONIFY: directory. wIconify will not end until all "foreign" windows are removed from custom screens, all icons created by the programmer's interface are closed, and all wIconify screens are removed. See ENDING WICONIFY below for more details. The SCREEN menu contains commands to manipulate screens: TO FRONT Brings the selected screen to the front. TO BACK Sends the selected screen to the back. WB TO FRONT Brings the current WB (as defined by the MAKE WB menu) to the front. TOGGLE TITLE Hides/shows the screen's title/menu bar. ICONIFY Iconifies the selected screen; the screen will disappear and be replaced by an icon on the Workbench screen. NEW CLI Attempts to open a new CLI window on the current screen, and makes the screen the current WB screen. This requires the RUN command in the C: directory. The actual command executed is set by the initialization file, and is the NEWSHELL command by default. See NEWCLI'S CREATED BY WICONIFY above for more details. MAKE WB Marks the selected screen as the current WB screen, and selects the CURRENT WB item in the OPEN WINDOWS menu. wIconify will open windows on this screen that would normally be opened on the Workbench screen. OPEN WINDOWS Specifies where and how windows will open that normally would be directed to the Workbench screen. ACTIVE SCREEN Windows open on the current active screen. CURRENT WB Windows open on the screen marked as the current WB screen by the MAKE WB menu. REAL WB Windows open on the (real) Workbench screen as usual. SIZE TO FIT Windows that are too big for the screen where they will open will be resized to fit on the screen. NEW SCREEN Allows you to open new screens for use as WB screens. 1 2 3 4 5 Specifies the depth of the screen to open. The screen is opened as soon as the depth is selected. The command-key equivalents are right-Amiga plus the depth (either on the keypad or main keyboard). HIRES Sets the horizontal resolution to HIRES (usually 640 pixels across). LORES Sets the horizontal resolution to LORES (usually 320 pixels across). INTERLACE Sets the vertical resolution to Interlaced (usually 400 pixels down) or Non-Interlaced (usually 200 pixels down). HAM Set the special HAM (Hold-And-Modify) mode. This is not available in HIRES INTERLACE mode, but in all others. Any depth will be converted to 6 bit planes automatically. CLOSE SCREEN Attempts to close a wIconify-created screen. This is only allowed when all the windows and icons are removed from the screen. The menu command-key equivalents can be customized via the initialization file; see CUSTOMIZING WICONIFY below. CUSTOMIZING WICONIFY: Many parts of wIconify can be customized, including the icon imagery, the button or key-stroke that iconifies a window, the menu command-key equivalents, and many other features. To change any of the defaults, you must supply a wIconify initialization file, which you can specify on the command line when you start wIconify. For example: 1> wIconify wIconify.init If you do not specify a file, wIconify will look for WICONIFY:wIconify.init and if it is not found, it will look for S:wIconify.init. If neither is found, it will use the default values for everything. The wIconify.init file is a text file that you can create or edit using any text editor, such as ED, EDIT, or Emacs. A sample initialization file, Sample.init, is provided as part of this distribution. The initialization file should contain a series of commands that specify what defaults you want to change. Each command keyword must be followed by a colon (':'), and you should have only one command per line. Some commands can take up more than one line. Blank lines are ignored, in general, although a blank line will end a multi-line command. You can include comments in your initialization file in two ways. First, the semi-colon (';') is a comment character, which means that everything on the line past the semi-colon will be ignored. This is the same as for the CLI. The Sample.Init file has numerous examples of the use of the semi-colon as a comment. The second type of comment is not line-oriented; instead, it is delimited by a comment initiator and a comment terminator. These are '/*' and '*/', respectively. They are the same as the comment characters in the C programming language. You can nest comments within comments, as in the following example: /* This is a comment /* inside */ another comment */ Be careful that you pair these together properly, or you may find that your whole initialization file becomes a comment! The commands allowed within the initialization file are the following: Format: ICONIFY_KEY: qualifiers keyname This specifies the key or button press that causes windows to become iconified. The default is the left-right click. Qualifiers can be separated by spaces, pluses (+), or bars (|), and the keyname should be separated from the qualifiers by a space. If a qualifier name is preceded by a dash (-) this specifies a "disqualifier", that is, the specified qualifier must NOT be pressed when the key is pressed; such qualifiers prevent the key-press from iconifying windows. The qualifiers must be chosen from the following list: LSHIFT The left SHIFT key RSHIFT The right SHIFT key CAPSLOCK The Caps Lock key CONTROL The CTRL key LALT The left Alt key RALT The right Alt key LCOMMAND The left Amiga key RCOMMAND The right Amiga key LAMIGA The left Amiga key (same as LCOMMAND) RAMIGA The right Amiga key (same as RCOMMAND) NUMERICPAD The key is on the numeric keypad LBUTTON The left mouse button RBUTTON The right mouse button MBUTTON The middle mouse button (future expansion) The keyname must be one of the following: LBUTTONPRESS The left button RBUTTONPRESS The right button F1 The F1 key ... F10 The F10 key ESC The ESCape key ENTER The ENTER key on the keypad RETURN The RETURN key BACKSPACE The Back Space key DELETE The DEL key HELP The HELP key TAB The TAB key SPACE The space bar \nn The key with keycode 'nn' where 'nn' is a HEX value; for example, \4C is the up-arrow key. (see the ROM Kernel Manual for a list of keycodes) Examples: ICONIFY_KEY: LBUTTON RBUTTONPRESS ; this is the default ICONIFY_KEY: LSHIFT F2 ; F2 with LSHIFT held down ICONIFY_KEY: LSHIFT-RSHIFT ENTER ; ENTER with LSHIFT but not RSHIFT ICONIFY_KEY: LSHIFT+RSHIFT ENTER ; ENTER with LSHIFT and RSHIFT ICONIFY_KEY: F6 ; F6 with no special qualifiers Format: CHANGE_REFRESH: qualifiers This specifies the qualifier keys that cause SMART_REFRESH windows to be converted to SIMPLE_REFRESH windows when they are iconified. The default is LALT. If the qualifiers specified are held down when the Iconify-Key is pressed, then the window's refresh type will be changed, otherwise it will remain unchanged when it is iconified. The qualifiers must be chosen from the list given above, and can be separated by a space, a plus (+) or a bar (|). Disqualifiers are not allowed in the CHANGE_REFRESH specification. Examples: CHANGE_REFRESH: LALT ; the default CHANGE_REFRESH: CONTROL+LSHIFT Format: ACTIVATION_KEY: qualifiers keyname The specifies the key or button press that activates the wIconify backdrop window on the active screen. By default it is LSHIFT F1. The qualifiers, disqualifiers, and keyname are specified as in ICONIFY_KEY above. Examples: ACTIVATION_KEY: LSHIFT F1 ; the default ACTIVATION_KEY: LSHIFT-LALT F1 ; LSHIFT F1 when LALT is not pressed Format: COLOR_MAP: rgb ... This command specifies a color map to be used for all wIconify screens created by the NEWSCREEN menu (or wIconScreen command). The lines following the COLOR_MAP command specify RGB gun intensities for each color, color 0 being the first line, color 1 being the second, etc. The RGB values are specified as HEX digits (0-F) representing 0 to 15. For example, F00 is bright red, FF0 is yellow, 888 is grey, etc. You can use the Palette or Preferences tools provided with the Workbench to experiment with different color values. There are also two special color values. If the first character in the color specification is an equal sign (=) or an asterisk (*), this means that the color should be the default color used by Intuition (the first four colors are set by the Preferences tool, and the others are the default ugly colors). Example: * ; use the default WB background color * ; and the default forground color 888 ; but use grey for color 2 FFF ; and white for color 3 ; additional colors could go here for screens with more bitplanes. Format: MENU_KEYS: menuname letter menuname letter ... This command specifies the menu command-key equivalences. Here, menuname represents the name of one of the menus (e.g., OPEN, CLEAN_UP, ACTIVE_SCREEN), and the letter following it is the key to be used as the command-key equivalent; it must be a printable character. If no letter follows the manu name, then this menu will not have a command-key equivalent. It is not possible to change the command-key equivalents of the depth items in the NEW_SCREEN menu, but all other items can be modified. Note that spaces in menu names are replaced by underscores. For submenus, just the name of the submenu itself is used as the name. Example: MENU_KEYS: OPEN O CLOSE C LOCK # CLEAN_UP K ORGANIZE R OPEN_ALL P ABOUT ? END ACTIVE_SCREEN A CURRENT_WB W REAL_WB = SIZE_TO_FIT S Format: DEFAULT_FLAGS: flags This specifies the icon flags that will be set automatically for all window icons created by wIconify. If no flags are provided, then no special flags are applied when a new icon is formed. The flags can be separated by spaces, plus signs (+), or vertical bars (|), and must come from the following list: CHANGEREFRESH SMART_REFRESH windows will become SIMPLE_REFRESH when they are iconified LOCKED The icons will be locked NOMOVE The icons will not be allowed to be dragged NOCLOSE The CLOSE menu will be unavailable for these icons NOORGANIZE The ORGANIZE menu will not affect these icons NOSAVEPOS The window's icon will go to the bottom of the screen every time it is iconified NOMULTISELECT The icons can only be selected one at a time NOICONIFY The windows will not be able to be iconified again These flags are part of the programmer's interface, and most of them do not make sense to use as the default window icon flags, except perhaps CHANGREREFRESH and perhaps NOSAVEPOS. They are provided for completeness. Examples: DEFAULT_FLAGS: ; default is no special flags DEFAULT_FLAGS: CHANGEREFRESH ; change SMART to SIMPLE refresh DEFAULT_FLAGS: CHANGEREFRESH | NOSAVEPOS Format: SCREEN_FLAGS: flags This specifies the icon flags to be given to screen icons when they are created. The flags are specified as for DEFAULT_FLAGS above, and must be chosen from the same list of options. The CHANGEREFRESH flag has no effect for screen icons, however. Screens automatically get the NOCLOSE flag. Format: IGNORE_SCREEN: screen1 screen2 ... This command specifies the names of screens that should be ignored by wIconify. wIconify will not open a backdrop window on these screens, windows on these screens will not be able to be iconified, nor will wIconify route Workbench windows to these screens. These screens are completely ignored by wIconify. The name of a screen need not be its complete name; you only need to specify enough of the name to distinguish it from other screens. Upper and lower case letters are not distinguished, but spacing is important. If the screen name has leading or trailing spaces, you will need to enclose it in single quotation marks ('). If you need a single quote within the the single quotes, use two single quotes in a row (''). A screen with no title is specified by empty quotes (''). If you do not use quotes around the name, the entire line (minus any leading and trailing blanks) is used as the name. Examples: IGNORE_SCREEN: ' A screen with leading blanks' '' ; no title A full-line title Format: HIRES_CLICOMMAND: command-string LORES_CLICOMMAND: command-string These commands specify the commands performed by the NEWCLI menu item. The command string can be enclosed in quotation marks (as described in IGNORE_SCREEN above), or can be the rest of the line. See NEWCLI'S CREATED BY WICONIFY for information about the current directory, etc., used by this command. The LORES command is used whenever the NEWCLI menu is selected on a LORES screen, and the HIRES command is used otherwise. If no LORES command is given, then the HIRES command will be used instead. The default commands are 'NEWSHELL' for the HIRES command, and nothing for the LORES command. Examples: HIRES_CLICOMMAND: NEWSHELL ; the default HIRES_CLICOMMAND: NEWSHELL FROM S:WICONIFY-SCRIPT HIRES_CLICOMMAND: 'EXECUTE WICONIFY:NEWCLI-COMMAND' HIRES_CLICOMMAND: NEWSHELL NEWCON:0/10/640/100/AmigaShell LORES_CLICOMMAND: NEWSHELL NEWCON:0/10/320/100/AmigaShell Format: COMMAND_STACK: stack-size When you select the NEWCLI menu, a separate process is created to perform the CLI command that you want executed (usually this is NEWSHELL, but you can specify another command using the HIRES_CLICOMMAND or LORES_CLICOMMAND commands described above). In the default case, this process simply performs the NEWSHELL command (creating the new shell), then exits, but if you change the command to something else, you may want a larger stack than the default 4K. The COMMAND_STACK command lets you specify the stack size. Examples: COMMAND_STACK: 2048 ; a 2K stack COMMAND_STACK: 10240 ; a 10K stack (a good size) Format: OPEN_ON: screen-type This command specifies the setting of the OPEN WINDOW submenu. The valid screen-types are: ACTIVE_SCREEN, CURRENT_WB, and REAL_WB. These specify where windows will open that usually would open on the Workbench screen. ACTIVE_SCREEN specifies that they will open on the currently active screen, CURRENT_WB indicates that they should open on the screen you selected with the MAKE_WB menu item, and REAL_WB means they should open on the Real Workbench screen (i.e., wIconify should not change where windows open). The default is to open windows on the active screen. Example: OPEN_ON: ACTIVE_SCREEN ; The default Format: SIZE_TO_FIT: TRUE-or-FALSE This command sets the SIZE_TO_FIT item of the OPEN_WINDOWS submenu. If you specify TRUE, wIconify will resize windows, if necessary, in order to allow them to open on screens other than the Workbench. If you specify FALSE, wIconify will not adjust the window sizes (some attempts to open windows on small screens may fail). The default setting is TRUE. Examples: SIZE_TO_FIT: TRUE ; the default SIZE_TO_FIT: FALSE ; the only other choice Format: DEFAULT_IMAGE: bitmap-data bitmap-data ... This command allows you to specify the image to be used by new icons (that don't specify their own images). Each of the lines that follow the DEFAULT_IMAGE command becomes a row of the image. Each character on the line (past the opening blanks) represents the pen color of one pixel of the row. For a 2 bit-plane screen, the colors range from '0' to '3'; for 3 bit-planes they are from '0' to '7'; For 4 bit-planes, they are '0' to '9' and 'a' to 'f' (these must be lower case letters); for 5 bit-planes, they are 0-9 and a-f for the first sixteen pen colors, and then SHIFT 0-9 and SHIFT A-F for pens from 16 to 31. That is, ')' is pen 16, '!' is pen 17, '@' is pen 18, '#' is pen 19, up through '*' as pen 24 and '(' as pen 25. Then 'A' is pen 26, up through 'F' as pen 31. This allows you to specify a 5-bitplane image if you want. Be careful that your images make sense in fewer bitplanes, though. You want to use a mix of even and odd numbers so that something will show up on one bit-plane screens. The standard size, is 41 by 18, though you can specify larger or smaller icons if you want. The maximum size is 78 by 32 (the size of the icon grid spacing). wIconify will warn you if your image exceeds this amount. See the Sample.Init file for a complete example of how to specify an image. Format: DEFAULT_SELECT: bitmap-data bitmap-data ... This command specifies the image to be used when the icon becomes selected. If no DEFAULT_SELECT command is given, then the select image will be an inverted copy of the default image. If a select image IS given, it should be the same width and height as the default image. The bitmap-data has the same form as the DEFAULT_IMAGE above. See the Sample.Init file for a complete example of specifying a select image. Format: DEFAULT_MASK: mask-data mask-data .... This command specifies the image mask to be used with the default icon. The mask data has the same format as the image bitmap-data described above, except that only pen values of 0 and 1 are allowed. A 0 represents places where you can "see through" the icon when it is being dragged. If a select image was given, the mask is associated with the selected image, otherwise, the mask is associated with the image itself as well as with its inverted select image. The mask data must be the same size as the other two images. In addition to determining what part of the image is invisible, the mask also is used as a "hit mask"; that is, when selecting an icon with a mask, you must click on one of the pixels that is a 1 in the mask data. If a select image was specified, the mask will be used as a hit mask only when the select image is showing, otherwise it will be used all the time. The example in the Sample.Init file has a mask with fairly large "holes" in it that you can experiment with. Format: DEFAULT_ICON: filename It is sometimes more convenient to have the bitmap data for the default icon stored in a separate file (for example, a file created by one of the wIconSetter icon-creation utilities). In this case, you can use the DEFAULT_ICON command to specify the file that contains the icon imagery. This file can contain three commands: ICON, SELECT, and MASK. These have the same format as DEFAULT_IMAGE, DEFAULT_SELECT, and DEFAULT_MASK above. No other commands are allowed in the icon file itself. Example: DEFAULT_ICON: WICONIFY:Window.Icon Format: SCREEN_IMAGE: SCREEN_SELECT: SCREEN_MASK: SCREEN_ICON: These commands have the same format as the corresponding DEFAULT commands described above, however, these ones determine the default imagery for the screen icons, whereas the previous ones are for the default window icons. Format: PRIORITY: n This specifies the priority for the wIconify handler process (the process that maintains the icons and wIconify backdrop windows). The default priority is 0, but you may want to bump this up to 5 or so. The trackdisk device runs at priority 5, the DFn: file-system tasks run at priority 10, and the Input.Device runs at priority 20. You must specify a priority in the range -128 to 127, though it probably is unwise to go above 10 or below 0. Examples: PRIORITY: 0 ; the default PRIORITY: 5 ; wIconify runs before the CLI's Format: HANDLER_PRIORITY: n This command specifies the priority in the Input.Device input handler chain of wIconify's input handler. The default is 51, which puts it just in front of Intuition (which is at priority 50). Many utilitiy programs install their own input handlers, and it may be necessary to use the priorities to adjust the sequence in which these get to see the input events. Too many programers have used priority 51 (inlcuding the author), and have hard-coded the priority into their programs. It is time that this begins to change. Examples: HANDLER_PRIORITY: 51 ; the default HANDLER_PRIORITY: 53 ; a little bit earlier in the input chain HOW WICONIFY WORKS: wIconify is made up of five distinct parts: an Input.Device input handler, the traps to the Intuition routines, an AmigaDOS process, the loader, and the programmer's interface. Each of these operates within different process contexts, which makes for extremely delicate and complex interaction among these components. The Input.Device handler is the smallest piece. Its job is to search the input chain for left-right mouse clicks (or whatever key is specified as the iconify key), remove them and inform the handler process about them. In the same way, it looks for the wIconify activation key (SHIFT F1) and activates the wIconify backdrop window when found. Finally, the handler also checks to make sure that iconified windows and screens do not become activated accidentally (input events should only go to non-iconified windows). wIconify traps a number of Intuition routines, namely OpenWindow(), CloseWindow(), OpenScreen() and CloseScreen(). The OpenWindow() trap checks to see if the window should be opened on a different screen, and if so, check whether it needs to be resized before it attempts to open the window. It also maintains the data required to tell when all the "foreign" windows have been removed from a screen. Finally, it looks for the Workbench window opened by LoadWB and modifies it to include standard border gadgets, etc. The CloseWindow() trap checks to see if the window has an icon, and if so requests the handler process to remove the icon. If the window is on a "foreign" screen, it updates the data needed to determine when it is safe to close a shared screen, and if the screen is waiting to close, it may signal that it is OK to be closed. The OpenScreen() trap checks if the newly-created screen is one that it is supposed to ignore, and if not, it tries to open the wIconify backdrop window on the screen. The CloseScreen() trap first attempts to remove any icons that it can from the screen, then it waits for any "foreign" windows to be closed and any icons to be removed by the user. Finally, it closes the wIconify backdrop window and closes the screen. wIconify also traps a number of other routines, specifically, WindowToFront(), WindowToBack(), and ActivateWindow(). These traps check that the window being specified is not and iconified window. This prevents iconified window from reappearing or becoming activated accidentally. Finally, wIconify traps the wSetWindowTitles() routine in order to update the name of an icon if its window title changes. Finally, wIconify traps AutoRequest(), BuildSysRequest() and FreeSysRequest(). These routines open (or close) windows, but since they are part of the Intuition library itself, and since Intuition does not call its own vector table, these rooutines bypass the traps that wIconify has installed in OpenWindow() and CloseWindow(). In order to properly handle the windows created for System Requests, wIconify also must trap these routines. In BuildSysRequest(), the windows are handled almost exactly as normal windows are, except that if the calling task is a Process and that process has an error window defined (by wSetSysRequest, for example), then the window will be opened on the screen containing that window regardless of the settings in the OPEN_ON menu. Window opened by BuildSysRequest() are new fully supported by wIconify: they can be iconified and manipulated as usual, their icons will be removed when they close, and their presence on a "foreign" screen will prevent that screen from closing before the system request is completed. The AutoRequest() routine presents more of a challange, since it does not return control until after the system request window has been completed. Thus wIconify never gets the chance to manipulate the window it creates, either to move it to another screen, or to maintain the internal data required for an icon. For this reason, the AutoRequest() routine has been completely replaced by an equivalent routine. This routine calls (the modified) BuildSysRequest(), and then waits for the user to complete the request. The action of the AutoRequest() routine is well-documented in the Intuition manual, so this replacement should be indistinguishable from the original under normal circumstances. All these traps run in the context of the process or task that calls the trapped routine, not in the context of the wIconify handler process, so they do not manipulate the linked lists of icons directly. Rather, they communicate with the wIconify handler process via Exec messages. The main handler process is the central component of wIconify, and it has a number of jobs. First, it is in charge of maintaining the linked lists of icons, screens, windows, etc. that are used by wIconify. Since the different parts of wIconify all run asynchronously under different process contexts, the lists could get seriously tangled if more than one process were trying to modify them at once. For this reason, the handler process is the only one that adjusts the icon lists (although the screen and window lists are maintained by the trap routines). The handler responds to requests from the Input.Device handler and the Intuition Trap routines to add or remove icons. This includes the actual "removal" and restoration of windows and screens as they are iconified. The second job of the handler is to manage the wIconify backdrop windows and the Intuition events associated with them. This involves the actual drawing of the icons as well as processing the mouse clicks and moves that cause icons to be selected, dragged, and opened. It also includes responding to all menu selections, and updating the menu items as needed. This includes opening and closing new screens, and starting NewCLI processes. Finally, the handler also responds to requests from other programs that use the wIconify programmer's interface to manage their own icons. This includes adding, removing, and selecting icons, iconifying and restoring windows and screens, and looking up information about icons. See the wIconify programmer's interface documentation for more information. The loader is the portion of wIconify that is actually named "wIconify" (the Input.Device handler, Intuition traps, and handler process all are encapsulated in the "wIconify-Handler"). Its job is to load the handler code into memory and set up the data needed by the different components of the handler, install the traps and Input.Device handler, and start the handler process itself. A major portion of this job is to read and process the intialization file and report any errors with it. If the loader detects that the handler already is loaded, then the loader signals the handler that it should attempt to quit running. When the handler responds that it is done, the loader will remove the traps and input handler, and then remove the handler process from memory. Although the handler is over 30K in size, it has been streamlined as much as possible. In particular, any non-essential functions have been moved to the loader. Thus all the initialization and run-down code is in the loader not the handler. In fact, the handler process can not end on its own; it requires the loader to help it out. When you choose the END item in the ICON menu, the handler process attempts to Execute() the wIconify command as a separate process just as though you typed wIconify again yourself. See ENDING WICONIFY for more details. In order to iconify windows, wIconify turns them into BACKDROP windows and then sends them to the back. They fall behind the wIconify backdrop window where they can no longer be seen, which makes them seem to disappear. This has some serious implications concerning memory usage; see WICONIFY AND SMART_REFRESH WINDOWS above for more details. To iconify screens, wIconify simply moves them below the visible area of the display; thus they seem to disappear. The legality of this is not strictly clear. It is not prohibited by the Intuition guide, but it may cause unforeseen problems. Note that in both cases, the screens and windows are not actually removed. They still exist and are usable by the programs that created them. Every effort was made to prevent iconified windows from becoming activated or depth-arranged accidentally, but the fact that they exist when they appear not to may cause some problems with some programs, such as hot-key programs that allow you to depth-arrange windows or screens. For example, these programs may not cycle the screens correctly. wIconify attempts to push iconified screens to the back whenever possible, so if your hot-key program pulls it to the front, wIconify will immediately push it to the back again. ENDING ICONIFY: As you can see from the description above, wIconify is a complex system, with a variety of connections into the system software and application programs. Shutting down and removing such a system is far from easy. Nevertheless, the author feals that you should be able to remove any peice of optional software without having to reboot the machine (apparently the authors of the Workbench don't agree), so he has provided the END menu item for this purpose. Simply selecting END may not end wIconify, however. A number of conditions must be met in order to ensure that wIconify can end safely. First, the END menu item uses the Execute() AmigaDOS routine, which requires the RUN command to be in the C: directory (it looks directly into the C: directory, bypassing the command path altogether), and it requires that WICONIFY: be assigned to the directory where the wIconify program is stored (usually C: or the wIconify directory). Second, all icons must be removed from all screens (wIconify will open window icons and remove AUTOREMOVE icons automatically when you ask it to END, but icons created by other programs may require you to closed them individually before END will operate). Third, all "foreign" windows must be removed from shared screens (you must close these manually). Fourth, all wIconify-created screens must be closed (wIconify automatically will close any screens that have no windows, but you will have to close any windows on wIconify screens before they will be closed). Fifth, wIconify will not end while there are un-replied messages associated with the wIconify programmer's interface, or with closing or resized windows. Finally, if the Intuition routines trapped by wIconify have been re-trapped by some other program, wIconify may not be able to restore its own traps, hence will not end. The last two of these are particularly hard to detect. In both cases, it will appear that wIconify has ended (there will be no more visible signs of its operation), but the process will still be running and the memory in use by it will not be freed. Furthermore, there is virtually nothing you can do about un-replied messages; if a program fails to reply to a message, there is no way for you to get around this, but it would be unsafe for wIconify to end without waiting for all its messages to be returned. The problem with the traps is a design flaw with the SetFunction() mechanism: the programs that use SetFunction() must be removed in the opposite order from which they were started. Fortunately, there is a solution. The author of wIconify also wrote a program called PatchSetFunction which makes it possible to add and remove traps in any order. He strongly recommends that you use this program, especially if you have lots of system-modifying programs like wIconify. The program can be obtained from the author. The other conditions can be met simply by closing windows or icons, and by providing the proper directory name assignments. This all probably seems pretty complicated just to end a program, but the author wishes to be as safe as possible. Despite this effort, however, there are still possible places where problems can occur. In general, if you are not using any programs that use the programmer's interface, you are probably safe in ending wIconify at any time. If you use programs that supply their own icons (particulary icons with no windows attached), it is best if you end these programs first before attempting to end wIconify. If wIconify fails to end (one of the above conditions is not met), then wIconify may be left in "limbo". When wIconify is trying to end, it will not allow new windows to become iconified, and may not open new screens, etc. This is a particularly delicate time for wIconify (many unforeseen conditions can occur internally during this phase), so you should try to minimize it, when possible, by closing windows, screens and icons BEFORE requesting wIconify to end. Once all the conditions are met, wIconify will end on its own (there is no need to request it to end again). If you used the wIconify command to end iconify (rather than the END menu) the wIconify command will not complete until the handler has ended. If you feel that the handler will not be able to end, you can cancel wIconify by pressing CTRL-C. DO THIS ONLY AS A LAST RESORT, however, since if the handler is able to end, there will be no loader ready to clean up after it! At this point, issuing another wIconify command will cause the handler to go through its shut-down process again, although if it didn't succeed the first time, it probably won't do so now. When you use the END menu item to end wIconify, the handler actually executes the loader as a separate process via the Execute() routine. If wIconify fails to end properly (for one of the reasons above), this process will still be waiting for it to end. Selecting END again will cause additional processes to be started. You can use the STATUS command to see if any of these are still active, and if so, you can use the BREAK command to send a CTRL-C to those processes if you want to remove them. See the AmigaDOS manual for information on the STATUS and BREAK commands. WICONIFY AND THE STARTUP SEQUENCE: wIconify usually should be part of your startup sequence, and its position within the startup-sequence file is important. If you are using wIconSetter, you should put the wIconify command early in the sequence (before too many windows are open) and the wIconSetter command immediately after it. If you want wIconify to work properly with the Workbench window (see HOW WICONIFY WORKS above), you should put the LoadWB command after the wIconify command. A number of other programs also have interactions with wIconify that may be dependent on the order in which they are installed relative to wIconify. See INTERACTIONS WITH OTHER PROGRAMS below for more details. Once wIconify is installed, there are a number of utilitiy programs that may be useful in your startup sequence. For example, you may want to have a new wIconify screen opened as your Amiga boots up, and use this screen as an additional Workbench screen on which you open utility programs that you use often, or you may want to start some programs and have their windows be iconified during the boot process. Both these functions can be performed by the wIconify utility programs. These include: wIconScreen Opens a new wIconify screen wIconifyWindow Iconifies a window (and allows you to specify the icon's position and icon flags) wIconifyScreen Iconifies a screen (and allows you to specify the icon's position and icon flags) wMakeWB Selects a screen as the current WB screen wOpenOn Sets the OPEN WINDOWS submenu selections ScreenToFront Depth arrange screens ScreenToBack Each of these is documented sepearately; see these documents for complete details on how to use these programs. If you plan to open extra Workbench screens where you will open many utilitiy programs during boot-up, you may want to consider changing the default OPEN_WINDOW setting to CURRENT_WB; then, create the screen using the wIconScreen command (the screen will not be activated, but will be the current WB screen, so new windows will open there); then open the utilities you want; finally, use wOpenOn to change the OPEN_WINDOWS menu back to ACTIVE_SCREEN. For example: wOpenOn CURRENT_WB wIconScreen HIRES NOACTIVATE BEHIND ; commands that open windows here wOpenOn ACTIVE_SCREEN Once windows are open, you can use wIconifyWindow to iconify them during the startup sequence, so your work area can be nice and clean as soon as your machine boots up. (You can also use the AUTOICONIFY flag within wIconSetter to cause windows to iconify as soon as they open, but this will stay in effect even after boot-up, so windows may iconify themselves when you hadn't intended them to). INTERACTION WITH OTHER PROGRAMS: LoadWB The Workbench opens a backdrop window to hold its disk and file icons. Since this window is the full size of the screen, it covers up the wIconify backdrop window making it hard to get to the window icons. For this reason, wIconify modifies the Workbench window when it opens so that it is a standard non-backdrop window with drag bar, depth gadgets and sizing gadget. In order for this to happen, however, you must install wIconify BEFORE you start the Workbench with LoadWB. See HOW WICONIFY WORKS above for more information. DropCloth DropCloth allows you to add a background picture or shading pattern to your Workbench window. DropCloth is not very picky about the window it modifies, however. In particular, it seems to take the back-most backdrop window. If wIconify is running, this will be the wIconify window (this is probably what you want since the Workbench window is no longer a backdrop window). On the other hand, if you have iconified windows, they will be turned into backdrop windows that are behind the wIconify backdrop, so in this case, DropCloth will add its picture or shading to the last iconified window (if any). Thus you can have DropCloth do its magic to ANY window simply by iconifying it just before running DropCloth. If you want to remove DropCloth from such a window, be sure to iconify it again first. Less Less is a program like More, with additional features. It does not behave very well, however (it does not respond to sizing its window, for example). This program attempts to open a large window to see if the screen is interlaced, and if the OpenWindow() call fails, it opens a smaller window for non-interlaced screens. If you have set the SIZE TO FIT option in the OPEN WINDOW submenu, however, wIconify will modify the initial window size to fit the screen, and Less will think the screen is interlaced. It will miscalculate the size of the window and hence the number of lines that can fit in the window. For programs like this, you should disable the SIZE TO FIT option. QMouse QMouse is a small utilitity that incorporates a mouse accellerator, a menu clock, click-to-front, and a hole lot of other useful features, all in one small package. Unfortunately, it seems that, in order to make it as small as possible, QMouse does not always do everything "legally". In particular, it does not seem to allocate the timer device correctly (it does not even contain the name of the timer device in its executable). For this reason, if you use QMouse, wIconClock will not be able to get access to the timer (in fact, its attempt to allocate the timer never seems to complete). If you install wIconClock BEFORE you start QMouse, however, everything seems to work OK. It may not be completely bugless, however. Screen and window hot-key programs These are programs that allow you to depth-arrange screens and windows via hot-keys. Since wIconify does not actually remove windows when they are iconified (it only hides them), such programs may try to depth-arrange iconified windows. wIconify tries very hard to prevent this, but the result is that your hot-key program may not do exactly what you think it should, due to the presence of unexpected backdrop windows. Similary, screens are not removed, just hidden, and their presence may confuse hot-key screen flippers as well. wIconify is designed to favor programs that allow you to move the front screen to the back, but will probably disrupt programs that allow you to bring the back screen forward: wIconify pushes iconified screens to the back, so if they are moved to the front, wIconify will just send them to the back again. You will never even see the screen come forward (since it is iconified), and the result will be that your screen-flipper appears to do nothing at all. Programs that write directly to the screen's RastPort The intuition guide suggests that programs always use a backdrop window for graphics rendering rather than go directly to the screen's RastPort. Unfortunately, some programs break this rule. You may wish to have wIconify not open its backdrop window on such screens. To do so, use the initialization file and the IGNORE_SCREEN command to specify the screens to be ignored. Programs that use Sprites: Some programs use the hardware sprites, which always appear above anything else on the screen (the mouse pointer is a sprite). When these windows are iconified, the sprites will still appear in front of everything, which may be a bit confusing if they are supposed to look like part of the window. Also, if you open new "foreign" windows on a screen that is using sprites, the sprites may appear on top of the new windows. This may be confusing if they are supposed to look like part of another window. WHEN WICONIFY CAN FAIL: In addition to the interactions described in the section above, there are some additional situations that can cause confusing results: A Window's Icon Appears but the Window Does Not Disappear: This can happen when you are attempting to iconify a SMART_REFRESH window when there is very little CHIP memory left. Low memory conditions are very touchy, and you should try to free up some memory right away, chances are the system is about to crash due to a lack of memory. If it survives, you should open the window's icon (even though the window is still visible). This is because wIconify has modified the window and attempted to send it to the back, but Intution did not have enough memory to save the window's contents off-screen. There is no way for wIconify to know this, however, since WindowToBack() does not return a success status. Once you have freed up some memory, try iconifying the window again. A Window's Icon Disappers but the Window Does Not Reappear: As with the problem above, this can be caused by very low CHIP memory conditions. What has happened in this case is that wIconify has attempted to bring the window to the front, but there is not enough memory for Intuition to save the parts of the windows that will become obscured. wIconify has no way to determine this, however, so it removes the window's icon, thinking that the window has appeared. At this point, the window is inaccessible as it is still behind the wIcoinfy backdrop window. There is a utility program called wIconVerify that will find any "lost windows" of this type. See the documentation for wIconVerify for more details. Selecting the END Menu Item Doesn't Seem to End wIconify: Ending wIconify is a more complex operation than you might at first think (see ENDING WICONIFY above for complete details). There are a number of reasons wIconify can fail to end when you ask it to: The RUN command may not be in the C: directory, or the C: directory is on an unmounted disk (AmigaDOS goes directly to C:, bypassing the path, so wIconify must have access to C: in order for END to work). The WICONIFY: directory has not been assigned via the ASSIGN command (see INSTALLING AND REMOVING WICONIFY above for details). There are screens with non-window icons on them that can not be removed automatically (this can only be true if you are using programs that take advantage of wIconify's programmer's interface). There are windows open on shared screens other than the workbench. There are wIconify screens open with windows on them. There are un-replied messages held by programs using the programmer's interface, or due to attempts to close windows associated with icons. Can't Create a NewCLI: In order to create a new CLI, wIconify must have access to the RUN command in the C: directory (being in the command path is not good enough). It must also have access to the NEWSHELL command, or whatever command you specified in the initialization file. The NewCLI also may fail if the syntax of the command you specified is incorrect, the command can't be found, or if the files required by it can not be found, or if the command you specified fails in any way. Note that the current directory and command path are NOT preserved when starting new CLIs, so you may need to do a CD or PATH command as part of the command executed (see NEWCLI'S CREATED BY WICONIFY above for more details). CLI has Trouble Finding Commands: This is probably due to the fact that the new CLI does not inherit the current directory or command path. You can either specify complete path names for the commands and files in the new CLI command, or you can create a file containing CD, PATH and any other commands you want performed, and have the New CLI command as EXECUTE this file. See NEWCLIS'S CREATED BY WICONIFY above for more detail. wIconify Crashes with Some Programs: wIconify has very complex interactions with Intuition and the system as a whole. Some programs may make assumptions about the system setup or their screens that are no longer valid when wIconify is running. It is even possible that such programs will crash if wIconify is running. If so, you may want to use the initialization file and the IGNORE_SCREEN command to prevent wIconify from modifying the screens used by such programs. A Program Thinks its Window is Larger than it Really Is: If the SIZE_TO_FIT item is checked in the OPEN_WINDOWS submenu, then wIconify will resize windows when they open so that they fit onto the screen where they open. wIconify sends such programs a NEWSIZE IntuiMessage, but not all programs are well-behaved in processing this change of size. If you have such a program, you may need to disable the SIZE_TO_FIT menu in order to get it to work correctly with wIconify. FUTURE ENHANCEMENTS: The author feels that wIconify is pretty much complete at this point, and that there is not too much more to be done with it. If you have bugs or suggestions to make, however, he would be more than happy to hear about them. AUTHOR: wIconify and its compaion utilities Copyright (c) 1990,1991 by Davide P. Cervone, all rights reserved. They were developed on 512K Amiga 1000 using Lattice C v4.0 and will undoubtedly need some re-writting to work with Manx Aztec C. Davide P. Cervone Department of Mathematics Brown University Providence, Rhode Island 02912 ST402523@BROWNVM st402523@brownvm.brown.edu