Programming Guide
The Script Folder
Scenario creates a folder in your personal Library which contains a subfolder for each type of action. Simply drop any AppleScript in the appropriate folder and it will run if that type of action is turned on in Scenario.
Scripts have to be regular AppleScript documents with the extension «scpt» to work.
This is also where you can find scripts to test if everything is running properly, and some Sample Scripts to get you acquiainted with writing AppleScripts which work with Scenario.
Scenario creates a folder in your personal Library which contains a subfolder for each type of action. Simply drop any AppleScript in the appropriate folder and it will run if that type of action is turned on in Scenario.
Scripts have to be regular AppleScript documents with the extension «scpt» to work.
This is also where you can find scripts to test if everything is running properly, and some Sample Scripts to get you acquiainted with writing AppleScripts which work with Scenario.
Log-in Scripts
Let’s start with something easy. There is no special consideration when running scripts at Log-in. Have at it.
Log-out Scripts
When you activate Log-out scripts, there are two important things which will happen. The first is cosmetic: Mac OS X cannot let a faceless background application know when the user will log-out and allow the application to delay the log-out. Thus, Scenario cannot remain a background application and still ensure that all your scripts are run before you are logged-out. In order to allow Scenario to work correctly, we must make it visible in the Dock when you decide to use Log-out scripts. This way, Scenario can check that all your scripts have run before allowing the system to log-out. If your scripts fail, you will not be logged out.
In order for Scenario to allow you to log-out, your script must return a specific code to Scenario to let it know that everything is ok and that the System can log-out.
Here is our sample log-out script so you can see how this works:
set theResult to button returned of (display dialog "Are you certain you want to log-out?" buttons {"No", "Yes"} default button 2)
if theResult is "Yes" then
error "MCScenarioReadyToGo"
end if
As you can see, when we want to allow the Log-out procedure to complete correctly, we return a special error code (MCScenarioReadyToGo) which tells Scenario to allow the Log-out to happen. Otherwise you will get a dialog stating that Scenario has canceled Log-out.
So it is very important that you verify that your script returns this value when it runs correctly and if not, to make the user aware of why they have not been logged out.
Why an error?
This is simply the only mechanism which we have access to to return a message to Scenario.
Sleep Scripts
Sleep Scripts are launched right before the computer goes to sleep. Again, there are some important caveats with this type of script.
When your computer goes to sleep, each program gets asked if it is ok to go to sleep and if not, the program gets a few seconds before they are forced to sleep. This way, no program can stop the computer from going to sleep and thus drain the battery and possibly create data loss.
The way Scenario deals with Sleep scripts is that it does not reply when the system asks it to sleep until all the scripts return that they are ready. This means your scripts must return a special error code the same way Log-out scripts do.
If Scenario does not reply to the System that it is ready, the System will put the computer to sleep anyway. This happens after a few seconds (about 15). So whether your script replies that it is done or not, the computer will go to sleep anyway.
The difference between Sleep scripts and Log-out scripts is that Log-out scripts can cancel Log-out altogether, but Sleep scripts can only delay sleep from happening. This means that if your script takes too much time to run, it will be interrupted and the computer will go to sleep.
This also means that if your script does not reply when it is done, your computer will wait until the default time out happens (15 seconds) which will add an unnecessary delay before Sleep occurs.
You can use the following script example as a way to understand how to program Sleep scripts which return the correct value so the computer can actually go to sleep before the 15 second time-out.
if button returned of (display dialog "This computer will go to sleep in less than 15 seconds or when you click this button, which ever comes first." buttons {"Wait until time out", "Sleep Now"} default button 2) is "Sleep Now" then
error "MCScenarioReadyToGo"
end if
Idle Scripts
You can configure Scenario to launch some scripts after a certain period of inactivity. Inactivity being defined as absence of mouse movement and keystrokes. Background processes do not count.
You can trigger scripts either after a set period of inactivity, or when your computer is no longer idle, when you start typing or move the mouse.
Our sample script for Idle actions sets your iChat AV Status from your normal status to “On the phone…” when the idle period is reached and sets it to what it was before when activity resumes.
The sample code is useful to see how we handle states between scripts as the way we launch scripts does not support AppleScript properties across launches.
He is the sample code from our Idle Start Script:
(* iChat Status Script 1.0 *)
(* This simple script stored the current iChat AV status message (if online) and replaces it with an idle message, in this case "On the phone" and back again the next time it is launched. Used with Scenario's Idle Script launching, it can be an indicator of what you are doing and if you are available... it could also be toggled by the Hot Key if you like... *)
property iChatIdleMessage : "On the phone…"
set theScript to "cat /tmp/mcScenarioiChatStatus"
try
set theStatus to do shell script "cat /tmp/mcScenarioiChatStatus"
on error
do shell script "echo 'not idle' > /tmp/mcScenarioiChatStatus"
set theStatus to "not idle"
end try
if theStatus is "not idle" then
-- Becoming idle, set the iChat status to idle
tell application "iChat"
-- store previous message, we'd use properties but it seems that launching script from within Cocoa doesn't allow properties to be preserved
do shell script ("echo " & status message & " > /tmp/mcScenarioiChatMessage")
set status message to my iChatIdleMessage
end tell
do shell script "echo 'idle' > /tmp/mcScenarioiChatStatus"
else
-- Becoming active, restore previous message
tell application "iChat"
set status message to (do shell script "cat /tmp/mcScenarioiChatMessage")
end tell
do shell script "echo 'not idle' > /tmp/mcScenarioiChatStatus"
end if
You will notice that we are saving the current iChat status and message in a temporary file in the /tmp folder of the computer. Normally, one could use script properties to keep the information inside the compiled script, but when launching scripts from within a Cocoa application, properties are not preserved, so we need to store this information in a file.
You can then place this script in your Idle Start Scripts folder and make an alias of it in the Idle End folder and it will toggle your iChat status.
There are no other special considerations when writing Idle Scripts.
Other notes of interest
Since Mac OS X 10.4.x, Scenario has not been able to launch scripts which require user interaction in the background. Versions 1.03 and later will display an error if you attempt this. In order to use Display Dialog or such features, you will need to include these commands within a Tell statement to the Finder or another application.
Let’s start with something easy. There is no special consideration when running scripts at Log-in. Have at it.
Log-out Scripts
When you activate Log-out scripts, there are two important things which will happen. The first is cosmetic: Mac OS X cannot let a faceless background application know when the user will log-out and allow the application to delay the log-out. Thus, Scenario cannot remain a background application and still ensure that all your scripts are run before you are logged-out. In order to allow Scenario to work correctly, we must make it visible in the Dock when you decide to use Log-out scripts. This way, Scenario can check that all your scripts have run before allowing the system to log-out. If your scripts fail, you will not be logged out.
In order for Scenario to allow you to log-out, your script must return a specific code to Scenario to let it know that everything is ok and that the System can log-out.
Here is our sample log-out script so you can see how this works:
set theResult to button returned of (display dialog "Are you certain you want to log-out?" buttons {"No", "Yes"} default button 2)
if theResult is "Yes" then
error "MCScenarioReadyToGo"
end if
As you can see, when we want to allow the Log-out procedure to complete correctly, we return a special error code (MCScenarioReadyToGo) which tells Scenario to allow the Log-out to happen. Otherwise you will get a dialog stating that Scenario has canceled Log-out.
So it is very important that you verify that your script returns this value when it runs correctly and if not, to make the user aware of why they have not been logged out.
Why an error?
This is simply the only mechanism which we have access to to return a message to Scenario.
Sleep Scripts
Sleep Scripts are launched right before the computer goes to sleep. Again, there are some important caveats with this type of script.
When your computer goes to sleep, each program gets asked if it is ok to go to sleep and if not, the program gets a few seconds before they are forced to sleep. This way, no program can stop the computer from going to sleep and thus drain the battery and possibly create data loss.
The way Scenario deals with Sleep scripts is that it does not reply when the system asks it to sleep until all the scripts return that they are ready. This means your scripts must return a special error code the same way Log-out scripts do.
If Scenario does not reply to the System that it is ready, the System will put the computer to sleep anyway. This happens after a few seconds (about 15). So whether your script replies that it is done or not, the computer will go to sleep anyway.
The difference between Sleep scripts and Log-out scripts is that Log-out scripts can cancel Log-out altogether, but Sleep scripts can only delay sleep from happening. This means that if your script takes too much time to run, it will be interrupted and the computer will go to sleep.
This also means that if your script does not reply when it is done, your computer will wait until the default time out happens (15 seconds) which will add an unnecessary delay before Sleep occurs.
You can use the following script example as a way to understand how to program Sleep scripts which return the correct value so the computer can actually go to sleep before the 15 second time-out.
if button returned of (display dialog "This computer will go to sleep in less than 15 seconds or when you click this button, which ever comes first." buttons {"Wait until time out", "Sleep Now"} default button 2) is "Sleep Now" then
error "MCScenarioReadyToGo"
end if
Idle Scripts
You can configure Scenario to launch some scripts after a certain period of inactivity. Inactivity being defined as absence of mouse movement and keystrokes. Background processes do not count.
You can trigger scripts either after a set period of inactivity, or when your computer is no longer idle, when you start typing or move the mouse.
Our sample script for Idle actions sets your iChat AV Status from your normal status to “On the phone…” when the idle period is reached and sets it to what it was before when activity resumes.
The sample code is useful to see how we handle states between scripts as the way we launch scripts does not support AppleScript properties across launches.
He is the sample code from our Idle Start Script:
(* iChat Status Script 1.0 *)
(* This simple script stored the current iChat AV status message (if online) and replaces it with an idle message, in this case "On the phone" and back again the next time it is launched. Used with Scenario's Idle Script launching, it can be an indicator of what you are doing and if you are available... it could also be toggled by the Hot Key if you like... *)
property iChatIdleMessage : "On the phone…"
set theScript to "cat /tmp/mcScenarioiChatStatus"
try
set theStatus to do shell script "cat /tmp/mcScenarioiChatStatus"
on error
do shell script "echo 'not idle' > /tmp/mcScenarioiChatStatus"
set theStatus to "not idle"
end try
if theStatus is "not idle" then
-- Becoming idle, set the iChat status to idle
tell application "iChat"
-- store previous message, we'd use properties but it seems that launching script from within Cocoa doesn't allow properties to be preserved
do shell script ("echo " & status message & " > /tmp/mcScenarioiChatMessage")
set status message to my iChatIdleMessage
end tell
do shell script "echo 'idle' > /tmp/mcScenarioiChatStatus"
else
-- Becoming active, restore previous message
tell application "iChat"
set status message to (do shell script "cat /tmp/mcScenarioiChatMessage")
end tell
do shell script "echo 'not idle' > /tmp/mcScenarioiChatStatus"
end if
You will notice that we are saving the current iChat status and message in a temporary file in the /tmp folder of the computer. Normally, one could use script properties to keep the information inside the compiled script, but when launching scripts from within a Cocoa application, properties are not preserved, so we need to store this information in a file.
You can then place this script in your Idle Start Scripts folder and make an alias of it in the Idle End folder and it will toggle your iChat status.
There are no other special considerations when writing Idle Scripts.
Other notes of interest
Since Mac OS X 10.4.x, Scenario has not been able to launch scripts which require user interaction in the background. Versions 1.03 and later will display an error if you attempt this. In order to use Display Dialog or such features, you will need to include these commands within a Tell statement to the Finder or another application.
