Call an Ovation Pro function
CallOPro provides a simple way to call an Ovation Pro script language function from an external task. The function can be either one of the built-in functions or one provided by an additional applet. This allows an external task to 'control' an applet, perhaps to wake-up the applet to start an event or maybe to pass it some data by calling a function that requires that data as a parameter.
How it works
CallOPro is a small stand-alone application that takes a text string passed to it on the command line. This string takes the form of the Ovation Pro function to be called. It is wrapped it up in a main() function, as if it was a small executable Ovation Pro scrip language file in memory. It is then sent (or rather, saved) to Ovation Pro using a Message_RAMTransmit message (part of the Data transfer protocol). Ovation Pro receives this as if the script file had been dragged to its iconbar icon. Upon which the script file is executed by Ovation Pro, thereby calling the function.
How you run CallOPro depends upon the type of program/environment you are calling it from - it mainly depends on whether or not you are using it from a multitasking application. The different methods of using it are fully outlined below, but in general it is simply a matter of passing the Ovation Pro function(s) you wish to call to CallOPro like so:
CallOPro will automatically add a semicolon to the end of the string supplied if it does not already have one, but if you are calling more than one function then they should be separated by a semicolon as you would normally do when using the Ovation Pro script language, eg: CallOPro function1();function
Note: In previous releases of CallOPro (prior to version 1.03) no path variables were set up and you had to run the CallOPro program by including a full filepath to its stored location. This has now changed as I decided it would be easier to use if some system variables were preset. As long as the CallOPro application has been seen by the filer (Filer_Booted) then the system variables will become active. This also means that single version of !CallOPro could be placed alongside the Ovation Pro transloaders or even in !Boot.Resources and be readily available whenever needed.
Ways to use CallOPro
CallOPro sets some alias *command style system variables that provides a simple way to use it from different environments, as well as setting a system variable to point to it's file location to aid in running the from other programs.
Below I've listed some examples of different ways to use CallOpro depending upon where you are using it.
Further Notes on using CallOPro
CallOPro is not restricted to calling just one function, but you must make sure to include a semicolon after each function as CallOPro can only add one to the end of the string (if the string needs one). Remember that CallOPro wraps up the string supplied to it in a main() function to produce a standard Ovation Pro script file.
For example, if you pass snaptogrid();type("hello world!") as the string, CallOPro takes the string and adds a semicolon to the end, because it does not already have one. It then wraps it up in a main() function and sends it to Ovation Pro. The script file that Ovation Pro receives is as follows:
This would snap the selected object to the grid (if it can be), and type the text 'hello world' at the current caret position. Note that the type() function enters the string at the current caret position, so this example would only work if a document is open with the caret in a text object.
Firstly, the Data transfer protocol message is only passed to Ovation Pro's iconbar icon, not to any open document windows. So specifying which document view receives the function call is not possible.
Secondly, the length of the string that can be passed to CallOPro is limited by the maximum allowed length of the command line. As the full path to CallOPro is also included in the command line string when it is run, the actual length left for the functions you are calling is dependent upon the length of CallOPro's pathname and which version of RISC OS is being used. If a lot of data needs to be passed to Ovation Pro then the !SendOPro utility should be used - this does a similar job but instead of passing the data in memory, it sends a file on disc to Ovation Pro.
Why use CallOPro
CallOPro is intended to be a simple 'helper' app. If your external code runs as a full task by registering with the WIMP itself then it is probably better to handle the whole transfer protocol yourself. But if you just need to add the facility to some simple code or an Obey file then using CallOPro will allow you to send data to Ovation Pro in an easy way without you having to write the transfer methods yourself.
Should you wish to implement this transfer method in your own task then this is a more detailed description of what happens.
CallOPro takes the command line string tail and adds a semicolon to the end if the string doesn't already have one. It then finds the task handle of Ovation Pro, and checks through the icons on the iconbar until it finds the one belonging to Ovation Pro. Now it has a window and icon pair to send a message to (the window is -2 for the icon bar, the icon is the one it just found on the iconbar). After wrapping up the command string in a main() function, CallOPro next sends a DataSave message to Ovation Pro's iconbar icon, to which Ovation Pro responds with a RAMFetch message. Upon receiving the RAMFetch message, CallOPro transfers the data to Ovation Pro and quits.
Runs on RISC OS