QuickTone Prototyper for Windows - Product Documentation Shareware Version 1.0S - 2/1/92 release Registered Version 1.0 - 2/10/92 release INTRODUCTION ------------ QuickTone Prototyper is a programming utility designed to quickly and easily prepare PC speaker sound effects for applications written for the Microsoft Windows operating environment (versions 3.0 and above). The utility was designed to provide a stand-alone sound effects facility in which multiple tone strings (queues) can be written and tested outside of the source code and compiler environment. This frees the programmer from having to rewrite and recompile source code over and over again in the process of "fine tuning" a given sound effect. QuickTone generates Windows API functions exclusively, making its output completely compatible with any Windows applications development language that makes calls to the Windows API. Up to eight different voice queues -- comprised of up to eight notes each -- may be edited and tested within QuickTone. In addition, separate queues of notes may be saved as text files for later insertion into your program source code or automatically copied to the Windows Clipboard for quick pasting into your source code via any Windows-based text editor. The program interface itself illustrates the benefits of such sound effects, with aural feedback linked to button and scroll bar operations -- demonstrating the textured "fit and finish" that such feedback can give a program. Because calls to the Windows API sound and voice functions are universal across all popular Windows programming languages, QuickTone can be used in conjunction with virtually any Windows applications development language that makes use of Windows API functions, including but not limited to: Borland C++ Borland Turbo Pascal for Windows Microsoft Quick C for Windows Microsoft SDK PROGRAM FILES ------- ----- The QuickTone Prototyper package consists of three files: QTONE.EXE The executable program file. QTONE.EXE (2/1/92) is the Shareware "S" version. QTONE.EXE (2/10/92) is the Registered version. QTONE.HLP The Windows Help file, used for providing comprehensive run-time help. QTONE.TXT This file, containing program information, notes, and general instructions. PROGRAM NOTES ------- ----- QuickTone runs within the Microsoft Windows environment (versions 3.0 or higher), and requires the following: * EGA or VGA graphics capability. * A Windows-compatible mouse or other pointing device. QuickTone runs in 16-color mode, but will run acceptably on monochrome or black & white EGA or VGA systems (VGA graphics are recommended). The program will run in any Windows 3.0+ operating mode. QUICKTONE PROTOTYPER SETUP --------- ---------- ----- QuickTone requires no configuration or setup. Although it can be run from a floppy disk, we strongly recommend installation to a hard disk. INSTALLATION GUIDELINES ------------ ---------- 1. We recommend making a backup copy of your program disk. Keep the master copy in a safe place and use the backup disk for program installation. 2. Copy the program files (QTONE.EXE and QTONE.HLP) from your master disk to an appropriate subdirectory on your hard disk (e.g., C:\SOUND). There are no hidden files or "key" files on the program disk, so the file copying process can be accomplished with the DOS "COPY" command or, if you prefer, through the Windows File Manager File/Copy command. This file, QTONE.TXT, is not required in order to run QuickTone. The two program files (QTONE.EXE and QTONE.HLP), however, are required, and must reside in the same directory in order for the program to work properly. 3. You may use the "Windows Setup" utility to setup a program item (icon) for QuickTone. Windows Setup will recognize the QTONE.EXE file and assign its icon to a program group for you. or... You may assign a program item icon to QuickTone manually, through the File/New commands in Program Manager. Always make sure that the correct path and filename (e.g., "C:\SOUND\QTONE.EXE") is assigned to the QTONE program item. The "Browse" control in the Program Item dialog box will make it easy to locate and assign the correct path and filename. 4. If installed correctly, the program should load from the Program Manager screen when the QTONE icon is double-clicked (or from File Manager when the QuickTone listing is selected with "File/Run" or double-clicked with the mouse pointer). USING QUICKTONE PROTOTYPER ----- --------- ---------- QuickTone Prototyper for Windows was designed to be a time- saving utility for programmers wishing to make use of simple sound effects in their Windows applications. QuickTone is limited to generating Windows API functions and their related parameters. As a result, the modules it produces can be inserted into source code text and compiled by virtually any major Windows programming language that makes calls to the Windows API. Little, if any, modification of the "queue modules" should ever be required. Best of all, QuickTone allows you to write a selected queue module to a text file, or copy it directly to the Windows clipboard, making it easy to paste into your program source code. Help and examples are available at any time through the QuickTone menu bar "Help/Contents..." command. You can directly access any Help topic through the Contents menu, or browse from topic to topic. Help topics may be printed through the Windows Help menu bar "File/Print Topic" command. GETTING STARTED ------- ------- The QuickTone program window is divided into four main areas. The Note Select area is used for selecting a specific note in an active voice queue. A maximum of eight possible notes may be placed into any single voice queue, but only one note at a time may be edited. The controls in this area allow a selected note to be test-played or erased at any time. The Queue Control area contains two status fields for displaying the active voice queue and the number of notes it contains. A scroll bar is provided for manually setting the number of active notes in a given queue. In addition, three command buttons are provided, allowing the user to display the active queue in a dialog box window, save the active queue to the Windows clipboard, or write the active queue to an ASCII text file. The Queue Select area is similar to the Note Select area. It is used for selecting a specific voice queue for editing. A total of eight voice queues are available to QuickTone. The controls in this area allow a given queue to be test-played in its entirety or cleared from memory at any time. A third control button allows the user to erase the contents of all eight voice queues at once. The Active Note Settings area is used for adjusting the particular sound settings of the currently active note. Three scroll bars are provided for this purpose. In addition, two status windows are used to display the selected note and its SetVoiceNote parameters during the editing process. USING QUICKTONE ----- --------- QuickTone Prototyper pre-selects voice queue number 1 when the program is loaded. At that time, all queues are considered empty and each note is considered vacant. To select a note or notes to edit, simply "click" one of the numbered buttons in the "Note Select" section. The "Notes in Queue" scroll bar and status window will be automatically updated to reflect the number of active notes in the current queue. The scroll bar controls the number of active notes assigned to the current voice queue. NOTE: The Note Select control buttons will override the Notes in Queue controls if the note selected for editing is greater than the current Notes in Queue (total notes) setting. When a note is selected, the actual editing is done in the "Active Note Settings" area at the bottom of the interface screen. Here, each of the three adjustable SetVoiceNote parameters may be set. As each value is adjusted, the SVN function displayed in the status window is updated to reflect the current function parameters. Specific information on the effect of each of the three Active Note Settings controls is provided in the "SetVoiceNote Function Explained" section. The active note may be test-played at any time by clicking the "Play Active Note" button. The entire active queue may be played at any time by clicking the "Play Active Queue" button. In addition, all voice queues containing any active notes can be played in sequence (1-8) by clicking the "Play All Queues" button. NOTE: Voice queue notes with a "Note Value" of zero (0) will be "played" as rest notes or pauses. To clear the active note, simply click the "Clear Active Note" button. This resets the note's SetVoiceNote parameters to the default "vacant" values. To clear ALL notes in the active voice queue, click the "Clear All Notes" button, or by manually sliding the "Notes in Queue" scroll bar to its zero position. SETVOICENOTE FUNCTION EXPLAINED ------------ -------- --------- The QuickTone Prototyper constructs PC speaker tone source code via the Windows API "SetVoiceNote" function. SetVoiceNote parameters set not only the tone note itself, but the duration of the tone and the "blank" (rest) just before and after the tone. Syntax ------ SetVoiceNote(Voice, Value, Length, CDots); Parameters ---------- Voice A specified voice queue. For our purposes, this value is preset to 1. Value An integer note value. When this value is set to zero, a rest ("blank") note is played. A value in the range 1-84 will produce a tone; generally higher in pitch as the value setting is increased. Length An integer value reciprocal of note length duration. This value exercises primary control over the duration of the played note; generally shorter as the length setting is increased. Length settings below 12 will allow a note duration of a full second or more. CDots An integer value of note duration in CDots. This value exercises secondary control of the duration of the played note, and may be used in conjunction with the "Length" setting to alter the rest period just before or after the note iself is played. For most purposes, however, this setting may be left at 1, with the "Length" value controlling note duration exclusively. ABOUT THE WINDOWS API SOUND FUNCTIONS ----- --- ------- --- ----- --------- The Windows API offers a number of functions that are used to produce tones and sound effects through the standard PC speaker. QuickTone employs a number of other functions in support of SetVoiceNote -- some to prepare the voice queue, some to control the manner in which the queue is played, and some to shut down the sound operation when the queue is empty. Example: OpenSound; SetVoiceNote(Voice, Value, Duration, CDots); StartSound; WaitSoundStates(S_QueueEmpty); StopSound; CloseSound; A brief description of each API function used in QuickTone operation is provided in the QuickTone Help file QTONE.HLP, which is accessible through the QuickTone menu bar "Help/Contents" command. FEATURES -------- NOTE SELECT FEATURES Play Active Note ---- ------ ---- This control button plays the active note. Clear Active Note ----- ------ ---- This control button clears the current note from memory and resets its SetVoiceNote parameters to the "vacant" default values. Clear All Notes ----- --- ----- This control button clears all notes in the active voice queue and resets their SetVoiceNote parameters to the "vacant" default values. QUEUE CONTROL / QUEUE DESTINATION FEATURES Display Queue ------- ----- This control button displays the entire active voice queue and its supporting API functions in a dialog box. Save to Clipboard ---- -- --------- This control button copies the entire active voice queue and its supporting API functions into the Windows clipboard for pasting into a Windows-compatible text or source code editor. Write to File ----- -- ---- This control button writes the entire active voice queue and its supporting API functions into an ASCII text file. Voice queue #1 is saved as QUEUE_01.TXT, queue #2 as QUEUE_02.TXT, and so on. QUEUE SELECT FEATURES Play Active Queue ---- ------ ----- This control button plays the active voice queue in its entirety. Blank or "vacant" notes are played as pauses. Play All Queues ---- --- ------ This control button plays all defined notes in all active voice queues. Blank or "vacant" notes are played as pauses. Queues are played in sequence, 1-8. Only queues containing active notes are played. Clear All Queues ----- --- ------ This control button clears all notes in all voice queues and resets their SetVoiceNote parameters to the "vacant" default values. ACTIVE NOTE SETTINGS FEATURES Note Value ---- ----- This scroll bar adjusts the active note's SetVoiceNote "Note" parameter. A value in the range 1-84 will produce a tone; generally higher in pitch as the note value setting is increased. A value of zero (0) produces a rest. Note Duration/Recip. ---- --------------- This scroll bar adjusts the active note's SetVoiceNote "Length" parameter, an integer value representing the reciprocal of note length duration. In QuickTone, this value exercises primary control over the duration of the played note; generally shorter as the length setting is increased. Length settings below 12 will allow a note duration of a full second or more. Note Duration/CDots ---- -------------- This scroll bar adjusts the active note's SetVoiceNote "CDots" parameter, an integer value representing note duration in CDots. In QuickTone, this value exercises secondary control of the duration of the played note, and may be used in conjunction with the "Length" setting to alter the rest period just before or after the note iself is played. For most purposes, however, this setting may be left at 1, with the "Length" value controlling note duration exclusively. MISC. FEATURES Help ---- Comprehensive run-time help is provided via the Windows Help system, through the menu bar "Help/Contents" command. You may select specific topics to read, or browse from topic to topic. You may even print topics for later reference. PRODUCT REGISTRATION ------- ------------ QuickTone Prototyper for Windows is shareware, not freeware. Product registration is necessary if companies like ours are to continue providing quality software for the shareware marketplace. Registered users receive the registered version of this product (available in 3.5" or 5.25" disk formats). Registration also entitles the user to advance information on upcoming Pegasus Development products (including upgrades to QuickTone) -- as well as other new titles in our expanding product line. The registration fee for this product is $16.00 (U.S.). Registrations are accepted both by telephone (with a major credit card) or by mail. For orders outside the continental U.S., please add $2.00 for shipping and handling. For your convenience, a registration form is provided here and within the QuickTone help file (accessible via the Windows Help system). The help file registration form, or any help topic, is easily printable through the Windows Help menu bar "File/Print Topic" command. We at Pegasus Development appreciate your support, and hope you enjoy using QuickTone 1.0. LIMITED WARRANTY AND REMEDIES ------- -------- --- -------- Before release, our applications software is tested on a wide variety of hardware configurations, under the most rigorous test conditions possible. We therefore warrant that the software will perform in substantial compliance with the specifications set forth in this text, provided that the software is used on the computer hardware and operating system(s) for which it was designed. Pegasus Development makes no other warranties, expressed or implied, with respect to this software or media, including its quality or fitness for a particular purpose. In no event will Pegasus Development be liable for any direct, indirect, special, incidental, or consequential damages arising from the use of or the inability to use this software, even if Pegasus Development has been advised of the possibility of such damages. Pegasus Development is not responsible for any costs including, but not limited to, those incurred as a result of lost profits or revenues, loss of time or use of the software, loss of data, the cost of recovering software or data, the cost of substitute software, claims by third parties, or similar costs. In no event will Pegasus Development's liability exceed the amount of the paid purchase fee. TRADEMARK ACKNOWLEDGMENTS --------- --------------- "Microsoft" and "Windows" are registered trademarks of Microsoft Corporation. "Borland", "Borland C++", and "Turbo Pascal for Windows" are registered trademarks of Borland International, Inc. Other brand and product names are trademarks or registered trademarks of their respective holders, and are hereby acknowledged. ---------------------------------------------------------------------------- SOFTWARE REGISTRATION FORM -------- ------------ ---- Return this form along with your remittance to: Pegasus Development QuickTone 1.0 Registration 11900 Grant Place Des Peres, MO. 63131 U.S.A. You can also register by telephone using your MasterCard or VISA through Advanced Support Group's Product Registration Hotline at 1-800-788-0787. ______ QuickTone Registrations @ $16.00 U.S. each For orders outside the continental U.S., please add $2.00 shipping and handling. Total enclosed . . . . . . . . . . . . . . $________ Payment by: [] Check [] MasterCard [] VISA Card# ____________________________ Exp. Date _______ Signature of Cardholder_____________________________ Name________________________________________________ Address ____________________________________________ City _______________________ State ____ Zip_________ Telephone (______)______________________ Disk Size Required: [] 3.5" (720K) [] 5.25" (360K) Please indicate where you obtained QuickTone 1.0: (Mail Order, BBS, etc) _____________________________ ____________________________________________________ ____________________________________________________