/*

    File:       SoundApp.c

    Contains:   1.04: This was an update to support the Utilities Unit that MacDTS

developed.  Some of it was routines formally created for SoundApp,

with additional ones coming from other sources.  This helps to reduce

the "destractive" code from the samples and makes them easier to maintain.

1.1:    ¥ This is the "new" SoundApp which adds some new features.

        ¥ Some knowledge of the new Sound Manager is present

          in areas that were work-arounds for old Sound Manager bugs

        ¥ Recording of sounds is now possible with the Sound Input Manager

        ¥ The document window will keep the Record button hidden if

          the Sound Inpute Manager is not available for recording,

          otherwise it will expand the window size to show this button.

        ¥ Supports copy and pasting of sound resources

        ¥ Conversion to MPW 3.2 was established (with some amount of pain)

        ¥ SoundApp now has its own documents

        ¥ Supports launching by open documents from Finder

        ¥ Added color icons for the System 7.0 desktop

        ¥ Added the new Sound Manager error strings

        ¥ DoErrorSound tests for safe beeps

        ¥ Made Apple Legal happy by getting rid of the xxxxCmd

          and changed it to the freqDurationCmd.  Also got rid of

          any other use of the work "xxxx" in a musical context

1.2:    ¥ Translated into C, some clean up along the way

        ¥ Using universal headers

        ¥ Gave up on the DTS utilities code, everything is self-contained

Formatting was done with FONT = Courier, SIZE = 10, TABS = 4

many thanks to: Bo3b Johnson, Mark Bennett, Andy Shebanow, Keith

Rollin, Chris Derossi, Pete Helme, Darin Adler, and my co-workers that

sat near me while I was making lots of noise testing this application.

To the reader,

SoundApp.p is a sample application source file for demonstrating

the Sound Manager.  It requires the use of the SoundUnit to handle

all of the sound routines.  This portion of the source code handles the

applicationÕs management of memory, errors, user interface, etc..

The read me notes are here in the source code because people tend to

not read them otherwise.

SoundApp is a demonstration of the Sound Manager released in System

6.0.x.  SoundApp is also a example of how to write a Macintosh

application that performs good user interface and proper error

handling.  Believe it or not, but the Sound Manager portion was the

easiest part for me to write.  It was all the user interface and error

handling that was the most difficult.  One thing became very clear to

me in the course of writing this application.  The following axiom is

one of the few great truths in the universe.

If you write a Macintosh application without MacApp, youÕre working

too hard.

Throughout the development of SoundApp I would run into typical

situations that make programming a Macintosh too hard.  When this

happened I asked myself Òwhat would MacApp do?Ó and that was followed

by the thought Òthen why am I writing code that is already out there

for me to use?Ó  I started out intending on writing a very simple

application that anyone could read, and understand the Sound Manager.

I felt this meant not requiring the person to read Object Oriented

Pascal.  I accomplished part of my goal.  People should be able to

learn how to use the Sound Manager (in its present condition), but it

didnÕt turn out to be such a simple application as I had hoped for.

I have put a large amount of comments into the code.  This is

something IÕm really picky about.  People do not comment their code

enough.  Each procedure has a paragraph that should explain what to

expect that routine to do, and how it goes about doing it.  There are

some bigger issues that I will put into the release notes below.

There are some things that make the Macintosh harder to develop for

than it should be.  Simple things should be simple.  Too many things

on the Mac that should be simple are not.  Maybe someday these things

will be fixed.

¥ GetFontInfo requires a port set to the font in question.  If I

wanted to find the height of the System Font, I had to first set the

current port to the WindowMgr.  I could have used my own window, but

what if I needed the font info before I had a window available?

¥ The toolbox blows chunks when your heap gets Òtoo low.Ó  I believe

this magical number is between 32k and zero.  The odds of blowing

chunks increase logarithmically as one approaches 0 free bytes.

¥ The Dialog Manager is not a free lunch and in fact will cost you

plenty.

¥ ThereÕs no safe way to determine how much memory opening a

resource file will take away from your heap.

¥ ThereÕs no way to determine how safe it is opening a resource that

could be shared by other applications, especially on a local volume.

¥ The Resource Manager doesnÕt always set ResErr.

¥ The Sound Manager returns even less errors.

¥ The List Manager returns no errors.

¥ Writing a staggering routine for new windows encompasses a number

of difficulties.  How does one find the height of a windowÕs title

region before the window is visible?

Am I just a complainer?  Do I have a bad attitude?  Probably, but

IÕm just trying to point out the above areas make the Mac programming

experience difficult.  These are areas that get developers into

trouble.  These areas need a sign in front of them that says,

ÒDanger!Ó  These are areas that developers get into and then write to

MacDTS for help.

Notation Conventions

--------------------

All global variables begin with a lower case ÒgÓ.

All constants begin with ÒkÓ except for those noted here.

Resource IDs begin with ÒrÓ.

Menu IDs being with ÒmÓ and items with an ÒiÓ.

Resource strings begin with ÒsÓ.

Human Interface

---------------

This is the most important and about the most difficult aspect of

programming on the Macintosh.  In the development of SoundApp I gave much

thought to the human interface issues.  In fact, in talking with the Human

Interface Group additions to the existing guidelines were made.  The

method of window stacking used here was a new one.  This was documented in

a Human Interface Tech Note.  I even made one compromise (hard to

believe!) suggested by the Human Interface Group.  I originally had the

buttons and the list in my choice of font and size.  They felt that

buttons should be in the System font and the list should also be the same.

I liked my font choice better, but the group had a point that I really

couldnÕt argue with.  That was, ÒIf there isnÕt a compelling reason to

change something standard, then donÕt change it.Ó  Buttons on a Macintosh

typically appear in the System font.  Changing the font, just because I

wanted to, was considered gratuitous.  Standard File is in the System font

and it also contains a list and buttons.  Since my window are very similar

to that dialog, IÕm using the System Font.

SoundApp is never modal unless an error occurs and I need to show and

alert.  Controls are inactivated for inactive windows.  The default button

is given the proper outline, and this outline disappears when the window

is deactivated.  Keyboard equivalents for the buttons cause the button to

appear as if it had been clicked in.  The check box in the Standard File

dialog remembers the userÕs last setting.  The about box is only

semi-modal.  It will allow the user access to switch to another application.

The status window under some circumstances was found to disappear too quickly,

so a built in delay was added.  Windows are centered or stacked according

to the Human Interface Guidelines.  The sound level isnÕt adjusted by the

application, and instead the users is informed of the current level and

told how it can be adjusted.

The About box

-------------

ItÕs rad.  Has a color icon, shows the 'vers' resource, goes Moof!ª.  It

also demonstrates how to handle a modal window without the Dialog Manager.

This technique can be use for any window, including dialog windows.  The

dialogÕs update routine would call UpdtDialog.  The really new point to

notice is this window is modal but ONLY within the applicationÕs layer.

While running under MultiFinder, the user can switch to other

applications.  While the About window is present, it is the only window

belonging to the application that accepts user actions.

Memory Management

----------------

This has to be the most difficult portion of a Mac application to

write.  This along with the user interface.  I spent too many nights

chasing down crashes while running the application under low memory.

I found unpleasant surprises while doing this.  The Sound Manager

doesnÕt check for NIL pointers.  OpenResFile may take large portions

of my heap away.  The toolbox seems to need at least 32k of free space

in the heap of my Mac II running color.

I wrote a simple grow zone procedure that will dump a reserve memory

block.  This is only considered for use in an emergency.  I never rely

on using it directly.  If the reserve has been released, I will not

continue an operation such as playing a sound or showing the status

window until it is regained.  Grow zones should not be considered a

solution to memory management.  They can be used to augment your

overall memory management scheme.

Error Checking

--------------

Lots and lots and lots of it.  I could even do more.  Programmers

need to do more of this.  The Sound Manager will crash when

encountering a NIL pointer.  My application should never crash.  If

you can find a way to crash this application, then I want to hear

about it.  Using a bogus 'snd ' resources doesnÕt count and IÕve found

many of those.  Writing proper error checking into the code during

development really helped.  Always handle errors, and pass along the

error.  I will let the first error encountered to be passed all the

way up to the caller and eventually my error dialog will show up for

the user.

SetPort Strategy

----------------

Any routine that needs to use Quickdraw will set the port.  I do not

believe that it should also be responsible for restoring the port back

to what it may have been before the routine was called.  So, youÕll

find there is an absence of the GetPort, SetPort, do my thing, and

then SetPort again.  Instead I SetPort and do my thing.  The Mac often

is setting the port unnecessarily.

Strings

-------

All of my strings are resources.  There are no strings that appear

within the code.  This helps memory management and allows me to adjust

the application to international systems without compiling any code.

I could simply use ResEdit, or some other tool, to localize this

application.  I find it is just as easy to run Rez again than

attempting to use ResEdit.  Besides, after editing with ResEdit I want

the source for that and would have to run DeRez which isnÕt nearly as

clean as my original source files.

Window Stacking

---------------

I hate applications that will open a new document that covers up an

existing document, unless the new document covers the entire screen.

So, my applicationÕs documents have a small window size.  I wanted to

open new windows that would not cover up older ones.  This is nice for

the user, since they will not have to move windows just to get at

other documents.  ResEdit will stagger new windows off of the

frontmost window but I find that this isnÕt the best approach.  It

will still cover up other windows and I also donÕt like windows that

will open half way between two monitors.  I wanted a better approach:

one that would always stagger new windows and not cover up older ones.

When I want to center a window, I need to know its entire rectangle

size.  The rub is that I cannot determine its size until I show it

because I only know about the windowÕs boundsRect.  This does not

include the area that contains the title bar.  ThatÕs the strucRgn,

which is an empty region for an invisible window.  I could do what

MacApp does, but if I have to do another thing that MacApp already

does IÕll give up and stick with MacApp.  I ended up writing a routine

that takes a guess at the height of the windowÕs title bar.  This is

another thing that was harder than it should have been.

Dialog Manager (and some of the reasons I donÕt like it)

--------------------------------------------------------

My first approach was to use modeless dialogs for document windows,

thinking that I could write an application that would demonstrate how to

deal with them and all of their idiosyncrasies.  Not long into the

development cycle it became obvious to me that I was fighting something

that contained more disadvantages than advantages.  I removed all the

dialog code and only used standard windows and controls the old fashion

way.  In the case of the About window, which is semi-modal, I have a test

that will return TRUE for a window that should be treated as modal.  This

allows my window to be handled by my standard event handlers and I donÕt

have to write dialog filters.  There are some things that do not get

handled properly while calling ModalDialog.  ModalDialog ignores disk

insert events.  The activate or update events do not get handled for

background windows.  Using a modeless dialog fails with MultiFinder if

switching takes place while the dialog is the frontmost window.  The

problem is that DialogSelect ignores and removes the suspend/resume event.

Another advantage to all this is that drawing was much faster.

As an example of some of the problems with ModalDialog and the activate

event.  Try this with the Finder.  Open a window and choose ÒView by name.Ó

Then select a few names with the shift key and resize the window so the

vertical scroll bar is visible.  Move this window to one edge of the

screen or a second monitor.  Now choose ÒSet Startup.Ó  This is a modal

dialog.  If you look at the Finder window with the selected files, youÕll

notice that the scrollbar and the text are still highlited.  This is not

the proper user interface.  This is because the deactivate routines are

not called while in ModalDialog.  You can even find this problem with

SoundApp.  On deactivate events I will change my controls to the inactive

state.  If you place the buttons to the side of the screen and then bring

up the standard file dialog, youÕll notice that the buttons donÕt change

properly.  ModalDialog also prevents the application from updating

background windows too.  To solve this a dialog filter procedure is

required.  In most cases, this filter would be as complex and the event

loop.  It would also make it necessary to call your event routines from

outside of the normal event loop.  All on this isnÕt worth the effort.

You can see how this does not happen while using this applicationÕs

About window.  Select an item in the document window and choose ÒPlay

Melody.Ó  This will leave the status window on screen so that you can

drag it to cover the document window.  Now select ÒAbout SoundAppÓ to

bring up the about window.  This causes the status window to close,

which uncovers the document window leaving an invalid area.  The

document window gets an activate event, then the About window appears.

Then the document window is properly deactivated and updated.  Yeah,

just like it should happen.

So, the tradeoff was that I didnÕt have to work around all the

strange things the Dialog Manager does such as running a secondary

event loop, and requiring me to have userItems or filterProcs.  This

made the code smaller, more readable, and faster.  I think I will

avoid the Dialog Manger from now one unless IÕm using a very simple

dialog.  The about window of this application proved too much for the

Dialog Manager.

One thing dialogs are good for is running ResEdit and laying out the

dialog.  To help position controls, I used a DLOG resource of the same

size as my WIND resource.  The DITL of this dialog contains the

positions I wanted for my CNTL resources.  This helped me to look at

where I could expect my buttons to show up.  This is one of the main

reasons people think they need the Dialog Manager, because ResEdit

makes it easy to build dialogs.  ResEdit alone has contributed to

nearly all of the Dialog Manager abuse in the world today.

I used a Rect resource for positioning the list rectangle of the

document windows.  These windows look very much like a modeless

dialog.  (They used to be, but that presented to many problems.)  The

About window is also a standard window, but shown modally.  Just like

ModalDialog, but my modal window does allow switching under

MultiFinder.  You can change the window to a dBoxProc and then

MultiFinder will not switch while this is the active window.  To help

with the layout of the about window, I position the text within it

based on the size of the window.  The status window does this too.

These two things, the Rect resource and text based on the size of the

window, help when changing the text.  If the new text doesnÕt fit,

then resize the windowÕs resource.  I used some trick with Rez to help

layout my window contents.  Refer to the SoundApp.r sources.

IÕve read and understood Tech Note 203, and have learned how to

apply it.  Bo3b Johnson is a smart guy, and developers should trust

his opinions.

List Manager

------------

ItÕs very easy to be tempted by this part of the toolbox, along with

the Dialog Manager.  The List Manager is a slow beast at times.  It

also has some problems with Òdoing the right thing.Ó  IÕve found that

the list will not be updated properly when the user clicks in a cell

that is out of bounds.  LClick will return TRUE with a cell that

doesnÕt exists.  LActivate will erase the scrollbars instead of

highlighting the properly.  Finally, the List Manager does not return

errors.  How would a person know if LSetCell worked?

IÕve read and understood Tech Note 203, and have learned how to

apply it.

Resource Manager

----------------

I test all the handles being returned from the Resource Manager

before using them, and if I get a NIL then I look at ResError.

ResError sometimes lies and returns noErr and a NIL handle.  ResError

is usually good for getting an error code AFTER youÕve already found

an error.

Opening a resource file that is already open by another application

is dangerous.  The Resource Manager will not tell you when youÕve done

this.  There needs to be a OpenRFPerm that will return permission

errors such as resFileBusyErr.  Refer to Tech Note 185.

When I or the Toolbox needs to get at one of my resources,

CurResFile must be set to my application.  Also, look out for one

particularly nasty situation when switching resource files.   If the

segment loader goes for a CODE segment, it better be from our resource

file!  The idea here is, in case you didnÕt get it already, always

have the current resource file be set to the application.  If a

resource is needed from another file, switch momentarily to get the

resource and immediately restore the current resource file to the

application.  I take an added measure of defense and whenever I need a

resource I use the Get1Resource calls.  These will only search the

current resource file.

Strategies For Sound

--------------------

All of the Sound Manager code is contained in the SoundUnit.p.  This

code was written to be general purpose, providing useful routines for

other applications.  Lots of error checking is performed.  IÕve also

extended the support for SndPlay and made it really asynchronous.

IÕve demonstrated most of the abilities the present Sound Manager has

to offer.  I will have to revise the SoundAppUnit to include any new

features (e.g., multi channel support) when the next Sound Manager is

released.

I allocate my own memory to be used as sound channels.  I allocate

these pointers early in the applicationÕs startup time to avoid memory

fragmentation.  These channels are of the standard size (holding 128

commands) but IÕve extended the structure to include my own

information.  When I create a new sound channel, I pass it a pointer

to this memory.  This will link in the 'snth' resource and hardware to

my channel.  When I dispose of the channel, the Sound Manager will

purge this resource and disconnect me from the hardware.  When adding

the 'snth' resource, the Sound Manager will allocate a pointer into

the applicationÕs heap instead of the systemÕs.  This is a modifier

stub used by the 'snth'.  This could cause some problems with memory

management.  I create and dispose of all my channels as soon as

possible, and this doesnÕt cause me problems.

I keep track of which document is playing a sound, along with a

global of when the application is playing sound.  I needed to keep

track of which document is playing because if the user disposes of

that document, I will have to stop playing the sound contained in it

since the user wants to dispose of that data.  I keep track of when

the application is playing sound in a global.  This is only used by

the routine that calculates the sleep time for WaitNextEvent.

I came up with a pretty sick music notational system using Rez.

Refer to the notes in the SoundAppSnds.r file.  If youÕve just

finished a meal, wait four hours before reading.

The SoundUnit handles all of the Sound Manager code entirely.  This

eliminates any and all references to the Sound Manager from the

application.  The SoundUnit will return any error encountered while

calling the Sound Manager, and does some extra error checking the

Sound Manager doesnÕt do.

The portion of the application that uses the wave table synthesizer

is more complex than the other two.  I wanted to include an example

channel modifier for use in the wave table channels.  This would have

been a transpositional modifier that would take a given freqDurationCmd and

transpose it by some amount.  This would be nice for the routine that

plays a scale, by allowing the other three channels to be playing the

same scale but at a different interval.  Unfortunately, I found that

the Sound Manager has bugs using a modifier, at least with the wave

table synths, and could not use them.

IÕve created a few wave table sounds and keep them in a 'snd '

resource.  This allows me to change the sound of the wave table

channels and not change any of the code.  Creating wave table data is

complicated.  The example sounds IÕve included are samples IÕve taken

from various sources.  IÕve cleaned them up quit a bit.  This was to

set loop points, try and reduce clicks, correct the sample rates, and

base frequencies.  This is also a complicated task.  Maybe I should document

these techniques.

    Written by: Jim Reekes  

    Copyright:  Copyright © 1994-1999 by Apple Computer, Inc., All Rights Reserved.

                You may incorporate this Apple sample source code into your program(s) without

                restriction. This Apple sample source code has been provided "AS IS" and the

                responsibility for its operation is yours. You are not permitted to redistribute

                this Apple sample source code as "Apple sample source code" after having made

                changes. If you're going to re-distribute the source, we require that you make

                it clear in the source that the code was descended from Apple sample source

                code, but that you've made changes.

    Change History (most recent first):

                7/29/1999   Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1

*/

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// global defines

// All of this code is for System 7 and later

#define SystemSevenOrLater 1

// I don't use any obsolete stuff in the interfaces, and you shouldn't either.

// You also need to worry about names because the Code Fragment Manager binds

// system calls by name. Read the comments in ConditionalMacros.h

#define OLDROUTINENAMES 0

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// includes

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#include <FixMath.h>

#include <AppleEvents.h>

#include <Controls.h>

#include <Devices.h>

#include <DiskInit.h>

#include <Dialogs.h>

#include <Errors.h>

#include <Events.h>

#include <Files.h>

#include <Icons.h>

#include <Gestalt.h>

#include <Lists.h>

#include <LowMem.h>

#include <Menus.h>

#include <Memory.h>

#include <QuickDraw.h>

#include <Resources.h>

#include <Scrap.h>

#include <Script.h>

#include <SegLoad.h>

#include <StandardFile.h>

#include <TextUtils.h>

#include <ToolUtils.h>

#include <Traps.h>

#include <Types.h>

#include <Windows.h>

#include <limits.h>

#include <string.h>

#include <Sound.h>

#include <SoundInput.h>

#include "SoundUnit.h"

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// constants

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

enum {

    kOSTrapBit              = (1<<11),  /* bit 11 is the OS Trap bit */

    kTrapNumberMask         = 0x07FF,   /* bits used by the A-Trap mechanism */

    kPollingSleepTime       = 60,       //MultiFinderÕs sleep while sound is playing

    kNumberOfMasters        = 3,        //number of master pointer blocks we expect

    kSizeOfReserve          = (unsigned long)32 * 1024, //size of reserve memory for grow zone proc

    kMinSpace               = (unsigned long)32 * 1024, //minimum available memory I allow in heap

    kMemForSndDoc           = 20 * 1024, //minimal amount of memory needed by document

    rAppSignature           = 'SAPP',   //applicaitonÕs OS signature

    rSndAppDocType          = 'sDoc',   //document's file type

    kScrollbarAdjust        = 16-1,     //the width of the scrollbar in the list

    kListFrameInset         = -1,       //inset rectangle adjustment for list frame

    kStadardWhiteSpacing    = 13,       //inset rectangle adjustment for dialog items

    kRecordTop              = 40,       //40,50 is topLeft for SndRecord dialog

    kRecordLeft             = 50,       //40,50 is topLeft for SndRecord dialog

    kHiliteControlSelect    = 1,        //select the control

    kHiliteControlDeselect  = 0,        //deselect the control

    kCntlOn                 = 1,        //controlÕs value when truned on

    kCntlOff                = 0,        //controlÕs value when truned off

    kWindowPosStartPt       = 2,        //offset from the topLeft of the screen

    kWindowPosStaggerH      = 16,       //staggering amounts for new windows

    kWindowPosStaggerV      = 3,        //not including the windowÕs title height

    kMinWindowTitleHeight   = 19,

    kButtonFrameSize        = 3,        //buttonÕs frame pen size

    kButtonFrameInset       = -4,       //inset rectangle adjustment around button

    kButtonSizeH            = 17,       //standard height of buttons

    kDafaultButSizeH        = kButtonSizeH - kButtonFrameInset - kButtonFrameInset

};

//refer to the SoundApp.r file for the explaination about these numbers

enum {

    kNumOfButtons           = 6,        //the number of buttons in the window

    kSndButtonSizeW         = 100,      //SizeW of buttons in document window

    kSndButtonSizeH         = 22,       //heigth of buttons in document window

    kSoundWindowSizeH       = ((kNumOfButtons * (kStadardWhiteSpacing + kSndButtonSizeH))

                                + kStadardWhiteSpacing),

    kSoundWindowSizeW       = 296,

    //standard position for icons in alerts

    kIconWidthOrHeight      = 32,

    kStdAlertIconTop        = kStadardWhiteSpacing,

    kStdAlertIconLeft       = 23,

    kStdAlertIconBottom     = kStdAlertIconTop + kIconWidthOrHeight,

    kStdAlertIconRight      = kStdAlertIconLeft + kIconWidthOrHeight,

    kFSAsynch               = true,     //asynchronous File Manager call

    kEnterKey               = '\3',     //the keys IÕm looking for

#ifdef applec

    kReturnKey              = '\n',     //MPW C is wrong, the return key is "\r" not "\n"

#else

    kReturnKey              = '\r',

#endif

    kEscape                 = '\33',

    kUpArrow                = '\36',

    kDownArrow              = '\37',

    kPeriod                 = '.',

    kBackspace              = '\b',

//This bit set in the ioFlAttrib field if the fileÕs resource fork is open.

    kResForkOpenBit         = (1 << 2),

//For the delay time when flashing the menubar and highlighting a button.

    kDelayTime              = 8,        //8/60ths of a second

//The minimal number of ticks the ShowWindow needs to be visible.

    kShowTimeDelay          = 20,

//BUG NOTE: timbreCmd value of 255 on the Mac Plus/SE will cause a crash Sound Manager 1

    kSquareWave             = 240,      //square wave for squareWaveSynth

    kSineWave               = 0,        //sine wave for the squareWaveSynth

    kPreferredTimbre        = 190,      //my preferred timbre for the squareWaveSynth

//Application snd resources must be higher than this number.

    kSystemSndRange         = 8191      //This is the highest snd id reserved by Apple.

};

//The following constants are the resource IDs.

enum {

    rMenuBar                = 1000,     //applicationÕs menu bar

    rExitAlert              = 1000,     //emergency exit user alert

    rUserAlert              = 1001,     //error message user alert

    rSoundVolAlert          = 1002,     //sound is set low alert

    rSaveAlert              = 1003,     //save changes? dialog

    rGetNameDLOG            = 2000,     //get a name for the sound dialog

    rNameItem               = 3,        //edit text item in rGetNameDLOG

    rUserItem               = 5,        //user item to help draw default outline

    rCustomGetFileDLOG      = 2001,     //dialog template for CustomGetFile

    rSndOnlyCheckBox        = 10        //dialog item number in CustomGetFile

};

/*

These are the window IDs used in the applications.  Each one must be unique,

since they are used to identify which window the event took place in.

*/

enum{

    rAboutWindow            = 1000,     //about window

    rStatusWindow           = 1001,     //sound status window

    rSoundWindow            = 1002,     //sound document window

    rListRectID             = 1000,     //resource containing size of list rectangle

    rCancelCntl             = 1000,     //stop button ID for the status window

    rPlaySndCntl            = 1001,     //sound button IDs for the sound document window

    rHyperPlayCntl          = 1002,

    rPlayScaleCntl          = 1003,

    rMelodyCntl             = 1004,

    rStopCntl               = 1005,

    rRecordCntl             = 1006,

    rAboutOkCntl            = 1007,

    rUntitled               = 1000,     //string ID for untitled resources

    rAboutText              = 1001,     //string ID for text appearing in about window

    rPutFileMsg             = 1002,     //string for text appearing in SFPutFile dialog

    rMoofIcon               = 1000,     //resource ID for ICON of application

    rAppPict                = 1000,     //resource ID of picture shown in about window

    rSndCursor              = 1000      //cursor resource for our documents

};

/*

The following are the snd resource IDs contained in the application,

which start at ID 9000.  IDs 0 - 8191 are reserved for Apple.

*/

enum {

    rMoofSound              = 9000,     //snd for the about window

    rScaleSnd               = 9001,     //snd containing a scale

    rMelodyPart1            = 9002,     //snd containing a melody

    rMelodyPart2            = 9003,     //snd containing the harmony

    rMelodyPart3            = 9004,     //snd containing the harmony

    rMelodyPart4            = 9005,     //snd containing the harmony

    rWaveHarmony            = 9006,     //snd containing waveTable for harmony

    rWaveMelody             = 9007,     //snd containing waveTable for melody

    rCounterPt1             = 9008,     //snd containing soprano part of counter point

    rCounterPt2             = 9009,     //snd containing alto part of counter point

    rCounterPt3             = 9010,     //snd containing tenor part of counter point

    rCounterPt4             = 9011,     //snd containing bass part of counter point

    rSopranoVox             = 9012,     //snd containing waveTable of soprano voice

    rAltoVox                = 9013,     //snd containing waveTable of alto voice

    rTenorVox               = 9014,     //snd containing waveTable of tenor voice

    rBassVox                = 9015,     //snd containing waveTable of bass voice

    rSampleHarmony          = 9016,     //snd containing the sampled sound harmony

    rSampleMelody           = 9017      //snd containing the sampled sound melody

};

//The following are resource IDs for messages.

enum {

    sErrStrings             = 1000,     //error string STR# ID

    sStandardErr            = 1,        //An error has occurred.

    sMemErr                 = 2,        //A Memory Manager error has occurred.

    sResErr                 = 3,        //A Resource Manager error has occurred.

    sCurInUseErr            = 4,        //That file is currently in use.

    sWavesBroken            = 5,        //The wave table synthesizer is not available.

    sWrongVersion           = 6,        //This system does not support the Sound Manager...

    sLowMemory              = 7,        //Memory is too low to continue...

    sNoMenus                = 8,        //Could not find applicationÕs menu resources.

    sInitSoundErr           = 9,        //Could not initialize the SoundUnit.

    sSoundErr               = 10,       //The Sound Manager has encountered an error.

    sNewDocErr              = 11,       //Could not create a new document.

    sInitStatusErr          = 12,       //Error initializing the status window.

    sEditErr                = 13,       //Could not complete the edit command.

    sDocErr                 = 14,       //There is a problem with this document.

    sMsgStrings             = 1001,     //message string STR# ID

    sPlayingMsg             = 1,        //playing a sound

    sHyperMsg               = 2,        //playing a sound the Hyper way

    sScaleMsg               = 3,        //playing scale

    sMelodyMsg              = 4,        //playing melody

    sTimbresMsg             = 5,        //playing various timbres

    sCounterPtMsg           = 6,        //playing 4 part counter point

    sSMErrStrings           = 1002      //strings describing Sound Manager errors

};

/*

The following constants are used to identify menus and items. The menu IDs

have an ÒmÓ prefix and the item numbers within each menu have an ÒiÓ prefix.

*/

enum {

    mApple                  = 128,      //Apple menu and items

    iAbout                  = 1,

    mFile                   = 129,      //File menu and items

    iNew                    = 1,

    iOpen                   = 2,

    iClose                  = 4,

    iQuit                   = 12,

    mEdit                   = 130,      //Edit menu and items

    iUndo                   = 1,

    iCut                    = 3,

    iCopy                   = 4,

    iPaste                  = 5,

    iClear                  = 6,

    mDemos                  = 1000,     //Demos menu and items

    iCheckVolume            = 1,

    iSquareScale            = 3,

    iSquareMelody           = 4,

    iSquareTimbre           = 5,

    iWaveScale              = 7,

    iWaveMelody             = 8,

    iWaveSATB               = 9,

    iSampleMelody           = 11,

    iSampleSATB             = 12

};

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// macros

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// Define HighWord and LowWord macros for efficiency.

#define HighWord(aLong)     ((aLong) >> 16)

#define LowWord(aLong)      ((aLong) & 0x0000FFFF)

// accessing a rectangle's points

#define TopLeft(r)          (* (Point *) &(r).top)

#define BottomRight(r)      (* (Point *) &(r).bottom)

#define AbsoluteValue(n)    ((n > 0) ? n : -n)

#if GENERATINGCFM

#define CreateRoutineDescriptor(info, proc)                                 \

 RoutineDescriptor g##proc##RD = BUILD_ROUTINE_DESCRIPTOR(info, proc)

#define GetRoutineAddress(proc) (&g##proc##RD)

#else

#define GetRoutineAddress(proc) proc

#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// types

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

typedef RectPtr *RectHandle;

/*

This is a document layout that contains the window record and references

to the associating data.  The window record MUST be the first field.  This

is because I use the window pointer returned by the Toolbox to be a

pointer to my document.  To confirm that the window pointer is a document

pointer, I store an application reference in the window recordÕs refCon.

Then, I use a routine to test for the presence of this reference to insure

IÕm looking at one of my documentÕs windows.

*/

struct SndDocument {

    WindowRecord    window;             // must be first field

    short           resFile;            // documentÕs resource file

    short           vRefNum;

    long            dirID;

    ListHandle      list;               // documentÕs list of sounds

    Boolean         sndInUse;           // document is using a 'snd ' resource

};

typedef struct SndDocument SndDocument;

typedef SndDocument *SndDocPeek;        // to peek at the document record

// This is the status window layout.  The concept here is similar to the

// document type mentioned above.  The message is a string handle used to

// store the current message.

struct StatusWindow {

    WindowRecord    window;

    StringHandle    message;            // current text of status message

    long            showTime;           // time window was shown

};

typedef struct StatusWindow StatusWindow;

typedef StatusWindow *StatWindowPeek;

// This is the about window layout.  The concept here is similar to the

// document type mentioned above.  The comment is a string handle used to

// store the current message.

struct AboutWindow {

    WindowRecord    window;

    Handle          appPict;            // handle to picture of appÕs name

    Handle          comment;            // handle to string of about comments

};

typedef struct AboutWindow AboutWindow;

typedef AboutWindow *AboutWPeek;

// This is the template to the WIND resource.  I used it to load in the WIND

// resource and then adjust the boundsRect.  I also look at the procID to

// determine if it has a title bar or drag region.

struct WindowTemplate {                 // template to a WIND resource

    Rect        boundsRect;

    short       procID;

    Boolean     visible;

    Boolean     filler1;

    Boolean     goAwayFlag;

    Boolean     filler2;

    long        refCon;

    Str255      title;

};

typedef struct WindowTemplate WindowTemplate;

typedef WindowTemplate *WindowTPtr, **WindowTHndl;

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// inlines

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is a handy routine to copy pascal strings. It's smaller than the

library call pstrcopy, and faster too.

*/

#if GENERATING68K

#pragma parameter PStringCopy(__A0,__A1)

void PStringCopy(StringPtr source, StringPtr destination)

 FIVEWORDINLINE (0x7000, 0x1010, 0x12D8, 0x51C8, 0xFFFC);

//                  moveq   #0,d0

//                  move.b  (a0),d0

//          loop    move.b  (a0)+,(a1)+

//                  dbra    d0,loop

#else

#include <DriverServices.h>

#define PStringCopy(source, dest) PStrCopy(dest, source)

#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// prototypes

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

short NumToolboxTraps(void);

Boolean TrapExists(short theTrap);

pascal long MyGrowZone(Size cbNeeded);

Boolean LowOnReserve(void);

void RecoverReserve(void);

Boolean AllocateReserve(void);

Boolean FailLowMemory(long memRequest);

Boolean HasSelection(SndDocPeek sndDoc);

OSErr GetSelection(SndDocPeek sndDoc, SndListHandle *sndHandle);

void SelectNextCell(ListHandle list, Boolean next);

void SelectSndCell(SndDocPeek sndDoc, short resID);

OSErr InitSndList(SndDocPeek docPtr);

Boolean OpenByApp(FSSpecPtr file, WindowPtr *window);

Point GetGlobalMouse(void);

short GetWTitleHeight(short variant);

Point GetGlobalTopLeft(WindowPtr window);

void MyParamText(StringHandle text, StringPtr cite0, StringPtr cite1);

void CenterWindowRect(short variant, Rect *theRect);

WindowPtr GetCenteredWindow(short id, Ptr p, WindowPtr behind);

short CenteredAlert(short alertID);

DialogPtr GetCenteredDialog(short id, Ptr p, WindowPtr behind);

void DoButtonOutline(ControlHandle button);

void SelectButton(ControlHandle button);

void ActivateSndCntls(SndDocPeek sndDoc);

Boolean IsDAWindow(WindowPtr window);

Boolean IsDocWindow(WindowPtr window);

Boolean IsModalWindow(WindowPtr window);

void KillSound(void);

Boolean DoCloseWindow(WindowPtr window);

void AlertUser(short error, short messageID);

void EmergencyExit(short message);

void Terminate(void);

void DrawStatusWindow(void);

void ShowStatusWindow(short messageID);

void InitStatusWindow(void);

pascal void DoErrorSound(short soundNo);

void CheckSoundVolume(void);

void AddSndDocControls(WindowPtr window);

Boolean PositionAvailable(Point newPt, short wTitleHeight);

WindowPtr NewStackedWindow(short windID, Ptr windStorage);

OSErr CreateSoundDoc(short resRef, FSSpecPtr file);

void OpenSoundDoc(FSSpecPtr file);

void NewSoundDoc(void);

pascal Boolean SFFilter(CInfoPBPtr p, Boolean *sndFilesOnly);

pascal short SFGetHook(short mySFItem, DialogPtr dialog, void *sndFilesOnly);

void GetSoundDoc(void);

void DrawAboutWindow(WindowPtr window);

void DoAbout(void);

void PlaySelectedSnd(SndDocPeek sndDoc, short message);

void PlaySndSong(SndDocPeek sndDoc, short sndID);

void PlaySquareSong(short sndID);

void PlaySquareTimbres(void);

void PlayWaveScale(void);

OSErr GetSndSongs(short sndSongID1, short sndSongID2, short sndSongID3, short sndSongID4, SndListHandle *sndSong1, SndListHandle *sndSong2, SndListHandle *sndSong3, SndListHandle *sndSong4);

OSErr InstallWaveSnds(SndChannelPtr chan1, SndChannelPtr chan2, SndChannelPtr chan3, SndChannelPtr chan4, short waveID1, short waveID2, short waveID3, short waveID4);

void PlayWaveMelody(void);

void PlayWaveSATB(void);

void PlaySampleMelody(void);

void PlaySampleSATB(void);

pascal void DefaultOutline(WindowPtr window, short theItem);

void GetSndName(Str255 sndName);

OSErr AddSnd(SndDocPeek sndDoc, StringPtr sndNamePtr, SndListHandle sndHndl);

void ClearSnd(SndDocPeek sndDoc);

void DoRecordSound(SndDocPeek sndDoc);

void AdjustMenus(void);

void CopySnd(SndDocPeek sndDoc);

void CutSnd(SndDocPeek sndDoc);

void PasteSnd(SndDocPeek sndDoc);

void DoMenuCommand(long menuResult);

void DrawSndWindow(WindowPtr window);

void DoKeyDown(char key, WindowPtr window);

Boolean ListClick(SndDocPeek sndDoc, EventRecord *event);

void DoSndDocClick(SndDocPeek sndDoc, EventRecord *event);

void DoStatClick(StatWindowPeek statWindow, EventRecord *event);

void DoAboutClick(WindowPtr window, EventRecord *event);

void DoUpdate(WindowPtr window);

void DoActivate(WindowPtr window, Boolean becomingActive);

pascal OSErr QuitApplicationEvent(const AppleEvent *theAppleEvent, AppleEvent *reply, long handlerRefcon);

pascal OSErr OpenDocumentsEvent(const AppleEvent *theAppleEvent, AppleEvent *reply, long handlerRefcon);

pascal OSErr PrintDocumentsEvent(const AppleEvent *theAppleEvent, AppleEvent *reply, long handlerRefcon);

pascal OSErr OpenApplicationEvent(const AppleEvent *theAppleEvent, AppleEvent *reply, long handlerRefcon);

void DoEvent(EventRecord *event);

void AdjustCursor(RgnHandle region);

void EventLoop(void);

void Initialize(void);

void main(void);

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// Globals (The ÒgÓ prefix is used to emphasize that a variable is global.)

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

gMac is used to hold the result of a SysEnvirons call. This makes it

convenient for any routine to check the environment. It is considered

global information, anyway.

*/

    SysEnvRec gMac;                 //set up by Initialize

/*

gReserveMemory is a handle of reserve memory used by my grow zone

procedure.  If memory is attempted to be allocated and fails, my grow

zone will release this reserved block of memory.

*/

    Handle gReserveMemory;

/*

gStatusWindow is the window that tells the user whatÕs happening.  I show

it while a sound is playing, and remove it as soon as the sound is

complete.  It is initialized once during startup, and from then on two

routines are used to show and hide it.  This demonstrates orchestrating

multimedia, that sound/graphic idea, at least in a crude sort of way.

*/

    StatWindowPeek gStatusWindow;

/*

gAppResRef is the applicationÕs resource file reference.  I need to save

this since I can open other resource files.  The current resource file is

always gAppResRef unless I momentarily set it to another file to read its

resources, and then immediately restore it back.

*/

    short gAppResRef;               //set up by Initialize

/*

gInBackground is maintained by our osEvent handling routines. Any part of

the program can check it to find out if it is currently in the background.

*/

    Boolean gInBackground;          //maintained by Initialize and DoEvent

/*

We have to allocate our own QuickDraw globals when creating code for PowerMacs.

MetroWerks declares "qd" in their runtime, so don't do that twice.

*/

#if GENERATINGCFM && !defined(__MWERKS__)

    QDGlobals   qd;

#endif

/*

This is necessary because of the Apple Event Manager. We used to be able

to quit directly when the user choose Quit from the File menu. But because

of the design of Apple Events, we cannot call ExitToShell from the quit handler.

That event handler must set a flag and then check it in the event loop.

*/

    Boolean gTerminate;

// allocate the RoutineDescriptors for Power Mac toolbox calls

#if GENERATINGCFM

CreateRoutineDescriptor(uppGrowZoneProcInfo, MyGrowZone);

CreateRoutineDescriptor(uppFileFilterYDProcInfo, SFFilter);

CreateRoutineDescriptor(uppDlgHookYDProcInfo, SFGetHook);

CreateRoutineDescriptor(uppUserItemProcInfo, DefaultOutline);

CreateRoutineDescriptor(uppUserItemProcInfo, QuitApplicationEvent);

CreateRoutineDescriptor(uppUserItemProcInfo, OpenDocumentsEvent);

CreateRoutineDescriptor(uppUserItemProcInfo, PrintDocumentsEvent);

CreateRoutineDescriptor(uppUserItemProcInfo, OpenApplicationEvent);

#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// IMPLEMENTATION

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

InitGraf is always implemented (trap 0xA86E). If the trap table is big

enough, trap 0xAA6E will always point to either Unimplemented or some other

trap, but will never be the same as InitGraf. Thus, you can check the size

of the trap table by asking if the address of trap 0xA86E is the same as 0xAA6E.

*/

#pragma segment Initialize

short NumToolboxTraps(void)

{

    if ( GetToolboxTrapAddress(_InitGraf) == GetToolboxTrapAddress(_InitGraf + 0x0200) )

        return (0x0200);

    else

        return (0x0400);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Check to see if a given trap is implemented.  GetTrapAddress may screw up and

wrap around into the trap table if you give it a toolbox trap that is out of

range, so check for this first.

*/

#pragma segment Initialize

Boolean TrapExists(short theTrap)

{

    UniversalProcPtr    trapAddress;

    if ( !(theTrap & kOSTrapBit) )                      // is this an OS trap?

        trapAddress = GetOSTrapAddress(theTrap);

    else {                                              // no, this is a tool trap

        theTrap &= kTrapNumberMask;                     // get the trap number

        if ( theTrap < NumToolboxTraps() )              // can this tool trap exist?

            trapAddress = GetToolTrapAddress(theTrap);

        else

            return (false);

    }

    return ( GetToolboxTrapAddress(_Unimplemented) != trapAddress );

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is a very basic grow zone procedure.  My application keeps a reserve

handle of memory in case the Memory Manager gets a request for some memory

that is not available in my heap.  If memory were to get tight (<32k),

the Toolbox will crash the system, especially Quickdraw.  Before releasing

the reserve handle I make sure it isnÕt the GZSaveHnd.  This handle cannot

be touched by the grow zone procedure.

WARNING:  The grow zone procedure will be called and A5 may not be valid.

Read Tech Note #136 and 208

*/

#pragma segment Main

pascal long MyGrowZone(Size cbNeeded)

{

#pragma unused (cbNeeded)

    long theA5;

    long result;

    theA5= SetCurrentA5();

    if (((*gReserveMemory) != nil) && (gReserveMemory != GZSaveHnd())) {

        EmptyHandle(gReserveMemory);

        result = kSizeOfReserve;                    //released this much memory

    } else

        result = 0;                             //this may release more memory

    theA5= SetA5(theA5);

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Before my application attempts to use more memory, I call this routine

to check if IÕm already using my reserve memory.  If so, then I better

prepare to die or get my reserve back.

*/

#pragma segment Main

Boolean LowOnReserve(void)

{

    return((*gReserveMemory) == nil);       // empty handle is low reserve

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is called from the event loop if LowOnReserve returns that IÕm out of

the reserve memory.  This will recover the reserve memory block.  If this

fails, it will be called the next time through the event loop.

*/

#pragma segment Main

void RecoverReserve(void)

{

    ReallocateHandle(gReserveMemory, kSizeOfReserve);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is called at startup time to allocate the reserve memory block used

in the grow zone procedure.  If IÕm unable to obtain this reserve, then

return false to signal a failure.

*/

#pragma segment Initialize

Boolean AllocateReserve(void)

{

    gReserveMemory = NewHandle(kSizeOfReserve);

    return(gReserveMemory != nil);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Call PurgeSpace and see if the requested amount of memory exists in the

heap including a minimal amount of heap space.  Also, if my grow zoneÕs

reserve has been release, thatÕs considered a failure.  I donÕt perform

any purging here.  The Memory Manager will do this if it needs the space.

This routine can be called with a memRequest == 0.  This checks if the heap

space is getting critical.

*/

#pragma segment Main

Boolean FailLowMemory(long memRequest)

{

    long    total;

    long    contig;

    PurgeSpace(&total, &contig);

    return((total < (memRequest + kMinSpace)) || LowOnReserve());

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This a simple test to see if the user has a currently selected list item.

*/

#pragma segment Main

Boolean HasSelection(SndDocPeek sndDoc)

{

    Cell aCell;

    SetPt(&aCell, 0, 0);

    return(LGetSelect(true, &aCell, sndDoc->list));

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a document, this will find the currently selected cell in the list.

Then using this cell as an index number, I call Get1IndResource.  This

will return the proper handle.  Since the List Manager is zero based and

the Resource Manager isnÕt, I have to add one to the index.

BUG NOTE: GetIndResource will return a bogus handle if the index is not

positive.

*/

#pragma segment Main

OSErr GetSelection(SndDocPeek sndDoc, SndListHandle *sndHandle)

{

    Cell    aCell;

    OSErr   result;

    result = noErr;

    SetPt(&aCell, 0, 0);

    if (LGetSelect(true, &aCell, sndDoc->list)) {

        if (aCell.v > -1) {                     // GetIndResource doesnÕt like < 0

            UseResFile(sndDoc->resFile);        // only get our resources

            *sndHandle = (SndListHandle)Get1IndResource(soundListRsrc, aCell.v + 1);

            if (*sndHandle == nil)

                result = ResError();            // return any error

            UseResFile(gAppResRef);             // restore our resource file

        }

    }

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is used to allow the user to select items from the list by using

the arrow keys.  Given a list and the direction, this will select the

next cell.  It will do nothing if weÕre at the first cell and the user

wants to do even higher (sped), or if weÕre at the last cell and the

user wants to go even lower (rent a clue bud).

*/

#pragma segment Main

void SelectNextCell(ListHandle list, Boolean next)

{

    Cell    aCell;

    short   lastItem;

    lastItem = (**list).dataBounds.bottom - 1;      // bounds is 1 greater

    SetPt(&aCell, 0, 0);

    if (LGetSelect(true, &aCell, list)) {

        if ((next && (aCell.v < lastItem)) || ((!next) && (aCell.v > 0))) {

            LSetSelect(false, aCell, list);

            if (next)

                aCell.v = aCell.v + 1;

            else

                aCell.v = aCell.v - 1;

            SetPt(&aCell, aCell.h, aCell.v);

            LSetSelect(true, aCell, list);

            LAutoScroll(list);

        }

    }

    else                                            // if no cells selected...

        LSetSelect(true, aCell, list);              // select the first cell

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

VERSION 1.1:  This routine will go through the list of snd resources

looking for the one that has the resource ID matching the parameter passed

in.  First thing to do is deselect the current selection.  Then once the

matching resource is found, select that one and scroll it into view.  One

assumption made is that the resources and the list are both index in the

same order.  This is true for the sndDoc, since I built the list this way.

*/

#pragma segment Main

void SelectSndCell(SndDocPeek sndDoc, short resID)

{

    Str255 name;

    Cell aCell;

    Handle sndHndle;

    ResType rType;

    short testID;

    short index;

    short numSnd;

    index = 0;

    aCell.h = 0;

    aCell.v = 0;

    if (LGetSelect(true, &aCell, sndDoc->list))

        LSetSelect(false, aCell, sndDoc->list); //deselect any cell

    UseResFile(sndDoc->resFile);                //count only its resources

    numSnd = Count1Resources(soundListRsrc);    //number of sounds available

    do {

        index++;

        SetResLoad(false);                      //donÕt load any resources

        sndHndle = Get1IndResource(soundListRsrc, index); //only get snd from file

        SetResLoad(true);                           //back to normal resource operations

        GetResInfo(sndHndle, &testID, &rType, name);

    } while ((resID != testID) && (index < numSnd));

    UseResFile(gAppResRef);                     //restore our resource file

    aCell.h = 0;

    aCell.v = index - 1;

    LSetSelect(true, aCell, sndDoc->list);

    LAutoScroll(sndDoc->list);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is used to create the list showing all the snd resources in the file.

If anything goes wrong while attempting to get any of the resources, then I

return false.  I donÕt want the document to continue if something goes

wrong while reading a resource.  If I do get the resource, then I add its

name to the list in a new row.  IÕm assured that at least one resource is

in the file before this routine is called.  Untitled resources will get one.

*/

#pragma segment Open

OSErr InitSndList(SndDocPeek docPtr)

{

    short           index;

    short           resID;

    short           newRow;

    short           numSnd;

    Handle          resHandle;

    StringHandle    strHandle;

    ResType         itsType;

    Str255          resName;

    Str255          untitled;

    Cell            aCell;

    OSErr           result = noErr;

    strHandle = (StringHandle)Get1Resource('STR ', rUntitled);

    if (strHandle != nil)

        PStringCopy(*strHandle, untitled);      // save no name title

    else

        untitled[0] = 0;                        // at least an empty string

    UseResFile(docPtr->resFile);

    numSnd = Count1Resources(soundListRsrc);

    newRow = LAddRow(numSnd, 0, docPtr->list);

    for (index = 1; index <= numSnd; index++) {

        SetResLoad(false);                      // donÕt load any resources

        resHandle = Get1IndResource(soundListRsrc, index); // only get snd from file

        SetResLoad(true);                       // back to normal operations

        if (resHandle != nil) {                 // only if I got the snd

            GetResInfo(resHandle, &resID, &itsType, resName);

            if (StrLength(resName) == 0)        // if the snd isnÕt named...

                PStringCopy(untitled, resName); // give it a name

            SetPt(&aCell, 0, index - 1);

            LSetCell(&resName[1], StrLength(resName), aCell, docPtr->list);

        }

        else {                                  // resHandle == NIL

            result = resNotFound;               // problem with resource file

            break;                              // get out of the loop

        }

    }

    UseResFile(gAppResRef);                     // restore our resource file

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

In the case that the user has attempted to open a resource file that is

already open, this routine will scan my open documents for it.  If I find

that the requested file is already open by the application, then return

true and its window pointer.  The application can then simply select that

window.  If the resource file is open but not by this application, thatÕs

a problem and I donÕt use the resource file.  Many problems with using an

open resource file.  Now if the Resource Manager would take care of this

problem for us...

*/

#pragma segment Open

Boolean OpenByApp(FSSpecPtr file, WindowPtr *window)

{

    Str255 docName;

    WindowPtr testWindow;

    Boolean result;

    result = false;

    testWindow = FrontWindow();

    while (testWindow != nil) {

        if (GetWRefCon(testWindow) == rSoundWindow)

            if ((file->vRefNum == ((SndDocPeek)testWindow)->vRefNum)

                && (file->parID == ((SndDocPeek)testWindow)->dirID))

            {

                GetWTitle(testWindow, docName);

                if (EqualString(file->name, docName, false, true))

                {

                    *window = testWindow;

                    result = true;

                    break;

                }

            }

        testWindow = (WindowPtr)(((WindowPeek)testWindow)->nextWindow);

    }

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Get the global coordinates of the mouse.  Get the global coordinates by

calling GetMouse and LocalToGlobal.  This assumes the current port is a

valid graf port.  When wouldnÕt it be?

*/

#pragma segment Main

Point GetGlobalMouse(void)

{

    Point globalPt;

    GetMouse(&globalPt);

    LocalToGlobal(&globalPt);

    return(globalPt);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Try and determine the windowÕs title bar height.  This isnÕt easy,

especially if the window is invisible.  We all know how the standard Apple

System WDEF works, at least at this date we do.  I assume that method as

shown below.  I could do what MacApp does with the Function CallWDefProc.

If the user has installed a replacement for the System WDEF, then itÕs

their problem to deal with.  My method will work as long as Apple doesnÕt

change how the WDEF in System 6.0 calculates the title bar height.  This

will allow my application to work on international Macs that have a larger

system font than Chicago.  I check the windowÕs variant code for one that

includes a title bar.  I will have to change this routine to adjust for

the modal-moveable window type, which hasnÕt been defined yet.

In this routine, I violate my rule about not using the GetPort, SetPort,

SetPort sequence mentioned at the start of the file. Mostly, I do this

because itÕs not all that apparent that a routine called GetWTitleHeight

will change the port, so I make sure that it doesnÕt.

*/

#pragma segment Open

short GetWTitleHeight(short variant)

{

    FontInfo info;

    GrafPtr curGraf;

    GrafPtr wMgrPort;

    short wTitleHeight;

    short result;

    if (    (variant == documentProc)

         || (variant == noGrowDocProc)

         || (variant == zoomDocProc)

         || (variant == rDocProc) )

    {

        GetPort(&curGraf);

        GetWMgrPort(&wMgrPort);                     //I need to know the font...

        SetPort(wMgrPort);                          //info in the SystemÕs port

        GetFontInfo(&info);

        SetPort(curGraf);                           //restore current port

        wTitleHeight = info.ascent + info.descent + info.leading + 2;

        if (wTitleHeight < kMinWindowTitleHeight)

            wTitleHeight = kMinWindowTitleHeight;

        result = wTitleHeight;

    } else

        result = 0;                         //other window types have no title

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a window, this will return the top left point of the windowÕs

port in global coordinates.  Something this doesnÕt include, is the

windowÕs drag region (or title bar).  This returns the top left point

of the windowÕs content area only.

In this routine, I violate my rule about not using the GetPort, SetPort,

SetPort sequence mentioned at the start of the file. Mostly, I do this

because itÕs not all that apparent that a routine called GetGlobalTopLeft

will change the port, so I make sure that it doesnÕt.

*/

#pragma segment Main

Point GetGlobalTopLeft(WindowPtr window)

{

    GrafPtr theGraf;

    Point globalPt;

    GetPort(&theGraf);

    SetPort(window);

    globalPt = TopLeft(window->portRect);

    LocalToGlobal(&globalPt);

    SetPort(theGraf);

    return(globalPt);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

IÕm using string pointers (not necessarily Memory Manager pointers)

to the replacement strings.  Using Str255 would copy the string to the

stack, and then to the text handle.  This way it is only copied once.

*/

#pragma segment Main

void MyParamText(StringHandle text, StringPtr cite0, StringPtr cite1)

{

    long    offSet;

    char    param0[2] = {'^', '0'};

    char    param1[2] = {'^', '1'};

    long    newLength;

    if (StrLength(cite0) > 0)

        offSet = Munger((Handle)text, 1, param0, sizeof(param0), (Ptr)&(cite0[1]), StrLength(cite0));

    if (StrLength(cite1) > 0)

        offSet = Munger((Handle)text, 1, param1, sizeof(param1), (Ptr)&(cite1[1]), StrLength(cite1));

    newLength = GetHandleSize((Handle)text) - 1;

    if (newLength > 255)

        newLength = 255;

    (*text)[0] = newLength;                     // stringÕs new length byte

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a windowÕs portRect, this routine will center the rectangle on the

main device within the desktop region.  This excludes the menu bar area.

It follows the Apple Human Interface Guidelines for where to place a

window centered on the screen. That is, 1/3th of the desktop shows above

the window and 2/3ths below it.  It returns a new rectangle set to the

centered position.  The top and left of this rectangle can be used with

MoveWindow.  This routine only considers the main device.  CenterWindowRect

could take a GDevice as a parameter to center the VAR rect with.  This

would also allow Alerts or dialogs that are closely associated with a

document window to be centered relative to the monitor that contains that

document.  This is also one of the Human Interface Guidelines.  MacApp 2.0

has a utility CalcScreenRect that you can borrow from to include this.

WARNING: This routine may move or purge memory.

*/

#pragma segment Open

void CenterWindowRect(short variant, Rect *theRect)

{

    Point rectSize;

    short wTitleHeight;

    wTitleHeight = GetWTitleHeight(variant);        //get title height

    SetPt(&rectSize, theRect->right, theRect->bottom + wTitleHeight);   //get size of rect

    SubPt(TopLeft(*theRect), &rectSize);            // include it in size

    theRect->top = ((qd.screenBits.bounds.bottom - qd.screenBits.bounds.top - GetMBarHeight() - rectSize.v)

                        / 3) + GetMBarHeight();     //1/3th below menubar, centered horz

    theRect->left = ((qd.screenBits.bounds.right - qd.screenBits.bounds.left) - rectSize.h) / 2;

    SetPt(&BottomRight(*theRect), theRect->left, theRect->top); //return adjusted rect

    AddPt(rectSize, &BottomRight(*theRect));

    theRect->top += wTitleHeight;                   //remove title height from rect

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a window ID, this routine will center the windowÕs rectangle before

showing it on the main screen.  This follows the Apple Human Interface

Guidelines for where to place a centered window on the screen.  If the

window is closely associated with another window, considerations should be

given to where that other window is located.  If this other window is on a

screen other then the main monitor, then it would be best to center the

window on that other monitor.

VERSION 1.1: There is a problem with GetNewWindow in the old Mac Plus and

SE ROMS.  It will call ReleaseResource on the 'WIND' resource within

GetNewWindow.  This make the handle invalid after the call.  Therefore,

before calling HPurge, we get the resource once again.

*/

#pragma segment Open

WindowPtr GetCenteredWindow(short id, Ptr p, WindowPtr behind)

{

    Rect newRect;

    WindowTHndl windTemplate;

    WindowPtr window;

    window = nil;                                               //initialize result

    windTemplate = (WindowTHndl)(Get1Resource('WIND', id));

    if (windTemplate != nil) {

        HNoPurge((Handle)windTemplate);

        newRect = (**windTemplate).boundsRect;

        CenterWindowRect((**windTemplate).procID, &newRect);

        (**windTemplate).boundsRect = newRect;

        window = GetNewWindow(id, p, behind);

        HPurge(Get1Resource('WIND', id));

    }

    return(window);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given an Alert ID, this routine will center the alertÕs rectangle before

showing it on the main screen.  This follows the Apple Human Interface

Guidelines for where to place a centered window on the screen.  If the

Alert is closely associated with another window, considerations should be

given to what the window is located.  If this other window is on a screen

other then the main monitor, then it would be best to center the Alert on

that other monitor.

VERSION 1.2: System 7 supports auto-positioning of windows and dialog, so

this routine isn't being called anymore. I has been left in the sources

for the readers that may be interested in knowing how it works.

*/

#pragma segment Open

short CenteredAlert(short alertID)

{

    AlertTHndl alertHandle;

    Rect alertRect;

    alertHandle = (AlertTHndl)(Get1Resource('ALRT', alertID));

    if (alertHandle != nil) {

        HNoPurge((Handle)alertHandle);

        alertRect = (**alertHandle).boundsRect;

        CenterWindowRect(dBoxProc, &alertRect);

        (**alertHandle).boundsRect = alertRect;

        HPurge((Handle)alertHandle);

    }

    return(Alert(alertID, nil));

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a dialog ID, this routine will center the dialogÕs rectangle before

showing it on the main screen.  This follows the Apple Human Interface

Guidelines for where to place a centered window on the screen.  If the

dialog is closely associated with another window, considerations should be

given to what the window is located.  If this other window is on a screen

other then the main monitor, then it would be best to center the dialog on

that other monitor.

VERSION 1.1: There is a problem with GetNewDialog in the old Mac Plus and

SE ROMS.  It will call ReleaseResource on the 'WIND' resource within

GetNewWindow.  This make the handle invalid after the call.  Therefore,

before calling HPurge, we get the resource once again.

VERSION 1.2: System 7 supports auto-positioning of windows and dialog, so

this routine isn't being called anymore. I has been left in the sources

for the readers that may be interested in knowing how it works.

*/

#pragma segment Open

DialogPtr GetCenteredDialog(short id, Ptr p, WindowPtr behind)

{

    Rect newRect;

    DialogTHndl dlogTemplate;

    DialogPtr dialog;

    dialog = nil;                                               //initialize result

    dlogTemplate = (DialogTHndl)Get1Resource('DLOG', id);

    if (dlogTemplate != nil) {

        newRect = (**dlogTemplate).boundsRect;

        CenterWindowRect((**dlogTemplate).procID, &newRect);

        (**dlogTemplate).boundsRect = newRect;

        HNoPurge((Handle)dlogTemplate);

        dialog = GetNewDialog(id, p, behind);

        HPurge(Get1Resource('DLOG', id));

    }

    return(dialog);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given any control handle, this will draw an outline around it.  This is

used for the default button of a window.  The extra nice feature here is

that IÕll erase the outline for buttons that are inactive.  Seems like

there should be a Toolbox call for getting a controlÕs hilite state.

Since there isnÕt, I have to look into the control record myself.  This

should be called for update and activate events.

The method for determining the oval diameters for the roundrect is a

little different than that recommended by Inside Mac.  IM I-407 suggests

that you use a hardcoded (16,16) for the diameters. However, this only

looks good for small roundrects. For larger ones, the outline doesnÕt

follow the inner roundrect because the CDEF for simply buttons doesnÕt

use (16,16). Instead, it uses half the height of the button as the

diameter. By using this formula, too, our outlines look better.

WARNING: This will set the current port to the controlÕs window.

*/

#pragma segment Main

void DoButtonOutline(ControlHandle button)

{

    Rect theRect;

    PenState curPen;

    short buttonOval;

    if (button != nil) {

        SetPort((**button).contrlOwner);

        GetPenState(&curPen);

        PenNormal();

        theRect = (**button).contrlRect;

        InsetRect(&theRect, kButtonFrameInset, kButtonFrameInset);

        buttonOval = (theRect.bottom - theRect.top) / 2;

        if (((**button).contrlHilite == kControlNoPart))

            PenPat(&qd.black);

        else

            PenPat(&qd.gray);

        PenSize(kButtonFrameSize, kButtonFrameSize);

        FrameRoundRect(&theRect, buttonOval, buttonOval);

        SetPenState(&curPen);

    }

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given the button control handle, this will cause the button to look as

if it has been clicked in.  This is nice to do for the user if they type

return or enter to select the default item.

*/

#pragma segment Main

void SelectButton(ControlHandle button)

{

    unsigned long finalTicks;

    HiliteControl(button, kHiliteControlSelect);

    Delay(kDelayTime, &finalTicks);

    HiliteControl(button, kHiliteControlDeselect);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Given a sound document, this routine goes through the control list looking

for a control that needs to be activated, or deactivated what ever the

case maybe.  The Play button is the default button, and it also needs its

outline drawn.  The Stop button is always active on the front most window.

This is true even if there is no selection made in the windowÕs list.  The

Stop button is a global action, regardless of what is happening in the window.

VERSION 1.1:  Stop button is only active while a sound is playing.

*/

#pragma segment Main

void ActivateSndCntls(SndDocPeek sndDoc)

{

    ControlHandle control;

    long cntlRefCon;

    Boolean activate;

    activate = ((WindowPeek)sndDoc)->hilited && HasSelection(sndDoc);

    control = (ControlHandle)((WindowPeek)sndDoc)->controlList;

    while (control != nil) {

        cntlRefCon = GetControlReference(control);

        if (    (cntlRefCon == rPlaySndCntl)

             || (cntlRefCon == rHyperPlayCntl)

             || (cntlRefCon == rPlayScaleCntl)

             || (cntlRefCon == rMelodyCntl)) {

            if (activate)

                HiliteControl(control, kControlNoPart);

            else

                HiliteControl(control, kControlInactivePart);

            if (cntlRefCon == rPlaySndCntl)

                DoButtonOutline(control);

        }

        if (cntlRefCon == rStopCntl) {

            if (((WindowPeek)sndDoc)->hilited && HasChannelOpen())

                HiliteControl(control, kControlNoPart);

            else

                HiliteControl(control, kControlInactivePart);

        } //cntlRefCon == rStopCntl

        if (cntlRefCon == rRecordCntl) {

            if (((WindowPeek)sndDoc)->hilited)

                HiliteControl(control, kControlNoPart);

            else

                HiliteControl(control, kControlInactivePart);

        } //cntlRefCon == rRecordCntl

        control = (**control).nextControl;

    }

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Check if a window belongs to a desk accessory.  This will first test for a

nil window.  DAs will have a negitive windowKind.

*/

#pragma segment Main

Boolean IsDAWindow(WindowPtr window)

{

    if (window == nil)

        return(false);

    else    //DA windows have negative windowKinds

        return(((WindowPeek)window)->windowKind < 0);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Check to see if a window is a document window.  This will first test for a

nil window.  Document windows all have a refCon set to rSoundWindow.  This

insures there is document type information after the window record.

*/

#pragma segment Main

Boolean IsDocWindow(WindowPtr window)

{

    Boolean result;

    if (window == nil)

        result = false;

    else

        result = (GetWRefCon(window) == rSoundWindow);

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This test will return true for a window that needs to be treated as a

modal window.  To include additional windows, add the windowÕs refCon

value to the set of modal windows.

*/

#pragma segment Main

Boolean IsModalWindow(WindowPtr window)

{

    long    wRef;

    Boolean result;

    if (window == nil)

        result = false;

    else {

        wRef = GetWRefCon(window);

        result = (wRef == rAboutWindow);        // test for all our modal windows

    }

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

This is used to free up all the sound data and channels in use.  There are

two reasons for using this routine.  One is after a sound has completed

the other is to terminate a sound that may be in progress.  For this

second reason, this routine should always be used before playing a new

sound.  When disposing of a sound channel, this sets all documentÕs

sndInUse flags to false.  I can call this routine at any time.  When I

find that the memory reserve is used, I will call this to free up any

possible sound resources which tend to be large.  Another important point

is the human interface issue of hiding the status window.  ItÕs possible

that  playing some short sounds could cause the status window to disappear

before the user had much of a chance to see it.  To solve this, there is a

delay that insures the status window was visible for a minimal time.

VERSION 1.1:  Update the document's controls since know that the sound

is no longer playing the buttons in the document window need to be updated.

*/

#pragma segment Main

void KillSound(void)

{

    WindowPtr window;

    if (HasChannelOpen()) {                         // if a channel is open...

        window = FrontWindow();                     // set all documentÕs flags

        while (window != nil) {

            if (IsDocWindow(window))                // if this is my document...

                ((SndDocPeek)window)->sndInUse = false; // then it is no longer active

            window = (WindowPtr)((WindowPeek)window)->nextWindow;

        }

    }

    if (HasSoundCompleted()) {                      // why were we called?

        DoSoundComplete();                          // from completion

        // delay for status window to show a minimal amount of time

        while ((TickCount() - gStatusWindow->showTime) < kShowTimeDelay) {};

    }

    else

        FreeAllChans();                             // or just because

    HideWindow((WindowPtr)gStatusWindow);

    window = FrontWindow();

    if (IsDocWindow(window))

        ActivateSndCntls((SndDocPeek)window);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Close any of my windows.  At this point, if there was a document

associated with a window, you could do any document saving processing if

it has been changed since being opened.  DoCloseWindow would return true

if the window actually closed.  false would be returned, as an example, if

the user chose ÒCancelÓ in the Save AsÉ dialog.  An important detail is if

the window to be close is one of my documents that is currently playing a

sound.  We cannot dispose of it yet, since the sound resource owned by the

document would be in use by the Sound Manager.  So, I test the documentÕs

sndInUse flag and if it is in use I call KillSound.  The About window

contains some resource handles.  I only mark them purgeable, but I could

use ReleaseResource and then DisposHandle.

*/

#pragma segment Main

Boolean DoCloseWindow(WindowPtr window)

{

    Boolean     result = true;

    switch (GetWRefCon(window)) {

        case rSoundWindow:

            if (((SndDocPeek)window)->sndInUse)     // contain a snd in use?

                KillSound();                        // not any more

            if (((SndDocPeek)window)->list != nil)  // dispose of document data

                LDispose(((SndDocPeek)window)->list);

            if (((SndDocPeek)window)->resFile != 0)

                CloseResFile(((SndDocPeek)window)->resFile);

            CloseWindow((WindowPtr)window);

            DisposePtr((Ptr)window);                // dispose of our doc storage

            break;

        case rStatusWindow:

            DisposeHandle((Handle)gStatusWindow->message);

            CloseWindow((WindowPtr)gStatusWindow);

            DisposePtr((Ptr)gStatusWindow);

            break;

        case rAboutWindow:

            if (((AboutWPeek)window)->comment != nil)   // never dispose...

                HPurge(((AboutWPeek)window)->comment);  // a Resource handle

            if (((AboutWPeek)window)->appPict != nil)

                HPurge(((AboutWPeek)window)->appPict);

            CloseWindow((WindowPtr)window);

            DisposePtr((Ptr)window);

            break;

        default:

            if (IsDAWindow(window))                     // we can close DAs too

                CloseDeskAcc(((WindowPeek)window)->windowKind);

            break;

    } // switch GetWRefCon(window)

    return(result);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Display an alert to inform the user of an error.  MessageID acts as an

index into a STR# resource of error messages.  This will attempt to

replace the error number with a string if the sound is a Sound Manager

error.

BUG NOTE: GetIndString will return a bogus string if the index is not

positive.

*/

#pragma segment Main

void AlertUser(short error, short messageID)

{

    Str255  msg1;

    Str255  msg2;

    short   theItem;

    UseResFile(gAppResRef);                     // restore our resource file

    if (messageID > 0)

        GetIndString(msg1, sErrStrings, messageID);

    else

        msg1[0] = 0;                            // case thereÕs no message

    if ((error <= noHardware) && (error >= badFormat))

        GetIndString(msg2, sSMErrStrings, AbsoluteValue(error) + noHardware + 1);

    else

        NumToString(error, msg2);

    ParamText(msg1, msg2, "\p", "\p");

    theItem = Alert(rUserAlert, nil);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Display an alert that tells the user an error occurred, then exit the

program.  This routine is used as an ultimate bail-out for serious errors

that prohibit the continuation of the application.  Errors that do not

require the termination of the application are handled with AlertUser.

Error checking and reporting has a place even in the simplest application.

BUG NOTE: GetIndString will return a bogus string if the index is not

positive.

*/

#pragma segment Main

void EmergencyExit(short message)

{

    Str255  msg;

    short   theItem;

    SetCursor(&qd.arrow);

    if (message > 0)

        GetIndString(msg, sErrStrings, message);

    else

        msg[0] = 0;                             // case thereÕs no message

    ParamText(msg, "\p", "\p", "\p");

    theItem = Alert(rExitAlert, nil);

    ExitToShell();                              //gotta go!

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Clean up the application and exit.  I close all of the windows so that

they can update their documents, if any.  Dispose of the SoundUnit and

close the status window if the user really wants to quit.

*/

#pragma segment Main

void Terminate(void)

{

    WindowPtr aWindow;

    Boolean closed;

    closed = true;

    KillSound();                                    //stop any sound in progress

    do {

        aWindow = FrontWindow();                    //get the current front window

        if (aWindow != nil)

            closed = DoCloseWindow(aWindow);        //close this window

    } while ((closed) && (aWindow != nil));         //do all windows

    if (closed) {

        FreeSoundUnit();                            //get rid of all sound equipment

        gTerminate = true;                          //exit if no cancellation

    }

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Draw the status message and update the button.  I setup a rectangle that

is the text area.  This is the entire window area, inset a small amount.

I also subtract from the bottom of the rectangle the area used by the button.

Doing things this way allowed me to change the size of the window and

not change any of this code.  The rectangle used by text will fill the

window regardless of the new size I give it in the WIND resource.

*/

#pragma segment Main

void DrawStatusWindow(void)

{

    Rect    theRect;

    PenNormal();

    theRect = ((WindowPtr)gStatusWindow)->portRect;

    theRect.bottom = theRect.bottom - kDafaultButSizeH;

    InsetRect(&theRect, kStadardWhiteSpacing, kStadardWhiteSpacing);

    HLock((Handle)gStatusWindow->message);

    TETextBox((*(gStatusWindow->message) + 1),

                **(gStatusWindow->message), &theRect, teJustLeft);

    HUnlock(((Handle)gStatusWindow->message));

    UpdateControls((WindowPtr)gStatusWindow, ((WindowPtr)gStatusWindow)->visRgn);

    DoButtonOutline((ControlHandle)((WindowPeek)gStatusWindow)->controlList);

}

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/*

Whenever I start a sound, I show this status window.  It will contain a

message showing what is currently happening.  A very good rule is not to

perform drawing outside of the update event.  I bend that rule here.  I

could simply select this window and show it.  This would allow my normal

drawing and activating routines to be called.  The problem with that was,

I found that many times the status window appeared and then disappeared

before these update routines had a chance to draw the window.  This left

the user with a blank window that immediately went away.  So, I do the

activation and drawing right after showing it.

BUG NOTE: GetIndString will return a bogus string if the index is not

positive.

*/

#pragma segment Main

void ShowStatusWindow(short messageID)

{