The speakAlert command speaks the text out loud, at the same time displaying the text in a dialog box.

This custom command takes one parameter, pText, and is used with a statement such as the following:

speakAlert "Go home now!"

speakAlert the finishMessage of me

speakAlert field "Info"

The first thing this handler does is make sure there is some text in the pText parameter. If there is no text, the dialog box will be empty, a bit confusing for the user, so to avoid this, if the pText parameter is empty, the handler uses the exit control structure to skip the rest of the handler.

if pText is empty then
	exit speakAlert 
end if

The revSpeak command speaks the text passed to it out loud, using the built-in text-to-speech capability of Mac OS, OS X, and Windows systems. This command is not currently supported on Unix systems.

Because the revSpeak command is not supported on all platforms, we'll place it inside a try control structure. The try control structure offers a flexible way of handling errors: if something inside the try block causes an execution error, no error window is displayed. Instead, if there was an error, the statements in the catch block are executed. If there is no error, the catch block is ignored.

try 
	revSpeak pText
catch theError 
	put return & "(Cannot speak text on this system.)" after pText
	beep 
end try

If the revSpeak command is not supported on the current system, using it normally causes an execution error. In this handler, however, it's inside a try control structure, so LiveCode executes the contents of the catch block instead of displaying an error message. The catch block in this handler adds a message to the end of the text to notify the user that speech isn't supported. It also beeps, so that if the current system can't speak, it at least makes a noise. Text to speech is often used in situations where the user may not be looking at the screen. The sound makes sure users are alerted, even if they're doing something else when the dialog box appears.

Finally, the handler displays the message in an answer dialog box. Because speaking the message takes a few seconds, the effect for the user is that the dialog box appears at more or less the same time that the computer begins speaking.

answer pText

on speakAlert pText
	if pText is empty then
		## skip the rest
		exit speakAlert 
	end if
   
	try 
		## in case revSpeak isn't installed
		revSpeak pText
	catch theError 
		## if the "revSpeak" command fails
		## make a sound to get the user's attention
		put return & "(Cannot speak text on this system.)" after pText
		beep 
	end try
   
	## Display a dialog box
	answer pText
end speakAlert

If you want speech (or any similar action) to occur at the same time an answer dialog box is displayed, you need to perform the other action before using the answer command. This is because the answer command is blocking, it stops the handler until the user dismisses the dialog box, so if you use the revSpeak command after the answer command, the computer does not start speaking until after the user closes the dialog box.