/*
**      Newton Developer Technical Support Sample Code
**
**      Sound Advice, shows how to load sound resources
**
**      by Maurice Sharp, Newton Developer Technical Support
**
**      Copyright © 1993-1995 by Apple Computer, Inc.  All rights reserved.
**
**      You may incorporate this sample code into your applications without
**      restriction.  This sample code has been provided "AS IS" and the
**      responsibility for its operation is 100% yours.  You are not
**      permitted to modify and redistribute the source as "DTS Sample Code."
**      If you are going to re-distribute the source, we require that you
**      make it clear in the source that the code was descended from
**      Apple-provided sample code, but that you've made changes.
*/

Sound Advice (Getting “snd ” resources to the Newt)
version 3

Version History
---------------

3 - added DefConst as the mechanism to define the sound. Also
    removed the mySound slot from the application main view, now
    use the constant direclty in the buttonClickScript. Updated this
    file...


The current release of NTK only allows automatic access to PICT
resources during the project build. If you want to include other types of
resources, you need to get them manually in your “Project Data” script.
The basic way to do this is to open the resource file, assign some variable
to the resource then close the resource file. You must also have an evaluate
slot in your project that refers to this variable.

The following example comes from the soundAdvice project that comes with
this interrim documentation.

Assume you have a file called resources that has a “snd ” resource called
“Boing” that you want to included in your project. You would go through 5
steps to get this resource:

1.	Bring the project window to the front and choose ‘Project Data’ from
the Project menu which will bring up a Project Data window.

2.	Type the following into the Project Data window
	rf := OpenResFileX(HOME & ":resources");
	DefConst('kBoingSound, GetSound11("Boing"));
	CloseResFileX(rf);

NOTE: "HOME" is an NTK compile-time variable

3. Wherever you want to use the sound, use the kBoingSound constant


Opening and Closing Resource Files

The example uses a couple of useful functions for opening and closing
resource files.
	fileId := OpenResFileX(<file-path>)
<file-path> is the full pathname of the file you want to open. 

For example, if your hard drive were called “Fred”, and in fred was a folder
called “Newton Work”, with another folder called “src”, then one called
“SoundAdvice”, and inside that folder was the file called “resources”, the
full path would be:
	“Fred:Newton Work:src:SoundAdvice:resources”

Opens the resource file with the full pathname <file-path> and assigns the
file point to the variable fileId. This variable can be used to close the
resource file later.

All resources in this file can be accessed until the file is closed.
	CloseResFileX(fileID)
	fileID is the ID of a file that you get from a call to OpenResFileX
Closes the resource file identifed by the fileID. The resources from that
file are no longer accessible


The “snd ” Resource Functions

	mySound := GetSound(<sound-name>)
	<sound-name> is the name of a 22Khz sampled  “snd ” resource
This function returns a sound frame based on an “snd ” resource that is
sampled at 22KHz. The sound MUST be sampled at that rate, if not, you will
get an error when you build. The listener will report an error like:

//-- Compiler Error: Sound resource: "Boing" must be sampled at 22 KHz
If you get this error, you probably have a sound that is sampled at 11KHz, so
use the GetSound11 call.
	mySound := GetSound11(<sound-name>)
	<sound-name> is the name of a 11Khz sampled  “snd ” resource
This function returns a sound frame based on an “snd ” resource that is
sampled at 11KHz. The sound MUST be sampled at that rate, if not, you will
get an error when you build. The listener will report an error like:

//-- Compiler Error: Sound resource: "Boing" must be sampled at 11 KHz
If you get this error, you probably have a sound that is sampled at 22KHz, so
use the GetSound call.
