Now that I've recovered from the pricing thing (we had 45 new customers getting in under the wire over the course of a couple days), I'm back to working on the release again. So here's another little example action, which is what this thread was kind of started for.
In this case, I've just copied it to the clipboard and pasted it here, to avoid having to paste a screen snap of the editor dialog every time:
Code:
1. // Speak the date and weather conditions
2. LocalVars::Set Variable(LVar:ToSay, Today is )
3. LocalVars::Append(LVar:ToSay, %(StdRTV:WeekDay))
4. LocalVars::Append(LVar:ToSay, , the )
5.
6. // Format the day number for correct speaking
7. System::Fmt Num As Spoken(%(StdRTV:DayNumber), LVar:DayNum)
8. LocalVars::Append(LVar:ToSay, %(LVar:DayNum))
9.
10. // Add the month
11. LocalVars::Append(LVar:ToSay, of %(StdRTV:Month).)
12.
13. // Add the conditions. The high can be invalid after 2pm
14. If Not System::Equals($(Weather.Day1High), 999)
15. LocalVars::Append(LVar:ToSay, Today's high will be )
16. LocalVars::Append(LVar:ToSay, $(Weather.Day1High))
17. End
18. LocalVars::Append(LVar:ToSay, . Current conditions are )
19. LocalVars::Append(LVar:ToSay, $(Weather.CurCondText))
20.
21. // And finally speak the text
22. System::Say Text(%(LVar:ToSay))
So this one will speak something like "Today is the fifth of June. Today's high will be 87. Current conditions are sunny". It takes into account that the current day high is invalid after 2pm from the weather channel feed and only speaks it if it's valid (the value is not 999.)
The lines are numbered, so I can comment on them by number
2. Settings a local variable called ToSay to the starting part of the text "Today is the ". Actions have local and global variables which are used to hold values as required. Locals just exist for the run of the action. Globals are shared. In some cases, globals aren't of much use, in other cases it's important to be able to leave some data around for subsequent use.
CQC actions are made up of targets, which implement commands that can be invoked, and those commands can take one or more parameters that are used while processing the command. The target is in the form XXX::, followed by the command name.
So "LocalVars::Set Variable", means invoke the Set Variable command on the LocalVars (local variables) target. There are a set of standard targets (system, macro engine, devices, local and global variables) that are always present. In some cases there are others, such as the graphical widgets in a user interface, or the incoming event in a triggered event. So the action system is flexible and 'pluggable' and can adapt to different situations easily.
3. Appends the weekday name. It uses a 'runtime value'. There are various runtime values, which are provided by the source. Above, targets were mentioned, which are the things that commands can be invoked on. The source is the thing invoking the commands. So it's something like a button on a user interface, or a key mapping that maps a keyboard key to an action, or an IR command mapping that maps an IR command to an action.
All sources provide a standard set of runtime values, like day of the week, host name, various current time formats, etc... But each type of source can provide special values that are just meaningful to it, for instance a slider on the graphical interface provides the current slider value, or the media category browser indicates the text of the category that was clicked on.
So when you do something like click the category browser, any action that is configured for it is invoked. That action is a set of commands to carry out against targets. So the source object you clicked is causing changes in the target objects you've configured it to change.
RTVs are indicated by a %(xxx) type replacement token. That token is replaced with the actual value of the runtime value as that action command step is executed.
Variables are treated like special runtime values also. So having set a local variable LVar:Bubba, you can then refer to the value of that variable as %(LVar:Bubba)
7. The "System::Fmt Num As Spoken" command is just a little helper that will take a value like 26 and format it out as "twenty sixth", which is useful for this type of TTS operation. So it doesn't say "the five of August" it says "the fifth of August".
14. Here it's checking whether the current day high value is valid. It's invoking a Not Equals command. The current day high value is a value from a device driver field, the weather channel device driver in this case. You refer to device values via a replacement token in the form $(device.field), and that token is replaced with the actual value of the field.
19. Here again the field access is used to get the value of the current condition field of the weather channel driver.