Getting Started with Tool Programming
Introduction
The Optuma custom tool programming allows users to code their own tools and functions to be used in the program. This module is included with an Optuma Enterprise Services subscription. Other clients may purchase it as an add-on module from the Tool Store.
The scripting language is based on Pascal which is easy to use and understand and is widely known. The syntax of the scripting language is outlined here.
If you have any specific questions these can be posted to the Developers Forum. Click here and log in with your Optuma username and password.
The programming functionality can be used to write a tool to apply to a chart or a function which can be used in scanning and backtesting.
Creating a Custom Tool
- To start coding a custom tool do the following steps
- First open Optuma and open a bar or candle chart.
- Click on the New menu button and select Custom Tool from the list:
- Enter the Tool Name - this should be a unique name 6. Enter Tool Hint - this text will show when the mouse is over the tool 7. Choose the Tool Type
Drawing: This is a tool that is drawn on the chart (such as a trend line or a rectangle)
Data List: This is a list tool that overlays over the chart (such as a moving average)
Data View: This is a list tool that displays in its own view below the chart (such as a MACD)
Note: when creating a Drawing tool type, the Mouse Clicks option will appear. This is the number of mouse clicksneeded to apply the tool. For example if the tool was like a trend line it would require two clicks to apply, but if the tool was a triangle it would require three clicks to apply.
Coding a Custom Tool
The window below will open when creating a custom tool is the Custom Tool Editor.
To open the Custom Tool editor Editor apply the script tool and click the “Edit Tool Code” action in the properties panel.
All the programming for the custom tool is done in this window.
There are three main procedures:
DefineTool
This is used to define the information about the tool. The Tool input parameter is the custom tool you are developing.
Tool.Name: This is the displayed name of the tool
Tool.Key: This is permission key for the tool and controls who can use the custom tool. (do not change this key unless an alternative key is provided by Optuma)
Tool.MouseClicks: This the number of mouse clicks used to apply the tool. E.g. a trend line would need two clicks to apply the tool the start and the end of the trend line, while a moving average tool would only need 1 click.
Tool.ToolType: this defines whether the tool is a drawing tool(ttDrawing) or overlays the data (ttDataList) or is displayed in a new view (ttDataView)
Init
This procedure is called once when the tool is applied. It is used to initialise the tool. By default a Plot variable is added to the tool and some of its properties are set. The Tool input parameter is the custom tool you are developing.
To add a drawing item to a tool, use the Add… function for the Tool. E.g. Tool.AddPlot().
Drawing Items
Drawing items are objects that are drawn on the chart as part of your custom tool. The following lists all the drawing items that can be added to a tool.
function AddPlot(sFormula : String = '') : TPlot;
function AddSelectionPoint(bVisible : Boolean): TSelectionPoint;
function AddLine() : TLine;
function AddHLine(rPrice : Double) : TLine;
function AddVLine(dtDate : TDateTime) : TLine;
function AddRectangle() : TRectangle;
function Add2DSymbols() : T2DSymbols;
function AddSymbols() : TSymbols;
function AddEvents() : TEvents;
function AddPriceLevels() : TPriceLevels;
function AddText(sText : String; dtDate : TDateTime; rPrice : Double) : TText;
function AddEphemeris() : TEphemeris;
For more information on the drawing items see Drawing Items
Helper Objects
Helper Objects are used to help the developer retrieve data and perform operation without drawing anything on the chart. For more information on helper objects see Helper Objects
Tool Properties
A custom tool can have custom properties that are shown in the properties panel and can be set by the user and used in the programming of the tool. To add a custom property, call the Add.. function on a tool E.g. Tool.AddBoolean(). The following lists the Tool Properties that can be added to a tool.
function AddBoolean(sName, sCaption : String; bDefault : Boolean) : TBooleanProperty; function AddInteger(sName, sCaption : String; iDefault : Integer) : TIntegerProperty;
For more information on the tool properties, items see Tool Properties.
Process
The process procedure is called every time new data is received by the tool and also every time the tool is moved by the mouse. The procedure has four input parameters
Tool: This is the custom tool you are developing.
ProcessStart: This is the start index into the DataIn Datalist (The DataIn index starts at 0). When processing the tool for the first time the value of ProcessStart will be 0. When processing a new bar from a tick on a live data chart, the value of ProcessStart will be the length-1 of the DataIn. This allows efficient processing of fast ticking live charts, because depending on the tool, when a new bar is processed whole datalist does not always need to be reprocessed.
ProcessEnd: This is the end index into the DataIn DataList. This value will always be the length-1 of the datalist.
DataIn: This is the input data for the Tool, it will normally be the datalist of the chart to which the tool is applied. E.g if the tool is applied to the DJI chart, then the DataIn will be an array of the DJI data.
Process for a Data List Tool
The following example is when creating a data list tool, like a moving average. The main objective being to create an output plot with the new plot data (Plot 1 in this example). As show in the default code, To access the data in the DataIn, it is common to loop through the datalist from ProcessStart to ProcessEnd indexing the Bar property.
procedure Process(Tool : TTool; ProcessStart : Integer; ProcessEnd : Integer; DataIn : TDataList);
var i, iIndex : Integer;
begin
for i := ProcessStart to ProcessEnd do
begin
Plot1.Row\[i\].Date := DataIn.Row\[i\].Date;
Plot1.Row\[i\].Open := DataIn.Row\[i\].Open;
Plot1.Row\[i\].High := DataIn.Row\[i\].High;
Plot1.Row\[i\].Low := DataIn.Row\[i\].Low;
Plot1.Row\[i\].Close := DataIn.Row\[i\].Close;
Plot1.Row\[i\].Hidden := False;
end;
// To retrieve an index from a date use the DateToIndex function
iIndex := DataIn.DateToIndex(now())
end;
The following lists all the DataIn.Row properties
DataIn.Row\[i\].Date
DataIn.Row\[i\].Open
DataIn.Row\[i\].High
DataIn.Row\[i\].Low
DataIn.Row\[i\].Close
DataIn.Row\[i\].Volume
DataIn.Row\[i\].OI
DataIn.Row\[i\].BarType
DataIn.Row\[i\].HighTime
DataIn.Row\[i\].LowTime
DataIn.Row\[i\].Hidden
Process for a Drawing Tool
The following example is when creating a Drawing tool, like a trend line. The main objective being to create lines joining selection points. When adding a drawing tool, the user will click to apply the tool. These clicks are called selection points. To access the selection points use the Tool.MP array where Tool.MP[0] represents the first selection point and Tool.MP[1] represents the second selection point. Each selection point has three proerties Date, Price and Idx.
To link a line to the selection points you need to set the date and price of the end points of the line to the selection points, as shown in the example below.
var Line1 : TLine;
procedure DefineTool(Tool : TTool);
begin
Tool.Name := 'MyLine';
Tool.Key := '1BD3D3CC-F5AB-4AAE-9AD0-77333DBD5E20';
Tool.MouseClicks := 2;
Tool.ToolType := ttDrawing;
end;
procedure Init(Tool : TTool);
begin
Line1 := Tool.AddLine();
Line1.Color := clRed;
Line1.Width := 7;
Line1.Style := DotDot;
Line1.Transparency := 100;
end;
procedure Process(Tool : TTool; ProcessStart : Integer; ProcessEnd : Integer; DataIn : TDataList);
begin
Line1.P1.Date := Tool.MP\[0\].Date;
// Assign the date of the selection point to the first point of Line1.
Line1.P1.Price := Tool.MP\[0\].Price;
// Assign the price of the selection point to the first point of Line1.
Line1.P2.Date := Tool.MP\[1\].Date;
Line1.P2.Price := Tool.MP\[1\].Price;
end;
Testing The Tool
If a chart is open when creating a custom tool, the tool is automatically applied to the chart. After making change to the code, to see the tool update with the changes click on the save button on the Optuma scripting editor (first tool button on the left). This will save the script and also update the tool on the chart.
Once programming of the tool is complete, close the Scripting editor by clicking the red cross at the top right. To bring the Scripting editor back then click the Show IDE action in the properties panel after selecting the custom tool by left clicking the tool on the chart.
Once the tool has been saved it will appear in the normal tool list and can be applied just like any other tool.
Debugging The Tool
To output messages to the screen, use the following two functions. These will display the message in the bottom right status window/
// this will display message for 10 seconds
DisplayMessage('My Title', 'My Msg' 10);
// this will display the message for default 3 seconds
Print('My Msg');
To keep track of these messages and to view past messages you can use the debug view program dbgview.exe which will display all debug messages. It can be download from here