Twilight_II/text/quick.dox.txt

Twilight IIª Quick Documentation

By Jim Maricondo.  © 1992, 1993 DigiSoft Innovations, All Rights Reserved.
February 1993 Revision.

	Greetings!  Thank you for purchasing TwilightÊII for the Apple IIGS by DYA from DigiSoft Innovations.  As a customer, you're very important to us.  Feel free to contact us at any time with any questions or comments at the addresses listed at the end of this document.  This quick documentation should serve to get you going until the final documentation is completed real soon now.  You will be sent a copy of the end manual when it is finalized, along with a TwilightÊII update disk containing the latest (and probably final) versions of the program and modules.

	We do not believe in copy protection, and for that reason TwilightÊII is not copy protected.  This however is not an invitation to copy TwilightÊII for all your friends.  Please don't give abuse our policies by giving it to anyone else or uploading it everywhere you know Ð programmers have to eat too, and this product has taken up an incredible amount of the free time of all those involved.  Your cooperation is greatly appreciated.

	A module, or blanker, is a program that does a specific screen effect or animation when it is time to blank the screen.  Modules have filetype $BC, auxtype $4004, just for your information.  Full module format documentation (so that you may write your own modules!) is forthcoming.

	To install TwilightÊII, also known as T2, you must first have Apple's System 6.0 and Control Panel desk accessory.  Run the installer program on the TwilightÊII v1.0 program disk.  You have several installation options.  If you have enough room on your boot disk (i.e. if you are using a large capacity hard drive,) we recommend you install everything onto the boot partition.   If not, the TwilightÊII Control Panel and blanker modules can be installed wherever you want.  It should be noted, however, that if you do not install the T2 Control Panel in the ÒCDevsÓ directory on your boot disk, you will have to manually double-click on the TwilightÊII icon from the Finderª every time you boot (or select the T2 icon from the Control Panel New Desk Accessory at every boot.)  If you boot from a floppy, you probably will not have enough room to install everything on the floppy disk.  Also for installation are some TwilightÊII Finder icons that will be put in your Icons directory.  If you need to know the specifics of installation, there basically isn't much to it.  The T2 Control Panel must be in the same directory as a subdirectory named ÒTwilightÓ that contains the screen saver effect modules, or blankers.  That is the basic requirement.  You don't have to install any blankers, but if you don't install any, you will not be able to enjoy the astounding animation effects offered by T2.  Also, please note that the Clock module uses a default font included on the TwilightÊII disk that it defaults to when no other font has been setup for it to use.

	If for some reason TwilightÊII is installed on your boot disk in the CDevs folder, and you do not wish to have it enabled for a particular boot, hold down control during boot (while you see the ÒWelcome to the IIGSÓ screen) and TwilightÊII will not install itself.  This will be indicated by a red ÒXÓ drawn over the boot TwilightÊII icon.

	There are four types of corners in TwilightÊII:
Disabled Ð TwilightÊII does not behave any differently when the mouse is in the corner.
Don't Blank Ð TwilightÊII will not blank the screen ever when the mouse is in the corner.  This will usually be visually indicated by the cursor changing into a little crossed out T2 icon.
Foreground Blank Now Ð TwilightÊII will blank the screen using the currently selected module(s).  The program that was running will be halted and will not resume execution until it is time to unblank the screen.
Background Blank Now Ð TwilightÊII fades the screen to black, but then allows the program that was running to continue execution!  For instance, if I am copying files with the Finder and I go to a ÒBackground Blank NowÓ corner, the screen will fade to black and the copy will continue!  With ÒForeground Blank Now,Ó the copy operation will stop until the screen is restored.

	All the modules you currently have installed in the ÒTwilightÓ subdirectory will appear in a list when TwilightÊII is opened.  Italics are used to denote modules that are built into T2 and will always be available (Foreground Fader and Background Fader.)  Underlined type is used to indicate special modules; because ÒBackground FaderÓ does the functional equivalent of a ÒBackground Blank NowÓ corner, it is considered special.

	To temporarily toggle TwilightÊII off and on, hold down shift and press clear until you see the border change color.  Then immediately release clear and shift.  It might take you a few times to get used to it, for if you hold the keys down too long, you're liable to turn T2 off and then back on, or on and then back off.  TwilightÊII will flash the border a unique color when it is being turned on and a different color when it is being turned off.  These colors will vary depending on what your border color is normally set to.  (For instance, if your border color is black and you turn T2 off via shift-clear, the border will flash white.  Conversely, turning T2 back on, the border will flash deep blue.  Experiment a bit and see what your colors are!)

	TwilightÊII will also blank the text screen (used by programs like AppleWorks 3.0, ProTERM 3, etc.), and will do so in the background (i.e. allowing the program running to continue execution after the screen has been turned to black) and even in ProDOS 8!  So, for instance, you can be downloading a file with America Online or ProTERM 3, and in the middle of the file transfer the screen can blank and the transfer will continue with no problems.  Also, when using TwilightÊII with text based programs that use the mouse (and show a little cursor onscreen, again like America Online and ProTERM 3), if you move the mouse to a Don't Blank corner, the screen will never blank, and if you move the mouse to a ÒBackground Blank NowÓ corner, the screen will instantly turn to black and allow the program running to continue execution.	
	It should be noted however that there are some cases when TwilightÊII currently will not blank the graphics screen.  (Twilight II should always blank the text screen unless you turn text screen blanking off (see below.)  In order for TwilightÊII to blank the graphics (Super Hi-Resolution) screen using the module(s) you have selected, you must be in a desktop program that follows Apple's guidelines.  There also are cases with desktop programs when the screen will not blank while a dialog box is on screen.  In these cases, moving the mouse to a ÒForeground Blank NowÓ or ÒBackground Blank NowÓ corner will have no effect until after the window on screen is closed. Likewise, the screen will not blank on its own accord (i.e. the time you specified has elapsed) until the window is closed.

	When you open TwilightÊII, you will be presented with a window containing a list of the currently installed modules, three buttons, and one check box.  Use the check box to toggle ÒRandom ModeÓ on and off.  Random mode allows you to select a whole list of modules to use, blanking the screen with a different one each time.  Random mode requires that your boot volume be a hard drive or other nonremovable device.  In random mode, the list of modules allows you to select ranges of modules using shift and command while clicking.  The ÒBlank NowÓ control, used to preview the presently selected module, is dimmed and not available in random mode.  Likewise, the ÒAbout ModuleÓ control (which gives about information on the currently selected module) is also disabled when random mode is turned on, or if the setup window is open onscreen.  It is important to remember that everything you change in the main window will not be saved until you close TwilightÊII!  So if you select a new module, and then while T2 is still open, move the mouse to a ÒForeground Blank NowÓ corner, the screen will blank with your previously selected selection.  Your new selection(s) will not go into effect until you close the T2 window.

	TwilightÊII is very configurable and even supports multi-user AppleShare networks.  To setup T2, simply click the setup button.  Presently, setup is only available in 640-mode desktop programs (such as AppleWorks GS, the Finder, etc.)  Select the area or module you wish to setup from the popup control labelled ÒSetup.Ó  You can configure each of the four screen corners for a different purpose.  In addition, you can set the time in minutes before the screen will be blanked, and set a variety of other options as well.  After you have made changes to a screen of setup, you must click the ÒupdateÓ button or your changes will not be saved (very similar to modifying comments with ShrinkIt-GS)!  The following is a quick summary of the general TwilightÊII setup options available.  In parenthesis are keyboard equivalents, where available.

	Install TwilightÊII NDA (New Desk Accessory) (CommandÐI) Ñ When checked, T2 will always install a NDA in the Apple menu that, when selected, will open up T2 directly, bypassing the Control Panel NDA.  Note that the Control Panel NDA must still be installed.  This NDA has keyboard equivalents of Command-Control-T, Command-~, and Command-`.  These equivalents are only available if not already in use by the program currently running when an equivalent is pressed.
	Let Mouse Movement Restore Desktop (Command-L) Ñ When this control is not checked, the mouse will not be allowed to restore the desktop after the screen has blanked.
	Blinking Box in Menu Bar (Command B) Ñ When checked, T2 will flash a small rectangle in the upper right portion of the menu bar to alert you that it is active.
	Caps Lock ÒLockÓ (Command-C) Ñ When checked, the position of the caps lock key becomes important in that it ÔlocksÕ the current state of the screen when it is in the down position.  If the screen is currently unblanked and you turn caps lock on, the screen will never blank until caps lock key is returned to the up position.  If the screen is currently blanked and you press down the caps lock key, the screen will not unblank until the key is released.
	Warn if Preferences Not Saved (Command-P) Ñ TwilightÊII will alert you if you have changed some setup options and have not saved the changes via clicking the ÒUpdateÓ button.
	Text Screen Blank Ñ You can tell TwilightÊII to blank all programs that use the text screen (e.g. AppleWorks, ProTERM 3, America Online, etc.) in the background (i.e. allowing the program to continue to run after the screen has turned black), or only GS/OS based programs that use the text screen, or never to blank the text screen.
	DoubleClick Function Ñ You can adjust what double-clicking on a blanker in the list of blankers that appears when you open up T2 will do.  Double-clicks can either be ignored, set to Òblank nowÓ using the blanker double clicked upon, set to select the module and close T2, or set to setup the selected module.  Most, but not all, modules support setup.  If you double-click on a module that does not support setup, T2 will open the setup window with ÒScreen CornersÓ selected.
	Watch Cursor Ñ TwilightÊII can be set to behave differently when there currently is a watch cursor onscreen.  In most cases you will want to set this option to either ÒBackground Blank,Ó which makes the graphics screen black and allows the program to continue.  For instance, with this option set to ÒBackground Blank,Ó you can be copying files with the Finder, and if the time to blank elapses, the screen will be turned to black and the copy operation will continue.  When the cursor is a normal arrow (or anything other than the watch), a normal animated blank will occur with the module(s) you have previously selected.  You can also set the screen not to blank when a watch cursor is onscreen, or to do a ÒforegroundÓ blank using the module(s) you have selected, stopping the program that was running (so a file copy operation would stop while the animation was running, for instance.)

	Most of the modules are pretty self-explanatory for now, except for the YouDrawIt! module.  This is a vastly enhanced version of the YouDrawIt module in Twilight 1.0.  If you aren't familiar with YouDrawIt (YDI), it allows you to use any GS paint program to design graphics that will be animated when the module gets control.  Enclosed on the TwilightÊII disk are what we feel represent the best assortment of animations drawn by users of Twilight like yourself.  These are standard Apple Preferred Format (APF) pictures that can be loaded into virtually any GS paint program.   Installer scripts are provided to install these animation pictures, or you can copy them yourself to wherever you want if you feel more comfortable doing so.  The pathname of the animation file to use when it is time for YDI to blank the screen can be set in setup.  Feel free to load the YDI animation files included into a paint program and modify them, or create your own.  YDI uses what we term ÒAnimation Template Files,Ó or ATF's.  There are two types of ATF's: extended and normal.  Extended ATF's have a filename suffix of Ò.EATF,Ó and normal ATF's have a suffix of Ò.ATF.Ó  Blank versions of these template pictures can also be found on the TwilightÊII program disk under the names of ÒBlank.ATFÓ and ÒBlank.EATF.Ó  The only difference between the two formats is that EATF allows double the amount of animation frames as ATF.  To create your own animation, load up an ATF or EATF file into your paint program, draw your images in the boxes shown, and then fill in the box next to the number of frames in your file.  Again, for examples look at the pre-drawn ATF's included.  Your ATF/EATF files can be placed anywhere you choose, with one restriction: they must be located on a disk that will be available when it is time for YDI to blank the screen.  If YDI is called and it can't find the currently selected ATF, you will get an error message.  This won't hurt anything, but an error message is a lot more boring to watch.  To select an ATF file for YDI to use when it is time to blank, open up TwilightÊII, click Setup, select ÒYouDrawItÓ from the Setup popup menu, and click on the ÒSet Animation PathÓ button.  You will then be presented with a dialog box asking you to open the ATF file that YDI will use when it is called.  Remember you have to click ÒUpdateÓ for these changes to be saved!!

	If you are experiencing bizarre problems, like your selected modules not being saved, or the screen never blanking at all, you might want to try deleting the ÒTwilight.SetupÓ file that TwilightÊII creates in the ÒTwilightÓ modules subdirectory.  If you still are having any problems or have any questions, feel free to contact us at the addresses listed below.  Also, if you feel something is not accurately described here or left out entirely, also let us know.

	Lastly, a little background on us.  DYA, which stands for ÒDigital Youth Alliance,Ó was founded in January 1990 to promote the GS.  Currently, DYA consists of three members in college or soon to be: Jim Maricondo and Derek Young (programmers) and Matt Keller (graphic artist.)  We are die hard AppleÊII supporters and would love to hear from you.  Please support us so we can continue to support you.  Digital Creations was formed in 1992 to handle distribution and marketing of DYA products.  Coming soon: Exhibition, a fantastic GS/OS based 3200 color slideshow program based on the fades contained in ExhibitÊA, DYA's premier 3200 color picture slide show disk.

DigiSoft Innovations
P.O. Box 380 (55 Skyview Drive)
Trumbull, CT  06611
Attn: Twilight II Support
Phone (203) 375-0837
Or send electronic mail:
America Online: ÒDigiSoftÓ
Delphi: ÒDYAJIMÓ
GEnie: ÒJ.Maricondo1Ó
Internet: Òdigisoft@aol.comÓ or Òafcdyajim@aol.comÓ


In addition, we would like to sincerely thank the many individuals who contributed ideas, beta testing and debugging skills, and other time to this project.  Without the help of these people, TwilightÊII would not have been possible.  In particular, very special thanks to (in no particular order): Jim Murphy, Greg Templeman, Marc Wolfgram, Dave Lyons, Matt Deatherage, Seth Ober, Joe Wankerl, John Ponthier, Mark Ranes, Dino Bagdadi, Andy Polk, Jim Mensch, James Smith, Dan Zimmerman, Dan Wellman, Andy Warren, Eric Shepherd, and deep apologies to anyone we forgot!


DIGITAL CREATIONS' LICENSORS MAKE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE SOFTWARE.  DIGITAL CREATIONS' LICENSORS DO NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE.  THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU.  THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME JURISDICTIONS.  THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.

IN NO EVENT WILL DIGITAL CREATIONS' LICENSORS, AND THEIR DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS (COLLECTIVELY DIGITAL CREATIONS' LICENSORS) BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE EVEN IF DIGITAL CREATIONS' LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.  Digital Creations' Licensors' liability to you for actual damages from any cause whatsoever, and regardless of the form of the action (whether in contract, tort (including negligence), product liability or otherwise), will be limited to $50.