gemini - kennedy.gemi.dev

💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Utilities › UltraBlank.Docs.t… captured on 2024-02-05 at 11:46:09.

-=-=-=-=-=-=-

UltraBlank� Documentation � Version 2.08

This program is ShareWare. Go ahead and try it out, but if you want to continue using it, you need to pay me for it. For complete details, see the Standard Plea and Legal Absurdities sections at the end of this document.

This document uses the Shaston font, in 8 & 16 point, for readability on the screen. If you want to print this file out, you may change the font to a more legible printer font, but don�t distribute the changed file. If you have Pointless�, try Chicago at a convienient pair of sizes (such as 12/24).

Installation
To use this utility, just copy the file �UltraBlank� to the System.Setup subdirectory in the System directory on your boot disk(s), and reboot. You MUST use a program which can copy extended files, like the Finder or newer versions of the Orca shell, since UltraBlank is an extended file. You can tell if UltraBlank was installed correctly if an icon of a monitor with a bouncing ball on it appears on the bottom of your screen while the computer is booting.

Note: This program requires System 6.0.0 or later to function. If UltraBlank is installed on a boot disk with an older System version than this, UltraBlank will not be installed, and a message to this effect will be displayed on the boot screen.

Attention: This program will refuse to be installed by an init installer such as IR, because of the potential problems if this is done. UltraBlank also won�t work if copied to the FinderExtras folder. If you didn�t understand this paragraph, it�s not something you need to worry about. Just follow the directions on how to install UltraBlank.

By the way, to get the Finder to display UltraBlank�s own icon for the �UltraBlank� file (and also let the Finder correctly identify UltraBlank�s preference file), all you have to do is select the �UltraBlank� file and choose Icon Info (-I) from the Finder. The next time the Finder starts, the new icon will be shown. This only needs to be done once.

New Features Summary
� New types of �color� for the Bouncing Ball blanking type
� Requires System 6 (allowing smaller & cleaner code)
� Uses features of System 6.0.1, if present
� All known bugs removed
� Still uses only about 5.5k in use

Please read these docs, but if you�re in a hurry to see bouncing balls (& are new to UltraBlank 2.x), just copy UltraBlank to the System.Setup folder and reboot. If you�re updating from an older version, choose the �UltraBlank�� desk accessory and select �Bouncing Ball� under Type. Now press Control & Shift at the same time. That�s it! See the Configuring UltraBlank section for customization instructions.

Synopsis & Description
This program will blank the screen after a period of time where no keyboard, mouse, or joystick fire-button activity takes place. This length of time may be selected from any GS/OS program as described below in the Configuring UltraBlank section. UltraBlank can blank the screen while any GS/OS or ProDOS 8 program is running (as long as GS/OS was originally booted). The blanking will take place while the computer is in ANY video mode which is available on the GS (super hi-res, text, hi-res, etc.). The only requirement is that the program allow interrupts. See the Usage section below for an easy way to check for this. While the computer is blanked, the currently running program will still continue to run.

Configuring UltraBlank
The following conventions will be used in this section: Individual options will be shown in italics, and individual selections for an option will be shown in bold. The actual menu option you choose to configure UltraBlank will be shown in �quotes�.

UltraBlank allows you to change the way the menu options to configure UltraBlank appear to you in the new and classic desk accessories menus. They will initially read �UltraBlank��, but you can change this to �Configure UltraBlank�� or �UltraBlank� Configure� as well. In any case, the menu options are described as �UltraBlank�� in the following paragraphs, for clarity.

NOTE: When using either version of the UltraBlank desk accessory, if the disk you booted is not in a drive when you choose it, then the computer may ask you to insert the boot disk. Just follow the directions on the screen if that happens. Also, UltraBlank saves your settings on the boot disk when you close the graphical �UltraBlank�� window or press Return in the text version, so that it will know what they are after you reboot. The same prompt to insert the boot disk will appear if the disk is not in a drive at that time (except that you are allowed to cancel from this one). If the boot disk is write protected when the program tries to save, or you cancel from the insert disk dialog, nothing bad will happen, but the settings will revert to what they were before the next time you reboot the computer.

There are two ways to configure UltraBlank. If you are currently using a program which supports New Desk Accessories, such as the Finder or ShrinkItGS, just pull down the Apple menu and select �UltraBlank��. Otherwise, go to the Classic Desk Accessories menu (by pressing Control-Apple-Esc) and select �UltraBlank� from that menu. However, GS/OS must be running to configure UltraBlank. When you are using a ProDOS 8 application, you will be told that GS/OS is needed.

When you�re done using the CDA version of �UltraBlank�, you can press Return to save your changes, or press Escape if you change your mind. In the NDA version, clicking in the close box will save your changes. You can hold down the Option or Control key while closing the window if you change your mind and don�t want to save your changes; however, any changes you have make will stay in effect until you reboot or shut down.

Using either version of the �UltraBlank� desk accessory, you may select the Delay option, which allows you to choose how long UltraBlank will wait before blanking the screen. In addition, you can use the Type option to select the type of blanking that UltraBlank uses. You can choose between Black Screen, which turns the entire screen and border to black, Bouncing Ball, which keeps the screen black except for a bouncing ball, or Blanking Off, which will completely turn off blanking. There are some options which modify how and when the bouncing ball will appear when bouncing ball is the chosen blanking type. They are described below in the description of the Advanced Options... button.

There is one more option available in the CDA version of �UltraBlank�. This option, Use Ball (Non-SHR), is described later in this section. The graphical (NDA) version of �UltraBlank�� has several more available options. You can press the About button to read about the program, and press the Help button to read a short description of the non-advanced options.

In addition, you can press the Advanced Options... button to show another window with several more options, which will be described in the remainder of this section.

The first three advanced options pertain to the Bouncing Ball blanking type. The Color option lets you select what color the bouncing ball will be. You may choose from several possible colors, most of which you�ve probably seen before. The most unusual colors are the five Psychedelic colors. The Psychedelic color choices continuously do the following: Starting with bright blue, the blue starts fading, while at the same time green appears and gets brighter. This goes on until the blue is completely gone and the green is at full brightness. The green then fades to red, then goes back to blue, where the process repeats. Trust me, this looks a lot neater than this description makes it sound, so try it out! The Dreamy, Slow, Normal, Fast, and Warp options refer to how quickly the colors change.

The Use Ball (Non-SHR) option lets you choose when and whether you will see a bouncing ball when the computer is displaying something other than super hi-res (text, for example). Never means that you will only see a bouncing ball when the screen in in super hi-res mode. The Only GS Programs option will cause UltraBlank to show a bouncing ball in any video mode, unless a ProDOS 8 program is currently running. When Possible means that UltraBlank will always try to display a bouncing ball. Keep in mind, however, that it may not always be possible to display a bouncing ball, in which case the screen will just go blank. See the Problems & TechStuff section for more specific details. In any event, a bouncing ball will always be used when the screen is currently in super hi-res mode (assuming, of course, that Bouncing Ball is the chosen blanking type).

The Sound Effects option controls what you will hear when the ball bounces off of the edges of the screen. You can have None, which does nothing, Blink Border, which (quietly) flashes the border, or Click, which clicks the internal speaker.

The last three options will only take effect after the system is restarted. The Boot Animation option lets you choose how fast the boot icon on the splash screen will be animated. You can also choose None to have no boot animation.

The Title option allows you to choose the text UltraBlank uses for the Desk Accessory menus. You may choose from the following: UltraBlank�, UltraBlank� Configure, and Configure UltraBlank�. The Style option allows you to choose what style the menu option has in the NDA menu. You can choose to have none, or any combination of underscore, italics, and bold. For example, if you choose UltraBlank� Configure and italic for Title and Style, then you will see the option �UltraBlank� Configure� in the Apple menu.

If you press OK, the settings you�ve chosen on the advanced options window will go into effect (but won�t be saved until you close the UltraBlank� window). Pressing Cancel will abort any changes you�ve made.

Usage
You shouldn�t have to change the way you use any of your programs, since any keyboard, mouse, or joystick fire-button activity you make will keep UltraBlank from blanking the screen. Only after the computer sits without any user activity for the amount of time you�ve chosen will the screen be �blanked�. Any activity AT ALL will bring the screen back. NOTE: this keypress or mouse movement will be passed on to the currently running program. So, if you don�t want to have a keypress popping up in your applications, then I suggest you either bump the mouse, or press a key like Shift or Control by itself, which will bring the screen back without any other effect.

If you want to quickly blank the screen whenever you want, you can do so by holding down only the Shift and Control keys at the same time until the screen goes blank, then letting up on both keys. This, by the way, is a good way to see if the currently running program allows interrupts, since the screen won�t go blank unless it does. By the way: You won�t be able to manually blank the screen if you�ve turned off blanking.

Problems & TechStuff
The only application that I know of which definitely doesn�t work with UltraBlank is AppleWorks 2.0 with Alan Bird�s Autoworks installed. I have also received a report that it doesn�t work with the game Zany Golf. Current versions of ProSEL 16 continuously set the border color while you�re using it, so the border won�t go black when the screen is blanked. As far as I know, this is the only problem with ProSEL, though.

There are a few things that you should keep in mind when using this program. First, you MUST disable any screen blanking features of other programs you wish to use, including any other screen blanking programs you�ve loaded as Desk Accessories, Inits, or CDevs. Failure to do so can result in the screen not being able to come back after more than one program blanks the screen!

If, while the screen is blanked, a program changes some colors or SCBs on the super hi-res screen, or changes to or from SHR without using QuickDraw II, then the screen may become at least partially visible. UltraBlank is smart enough not to mess up the screen trying to restore it to the previous state, but doesn�t detect these changes after it�s already blanked the screen.

If a program switches to/from SHR �normally� (i.e. using QuickDraw II) then the screen will be restored to it�s previous state, so that QuickDraw II can switch modes cleanly. An example of when this may occur is if a GS program quits while the screen is blanked. After this happens, the countdown to blanking the screen is restarted, as if you had pressed a key or something.

Under System 6.0.1, the screen will be restored whenever the system requests it (by using the systemSaysForceUndim request). In general, this happens whenever the system thinks something �important� happened. Many of these events are listed in the Sound CP.

If the current program makes changes to the SHR screen while the bouncing ball is being displayed, then �glitches� may appear after the screen is restored. These will usually be small black spots, but may also appear to be small parts of the screen that weren�t updated. These are nothing to worry about, and will go away the next time that portion of the screen is updated.

The method that UltraBlank uses to decide whether to attempt to display a bouncing ball when the screen isn�t in SHR is as follows: For Only GS Programs, it determines whether the current OS is GS/OS. If so, it then determines whether the memory where the SHR screen resides is in use. If not, the memory is (temporarily) allocated and it then proceeds to display the bouncing ball. If so, it determines whether the QuickDraw II toolset is active. If it is, it then displays the bouncing ball. If not, then the plain black screen is used. For the When Possible option, if the current O/S is ProDOS 8, then the bouncing ball is always displayed, under the assumption that a P8 program either won�t be using that memory, or it will be used for display purposes. Since it is allocated to the OS when ProDOS 8 is started, it won�t be allocated by the Memory Manager. I haven�t discovered any programs which have a problem with this, so I have made it the default. If you find such a program, please let me know, so I can see about working around it.

The accuracy of the blanking intervals given is based on the assumption that interrupts are allowed to take place the majority of the time the computer is running. Any time interrupts are disabled, the internal countdown to blanking the screen is temporarily halted. If you have chosen the �Bouncing Ball� blanking type and the ball is currently bouncing, the ball will also stop moving every time interrupts are disabled. Normally, the system doesn�t do this for extended periods of time, so this slowdown won�t be noticable. Also, blanking will not occur at all if and while interrupts are completely disabled by the current program.

I have received reports that some misbehaving programs are disconnecting UltraBlank. If the screen won�t blank, and you believe UltraBlank has been disconnected, you can reconnect it by choosing �UltraBlank� from the Classic Desk Accessories menu (even while using ProDOS 8). You don�t need to make any changes; UltraBlank is reconnected as soon as you choose the option from the menu. I also reconnect UltraBlank whenever you enter or leave any GS application that supports New Desk Accessories.

The only other problem I�m aware of is that UltraBlank is disconnected if you press Control-Reset. GS/OS applications usually reboot the system, so this isn�t a problem, but some ProDOS 8 programs allow Reset to be non-fatal, such as most AppleSoft BASIC programs. In this case, I recommend that you exit the application you�re currently using and shut down (or reboot), since there may be problems with other GS/OS applications. If you do want to reconnect UltraBlank, the method described above will work.

Even though this program takes about 20k on disk, the memory used while the program is in operation is only around 4.5k for the program itself, and including the overhead of tool patches of 1-1.1k, the total memory usage is around 5.5k. The remaining space is in modules which are only used when either UltraBlank desk accessory is active, as well as information used while booting, which is not kept in memory.

This program places a �hidden� file in the System:System.Setup folder of your boot disk named �UltraBlankCnfg� with a filetype of $5A (Preferences File) which holds the current settings for UltraBlank. If you want to return UltraBlank to it�s �factory default� settings, you just need to delete this file.

UltraBlank attempts to display an icon of a monitor (with a bouncing ball in it, of course :) while it�s being installed. If there�s a problem accessing it�s resources, or the system version is too low (less than System 6.x), then it will display a small �splash-screen� above the box which says �Welcome to the IIgs�. If UltraBlank encounters some other problem while loading, then the icon will have a red �X� through it, to indicate that it wasn�t loaded.

Standard Plea
This program is ShareWare, so if you find yourself using it, please help me out by paying something for it, so I can justify spending the time to update this and write other nifty pieces of software. People who send me at least $15 (U.S.) per computer, along with their vital information (Name, Address, # of computers, America Online screen name [if applicable], any other Internet-accessable names, etc.), and refer to �UltraBlank Version 2.08� will be assigned a registration number and will be entitled to receive one US-mailed update of this program at no charge. Normally, I will only mail major updates to people. I will send any minor versions to registered users on America Online or over the Internet, if I have an e-mail name to send to.

Registered users of previous versions of UltraBlank need not pay any more for this version (but, of course, may if they want to).

Please send bug reports, suggestions for enhancements, and your money to:
Robert S. Claney
2370-E Shady Oaks Rd
Marshalltown, IA 50158-9575

I can also be reached at the following locations:
America Online: BobClaney
Internet: bobclaney@aol.com
claney@iastate.edu
txa84@isuvax.iastate.edu

I�m more likely to help you out with any problems if you�re a registered user, but let me know what problems you have in any case, so I can strive to make this program as good as it can be.

Non-registered users are granted a limited license to try out this software to see whether it is useful to them. Continued usage requires registering this software by following the instructions in the Standard Plea section. In any case, this software may only be used for non-commercial purposes on a single machine only, unless specifically authorized in writing by me. Site licenses are available at a reduced price for multiple machines at a single location. Rates are also available for individuals wanting to use UltraBlank� on more than one computer. Contact me by (e-)mail for more information.

The accompanying software may be distributed as long as the following conditions are met: [1] This documentation (UltraBlank.Docs) and the history file (UltraBlank.Hist) must accompany the program (UltraBlank). [2] Neither the documentation, the history, or the program is modified in any way, other than compression by ShrinkIt� or some other widely available Apple� compression program. (This includes modifying the resources.) [3] No charge is made for it, other than minimal copying and media charges, or normal network charges, if online. [4] It is not incorporated into or with any other software, without my written permission.

Except in this section, marks identifying trademarks (�,�) are generally not used, in the intrests of readability.

This document was prepared by ShadowWrite 1.3.3. (Including the invisible text :)
Thank you, Andr�! Sorry, I haven�t snail-mailed the �Thank you� to you; I hope this suffices.

UltraBlank� is a trademark of Robert S. Claney.

Apple�, ProDOS�, and Apple IIGS� are registered trademarks, and GS/OS�, Finder�, QuickDraw�, and ADB� are trademarks, of Apple Computer, Inc.

GNO/ME� is a trademark of Procyon Enterprises Inc.

Orca� is a trademark of The Byte Works, Inc.

Pointless� is a trademark of WestCode Software.

ShrinkIt� is a trademark of Andrew E. Nicholas.

Any other names are trademarks or registered trademarks of their respective companies. So there. (Not so here (bad invisible joke (Why are you reading it? (Help, I�m trapped in a LITHP parser (bad () joke (and really bad LISP joke :))))))

If you're reading this, you're probably viewing it from the text screen. Naughty! Go at once to a graphical TeachText viewer to see these docs as they were written.