home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / QTONE.ZIP / QTONE.TXT < prev   
Encoding:
Text File  |  1992-02-01  |  18.5 KB  |  546 lines
  1. QuickTone Prototyper for Windows - Product Documentation
  2. Shareware Version 1.0S - 2/1/92 release
  3. Registered Version 1.0 - 2/10/92 release
  4.  
  5.  
  6. INTRODUCTION
  7. ------------
  8. QuickTone Prototyper is a programming utility designed to
  9. quickly and easily prepare PC speaker sound effects for
  10. applications written for the Microsoft Windows operating
  11. environment (versions 3.0 and above).
  12.  
  13. The utility was designed to provide a stand-alone sound
  14. effects facility in which multiple tone strings (queues) can
  15. be written and tested outside of the source code and compiler
  16. environment.  This frees the programmer from having to
  17. rewrite and recompile source code over and over again in the
  18. process of "fine tuning" a given sound effect.
  19.  
  20. QuickTone generates Windows API functions exclusively, making
  21. its output completely compatible with any Windows applications
  22. development language that makes calls to the Windows API.
  23.  
  24. Up to eight different voice queues -- comprised of up to
  25. eight notes each -- may be edited and tested within QuickTone.
  26. In addition, separate queues of notes may be saved as text
  27. files for later insertion into your program source code or
  28. automatically copied to the Windows Clipboard for quick
  29. pasting into your source code via any Windows-based text
  30. editor.
  31.  
  32. The program interface itself illustrates the benefits of
  33. such sound effects, with aural feedback linked to button and
  34. scroll bar operations -- demonstrating the textured "fit and
  35. finish" that such feedback can give a program.
  36.  
  37. Because calls to the Windows API sound and voice functions
  38. are universal across all popular Windows programming
  39. languages, QuickTone can be used in conjunction with virtually
  40. any Windows applications development language that makes use
  41. of Windows API functions, including but not limited to:
  42.  
  43.     Borland C++
  44.     Borland Turbo Pascal for Windows
  45.     Microsoft Quick C for Windows
  46.     Microsoft SDK
  47.  
  48.  
  49. PROGRAM FILES
  50. ------- -----
  51. The QuickTone Prototyper package consists of three files:
  52.  
  53. QTONE.EXE
  54.     The executable program file.
  55.     QTONE.EXE (2/1/92) is the Shareware "S" version.
  56.     QTONE.EXE (2/10/92) is the Registered version.
  57.  
  58. QTONE.HLP
  59.     The Windows Help file, used for providing
  60.     comprehensive run-time help.
  61.  
  62. QTONE.TXT
  63.     This file, containing program information, notes,
  64.     and general instructions.
  65.  
  66.  
  67. PROGRAM NOTES
  68. ------- -----
  69. QuickTone runs within the Microsoft Windows environment
  70. (versions 3.0 or higher), and requires the following:
  71.  
  72.     * EGA or VGA graphics capability.
  73.  
  74.     * A Windows-compatible mouse or other pointing
  75.       device.
  76.  
  77. QuickTone runs in 16-color mode, but will run acceptably on
  78. monochrome or black & white EGA or VGA systems (VGA graphics
  79. are recommended).  The program will run in any Windows 3.0+
  80. operating mode.
  81.  
  82.  
  83. QUICKTONE PROTOTYPER SETUP
  84. --------- ---------- -----
  85. QuickTone requires no configuration or setup.  Although it
  86. can be run from a floppy disk, we strongly recommend
  87. installation to a hard disk.
  88.  
  89.  
  90. INSTALLATION GUIDELINES
  91. ------------ ----------
  92. 1. We recommend making a backup copy of your program disk.
  93.    Keep the master copy in a safe place and use the backup
  94.    disk for program installation.
  95.  
  96. 2. Copy the program files (QTONE.EXE and QTONE.HLP)
  97.    from your master disk to an appropriate subdirectory on
  98.    your hard disk (e.g., C:\SOUND).
  99.  
  100.    There are no hidden files or "key" files on the program
  101.    disk, so the file copying process can be accomplished
  102.    with the DOS "COPY" command or, if you prefer, through
  103.    the Windows File Manager File/Copy command.
  104.  
  105.    This file, QTONE.TXT, is not required in order to run
  106.    QuickTone.  The two program files (QTONE.EXE and
  107.    QTONE.HLP), however, are required, and must reside in
  108.    the same directory in order for the program to work
  109.    properly.
  110.  
  111. 3. You may use the "Windows Setup" utility to setup a
  112.    program item (icon) for QuickTone.  Windows Setup will
  113.    recognize the QTONE.EXE file and assign its icon to a
  114.    program group for you.
  115.  
  116.    or...
  117.  
  118.    You may assign a program item icon to QuickTone manually,
  119.    through the File/New commands in Program Manager.
  120.  
  121.    Always make sure that the correct path and filename
  122.    (e.g., "C:\SOUND\QTONE.EXE") is assigned to the QTONE
  123.    program item.  The "Browse" control in the Program Item
  124.    dialog box will make it easy to locate and assign the
  125.    correct path and filename.
  126.  
  127. 4. If installed correctly, the program should load from
  128.    the Program Manager screen when the QTONE icon is
  129.    double-clicked (or from File Manager when the QuickTone
  130.    listing is selected with "File/Run" or double-clicked
  131.    with the mouse pointer).
  132.  
  133.  
  134. USING QUICKTONE PROTOTYPER
  135. ----- --------- ----------
  136. QuickTone Prototyper for Windows was designed to be a time-
  137. saving utility for programmers wishing to make use of simple
  138. sound effects in their Windows applications.
  139.  
  140. QuickTone is limited to generating Windows API functions and
  141. their related parameters.  As a result, the modules it
  142. produces can be inserted into source code text and compiled
  143. by virtually any major Windows programming language that
  144. makes calls to the Windows API.  Little, if any, modification
  145. of the "queue modules" should ever be required.
  146.  
  147. Best of all, QuickTone allows you to write a selected queue
  148. module to a text file, or copy it directly to the Windows
  149. clipboard, making it easy to paste into your program source
  150. code.
  151.  
  152. Help and examples are available at any time through the
  153. QuickTone menu bar "Help/Contents..." command.  You can
  154. directly access any Help topic through the Contents menu, or
  155. browse from topic to topic.
  156.  
  157. Help topics may be printed through the Windows Help menu bar
  158. "File/Print Topic" command.
  159.  
  160.  
  161. GETTING STARTED
  162. ------- -------
  163. The QuickTone program window is divided into four main areas.
  164.  
  165. The Note Select area is used for selecting a specific note in an
  166. active voice queue.  A maximum of eight possible notes may be
  167. placed into any single voice queue, but only one note at a time
  168. may be edited.  The controls in this area allow a selected note
  169. to be test-played or erased at any time.
  170.  
  171. The Queue Control area contains two status fields for displaying
  172. the active voice queue and the number of notes it contains.  A
  173. scroll bar is provided for manually setting the number of active
  174. notes in a given queue.  In addition, three command buttons are
  175. provided, allowing the user to display the active queue in a dialog
  176. box window, save the active queue to the Windows clipboard, or
  177. write the active queue to an ASCII text file.
  178.  
  179. The Queue Select area is similar to the Note Select area. It is
  180. used for selecting a specific voice queue for editing.  A total
  181. of eight voice queues are available to QuickTone.  The controls
  182. in this area allow a given queue to be test-played in its
  183. entirety or cleared from memory at any time.  A third control
  184. button allows the user to erase the contents of all eight voice
  185. queues at once.
  186.  
  187. The Active Note Settings area is used for adjusting the particular
  188. sound settings of the currently active note.  Three scroll bars
  189. are provided for this purpose.  In addition, two status windows
  190. are used to display the selected note and its SetVoiceNote
  191. parameters during the editing process.
  192.  
  193.  
  194. USING QUICKTONE
  195. ----- ---------
  196. QuickTone Prototyper pre-selects voice queue number 1 when the
  197. program is loaded.  At that time, all queues are considered
  198. empty and each note is considered vacant.
  199.  
  200. To select a note or notes to edit, simply "click" one of the
  201. numbered buttons in the "Note Select" section.  The "Notes in
  202. Queue" scroll bar and status window will be automatically
  203. updated to reflect the number of active notes in the current
  204. queue.
  205.  
  206. The scroll bar controls the number of active notes assigned to
  207. the current voice queue.
  208.  
  209. NOTE:  The Note Select control buttons will override the Notes
  210. in Queue controls if the note selected for editing is greater
  211. than the current Notes in Queue (total notes) setting.
  212.  
  213. When a note is selected, the actual editing is done in the
  214. "Active Note Settings" area at the bottom of the interface
  215. screen.  Here, each of the three adjustable SetVoiceNote
  216. parameters may be set.  As each value is adjusted, the SVN
  217. function displayed in the status window is updated to reflect
  218. the current function parameters.  Specific information on the
  219. effect of each of the three Active Note Settings controls is
  220. provided in the "SetVoiceNote Function Explained" section.
  221.  
  222. The active note may be test-played at any time by clicking the
  223. "Play Active Note" button.  The entire active queue may be
  224. played at any time by clicking the "Play Active Queue" button.
  225. In addition, all voice queues containing any active notes can
  226. be played in sequence (1-8) by clicking the "Play All Queues"
  227. button.
  228.  
  229. NOTE:  Voice queue notes with a "Note Value" of zero (0) will be
  230. "played" as rest notes or pauses.
  231.  
  232. To clear the active note, simply click the "Clear Active Note"
  233. button.  This resets the note's SetVoiceNote parameters to the
  234. default "vacant" values.
  235.  
  236. To clear ALL notes in the active voice queue, click the "Clear
  237. All Notes" button, or by manually sliding the "Notes in Queue"
  238. scroll bar to its zero position.
  239.  
  240.  
  241. SETVOICENOTE FUNCTION EXPLAINED
  242. ------------ -------- ---------
  243. The QuickTone Prototyper constructs PC speaker tone source
  244. code via the Windows API "SetVoiceNote" function.  SetVoiceNote
  245. parameters set not only the tone note itself, but the duration
  246. of the tone and the "blank" (rest) just before and after the
  247. tone.
  248.  
  249.     Syntax
  250.     ------
  251.     SetVoiceNote(Voice, Value, Length, CDots);
  252.  
  253.     Parameters
  254.     ----------
  255.     Voice
  256.     A specified voice queue.  For our purposes, this
  257.     value is preset to 1.
  258.  
  259.     Value
  260.     An integer note value.  When this value is set to zero,
  261.     a rest ("blank") note is played.  A value in the range
  262.     1-84 will produce a tone; generally higher in pitch as
  263.     the value setting is increased.
  264.  
  265.     Length
  266.     An integer value reciprocal of note length duration.
  267.     This value exercises primary control over the duration
  268.     of the played note; generally shorter as the length
  269.     setting is increased.  Length settings below 12 will
  270.     allow a note duration of a full second or more.
  271.  
  272.     CDots
  273.     An integer value of note duration in CDots.  This value
  274.     exercises secondary control of the duration of the
  275.     played note, and may be used in conjunction with the
  276.     "Length" setting to alter the rest period just before
  277.     or after the note iself is played.  For most purposes,
  278.     however, this setting may be left at 1, with the "Length"
  279.     value controlling note duration exclusively.
  280.  
  281.  
  282. ABOUT THE WINDOWS API SOUND FUNCTIONS
  283. ----- --- ------- --- ----- ---------
  284. The Windows API offers a number of functions that are used to
  285. produce tones and sound effects through the standard PC speaker.
  286.  
  287. QuickTone employs a number of other functions in support of
  288. SetVoiceNote -- some to prepare the voice queue, some to control
  289. the manner in which the queue is played, and some to shut down
  290. the sound operation when the queue is empty.
  291.  
  292. Example:
  293.     OpenSound;
  294.     SetVoiceNote(Voice, Value, Duration, CDots);
  295.     StartSound;
  296.     WaitSoundStates(S_QueueEmpty);
  297.     StopSound;
  298.     CloseSound;
  299.  
  300. A brief description of each API function used in QuickTone
  301. operation is provided in the QuickTone Help file QTONE.HLP,
  302. which is accessible through the QuickTone menu bar
  303. "Help/Contents" command.
  304.  
  305.  
  306. FEATURES
  307. --------
  308.  
  309.     NOTE SELECT FEATURES
  310.  
  311.     Play Active Note
  312.     ---- ------ ----
  313.     This control button plays the active note.
  314.  
  315.  
  316.     Clear Active Note
  317.     ----- ------ ----
  318.     This control button clears the current note from
  319.     memory and resets its SetVoiceNote parameters to
  320.     the "vacant" default values.
  321.  
  322.  
  323.     Clear All Notes
  324.     ----- --- -----
  325.     This control button clears all notes in the active
  326.     voice queue and resets their SetVoiceNote parameters
  327.     to the "vacant" default values.
  328.  
  329.  
  330.     QUEUE CONTROL / QUEUE DESTINATION FEATURES
  331.  
  332.     Display Queue
  333.     ------- -----
  334.     This control button displays the entire active voice
  335.     queue and its supporting API functions in a dialog box.
  336.  
  337.  
  338.     Save to Clipboard
  339.     ---- -- ---------
  340.     This control button copies the entire active voice
  341.     queue and its supporting API functions into the
  342.     Windows clipboard for pasting into a Windows-compatible
  343.     text or source code editor.
  344.  
  345.  
  346.     Write to File
  347.     ----- -- ----
  348.     This control button writes the entire active voice
  349.     queue and its supporting API functions into an ASCII
  350.     text file.  Voice queue #1 is saved as QUEUE_01.TXT,
  351.     queue #2 as QUEUE_02.TXT, and so on.
  352.  
  353.  
  354.     QUEUE SELECT FEATURES
  355.  
  356.     Play Active Queue
  357.     ---- ------ -----
  358.     This control button plays the active voice queue in
  359.     its entirety.  Blank or "vacant" notes are played as
  360.     pauses.
  361.  
  362.  
  363.     Play All Queues
  364.     ---- --- ------
  365.     This control button plays all defined notes in all
  366.     active voice queues.  Blank or "vacant" notes are
  367.     played as pauses.  Queues are played in sequence,
  368.     1-8.  Only queues containing active notes are played.
  369.  
  370.  
  371.     Clear All Queues
  372.     ----- --- ------
  373.     This control button clears all notes in all voice
  374.     queues and resets their SetVoiceNote parameters to the
  375.     "vacant" default values.
  376.  
  377.  
  378.     ACTIVE NOTE SETTINGS FEATURES
  379.  
  380.     Note Value
  381.     ---- -----
  382.     This scroll bar adjusts the active note's SetVoiceNote
  383.     "Note" parameter.  A value in the range 1-84 will produce
  384.     a tone; generally higher in pitch as the note value
  385.     setting is increased.  A value of zero (0) produces a
  386.     rest.
  387.  
  388.  
  389.     Note Duration/Recip.
  390.     ---- ---------------
  391.     This scroll bar adjusts the active note's SetVoiceNote
  392.     "Length" parameter, an integer value representing the
  393.     reciprocal of note length duration.  In QuickTone, this
  394.     value exercises primary control over the duration of
  395.     the played note; generally shorter as the length
  396.     setting is increased.  Length settings below 12 will
  397.     allow a note duration of a full second or more.
  398.  
  399.  
  400.     Note Duration/CDots
  401.     ---- --------------
  402.     This scroll bar adjusts the active note's SetVoiceNote
  403.     "CDots" parameter, an integer value representing note
  404.     duration in CDots.  In QuickTone, this value exercises
  405.     secondary control of the duration of the played note,
  406.     and may be used in conjunction with the "Length"
  407.     setting to alter the rest period just before or after
  408.     the note iself is played.  For most purposes, however,
  409.     this setting may be left at 1, with the "Length" value
  410.     controlling note duration exclusively.
  411.  
  412.  
  413.     MISC. FEATURES
  414.  
  415.     Help
  416.     ----
  417.     Comprehensive run-time help is provided via the Windows
  418.     Help system, through the menu bar "Help/Contents"
  419.     command.
  420.  
  421.     You may select specific topics to read, or browse from
  422.     topic to topic.  You may even print topics for later
  423.     reference.
  424.  
  425.  
  426. PRODUCT REGISTRATION
  427. ------- ------------
  428. QuickTone Prototyper for Windows is shareware, not freeware.
  429.  
  430. Product registration is necessary if companies like ours are
  431. to continue providing quality software for the shareware
  432. marketplace.
  433.  
  434. Registered users receive the registered version of this
  435. product (available in 3.5" or 5.25" disk formats).
  436. Registration also entitles the user to advance information
  437. on upcoming Pegasus Development products (including upgrades
  438. to QuickTone) -- as well as other new titles in our
  439. expanding product line.
  440.  
  441. The registration fee for this product is $16.00 (U.S.).
  442. Registrations are accepted both by telephone (with a major
  443. credit card) or by mail.  For orders outside the continental
  444. U.S., please add $2.00 for shipping and handling.
  445.  
  446. For your convenience, a registration form is provided here
  447. and within the QuickTone help file (accessible via the
  448. Windows Help system).  The help file registration form, or
  449. any help topic, is easily printable through the Windows Help
  450. menu bar "File/Print Topic" command.
  451.  
  452. We at Pegasus Development appreciate your support, and hope
  453. you enjoy using QuickTone 1.0.
  454.  
  455.  
  456. LIMITED WARRANTY AND REMEDIES
  457. ------- -------- --- --------
  458. Before release, our applications software is tested on a
  459. wide variety of hardware configurations, under the most
  460. rigorous test conditions possible.  We therefore warrant
  461. that the software will perform in substantial compliance
  462. with the specifications set forth in this text, provided
  463. that the software is used on the computer hardware and
  464. operating system(s) for which it was designed.
  465.  
  466. Pegasus Development makes no other warranties, expressed or
  467. implied, with respect to this software or media, including
  468. its quality or fitness for a particular purpose.
  469.  
  470. In no event will Pegasus Development be liable for any
  471. direct, indirect, special, incidental, or consequential
  472. damages arising from the use of or the inability to use this
  473. software, even if Pegasus Development has been advised of
  474. the possibility of such damages.
  475.  
  476. Pegasus Development is not responsible for any costs
  477. including, but not limited to, those incurred as a result of
  478. lost profits or revenues, loss of time or use of the
  479. software, loss of data, the cost of recovering software or
  480. data, the cost of substitute software, claims by third
  481. parties, or similar costs.  In no event will Pegasus
  482. Development's liability exceed the amount of the paid
  483. purchase fee.
  484.  
  485.  
  486. TRADEMARK ACKNOWLEDGMENTS
  487. --------- ---------------
  488. "Microsoft" and "Windows" are registered trademarks of
  489. Microsoft Corporation.
  490.  
  491. "Borland", "Borland C++", and "Turbo Pascal for Windows"
  492. are registered trademarks of Borland International, Inc.
  493.  
  494. Other brand and product names are trademarks or registered
  495. trademarks of their respective holders, and are hereby
  496. acknowledged.
  497.  
  498. ----------------------------------------------------------------------------
  499.  
  500. SOFTWARE REGISTRATION FORM
  501. -------- ------------ ----
  502. Return this form along with your remittance to:
  503.  
  504.     Pegasus Development
  505.     QuickTone 1.0 Registration
  506.     11900 Grant Place
  507.     Des Peres, MO. 63131
  508.     U.S.A.
  509.  
  510.     You can also register by telephone using your
  511.     MasterCard or VISA through Advanced Support Group's
  512.     Product Registration Hotline at 1-800-788-0787.
  513.  
  514.  
  515.     ______ QuickTone Registrations @ $16.00 U.S. each
  516.  
  517.     For orders outside the continental U.S., please add
  518.     $2.00 shipping and handling.
  519.  
  520.     Total enclosed . . . . . . . . . . . . . . $________
  521.     
  522.     Payment by:  [] Check      [] MasterCard     [] VISA
  523.     
  524.     Card# ____________________________ Exp. Date _______
  525.  
  526.     Signature of Cardholder_____________________________
  527.  
  528.     Name________________________________________________
  529.  
  530.     Address ____________________________________________
  531.  
  532.      City _______________________ State ____    Zip_________
  533.  
  534.     Telephone (______)______________________
  535.  
  536.     Disk Size Required: [] 3.5" (720K)   [] 5.25" (360K)
  537.  
  538.     Please indicate where you obtained QuickTone 1.0:
  539.  
  540.     (Mail Order, BBS, etc) _____________________________
  541.  
  542.     ____________________________________________________
  543.  
  544.     ____________________________________________________
  545.  
  546.