TMusic Component - README
=========================

Purpose
-------
Apart from sounds generated via the soundcards,
windows doesn't offer much sound via the built-
in PC speaker.

Still programs can gain some user friendlyness
when appropriate sounds at appropriate times
are produces, like a high BEEP-BEEP to acknowledge
some typed data or a low BUZZ that informs that
data is rejected. DOS-PASCAL had the Sound-procedure
which is missing here...

There is hardware in the PC to produce various
frequencies, the only thing to be done is to
set the frequency, switch on the speaker, and
after a while, switch off the speaker.

To control the hardware, direct access to the
ports is requiered. AFAIK, there is no API-call
to do so. Fortunately Windows lets me control
these ports without GPF... Maybe if you have
low-level drivers for the PC-speaker Windows won't
let you use this component!

To switch off the speaker, the MMTimer implemen-
tation like the one in the RTCTimer is used.
Thanks Immo Wache!

>>> Due to the usage of this timer only ONE instance
>>> of TMusic can be used in an application!

This gives great accuracy and lets playing sounds
or music continue even when the application is
minimized or when windows are being dragged around
the screen. Even if you skip to a DOS-session,
the sound goes on... <g>.

Installation
------------
1. Copy the files MUSIC.DCU and MUSIC.DCR to your
   components directory or to whatever directory
   you like.

2. Select Option/Install Components from the
   Delphi menu

3. Click the ADD button, click the Browse button,
   list files of type .DCU and click on MUSIC.DCU

4. OK,OK and the library will be rebuilt.
   TMusic-component will appear on the CTL-page
   of the palette, but you can place it anywhere
   you like.


The Component
-------------

Properties:

AutoRepeat
==========
repeats played music until
switched off by setting autorepeat to false
or by calling the TMusic.Stop method.

MusicList
=========
is a stringgrid that contains the
music to be played. See below for a description.

Name and Tag are default properties.

NoteDuration
============
is the basic duration of a full note.



Methods:

Function Start(start,finish:integer): integer

Starts music as listed in the MusicList,
starting at line 'start' and ending with line 'finish'
(based on 0)
returns -1 if MusicList is empty
returns -2 if start/finish are outside limits

if finish > MusicList.Count lines then finish
is truncated.
returns 0 if all ok, music should start

Between start and finish there can be 1000 notes
maximum. More then 1000 are ignored.


Function Stop:integer;
Stops current music if any is being played.
Result can be ignored.



Events:

There are no events.



Please see the MUSIDEMO project for
some examples. Switch on AutoRepeat and
fiddle around with windows...


MUSICLIST Syntax
----------------
Any empty line or line beginning with an *
are ignored.
* lines can be used for comments.

Base = octaaf 7

The following convention is used for
characters in the MusicList.Lines:

'c' is a C
'C' is a C#
'd' is a D
'D' is a D#
'e' is an E
'f' is an F
'F' is an F#
'g' is a G
'G' is a G#
'a' is an A
'A' is an A#
'b' is a B
'0' zero is pause

'1'...'9' sets the octave absolute
'>' increase the octave
'<' decreases the octave

'V'..'Z' or 'v'..'z'
sets the duration:
Z=1
Y=1/2
X=1/4
etc based on the property NoteDuration for
a full note

'+' doubles the speed (halves notetime)
'-' halves the speed

Unknown characters are ignored.



SHAREWARE
=========
This component is $16 - shareware.

It has a 'nag' messagebox that appears
anytime you use the component. Sorry for
that. You know why....

If you like to register:

- go SWREG, keyword CTL

- send me a cheque or int. moneyorder

  to J vd Waeter pc applicaties
     Sottegemstraat 44
     4382 EN  Vlissingen
     the Netherlands

- you will receive an unnagged copy of
  the TMusic component by e-mail or by
  snailmail.

Any suggestions are welcome,
please e-mail to 100332.3264@compuserve.com


Disclaimer
==========
This component adresses the ports of the speaker
directly. It is the users responsibility this could
not result in any loss of data or other damage.

