Custom Functions

It is possible to perform calculations on your data before it is displayed. RTView comes with an array of built-in, pre-defined “Function Types” or you can create your own Custom Functions. You can define functions in the Edit Function dialog and attach your objects to the results of these functions using the Attach to Function Data dialog.

Extend the functionality of RTView by creating your own custom functions. Just like built-in functions, they can be attached to any object or used as input to another function.

In order to implement your custom functions, you'll need to create, compile and deploy a custom function class as described below. See the javadocs for more information on the custom function API.

Creating a Custom Function Class

1.     Create a class named MyFunctionHandler that subclasses com.sl.gmsjrtview.GmsRtViewCustomFunctionHandler. RTView will create one instance of this class for each function in your application.

2.     Implement the getFunctionDescriptors() method to return a Vector of GmsRtViewFunctionDescriptors, one for each custom function in this class. For example:

public Vector getFunctionDescriptors ()

{

// vector of function descriptors

Vector<GmsRtViewFunctionDescriptor> v = new Vector<GmsRtViewFunctionDescriptor>();

// Round

GmsRtViewFunctionArgument roundArgs[] = new

GmsRtViewFunctionArgument[1];

roundArgs[0] = new GmsRtViewFunctionArgument("Value", GMS.G_DOUBLE);

v.addElement(new GmsRtViewFunctionDescriptor("Round",  roundArgs, GMS.G_INTEGER, null,

"This function rounds the value to the nearest integer.\n",

"This is the extended Help description.\n",false));

// return the vector full of functions

return v;

}

3.     Implement the get*Result method for each GmsRtViewFunctionDescriptor returned in getFunctionDescriptors(). Four return types are supported for custom functions and each has a corresponding callback method:

The get*Result method will get called once when the display containing the function is loaded and the function has received values for all of the arguments listed in the GmsRtViewFunctionDescriptor and again any time the argument values change.

The example in Step 2 returns a GMS.G_INTEGER, so for the Round function we’ll implement the getIntResult() method:

public int getIntResult (String functionName,

GmsRtViewFunctionDescriptor functionDesc,

GmsModelVariables functionIcon)

{

int ret = 0;

//--------------------------------------------

// Add an element to this if for each custom function

//--------------------------------------------

if (functionName.equals("Round")) {

double num = Double.NaN;

try {

// get the argument value via the descriptor

num = functionDesc.getArgDoubleValue("Value", functionIcon);

} catch (Exception e) {

// show error message, if argument not found

System.out.println(e.getMessage());

return 0;

}

// round to the nearest integer

ret = (int) Math.rint(num);

}

// return the result to the caller

return ret;

}

Compiling a Custom Function Class

Add the gmsjrtview.jar file, located in the lib directory (found in your installation directory,) to your classpath when you compile your MyFunctionHandler.java.

Deploying a Custom Function Class

The compiled MyFunctionHandler class must be included in the RTView classpath by adding it to the definition for the RTV_USERPATH environment variable.

Note: By default, RTView adds a jar named myclasses.jar in the directory where you start up to the classpath, so you can add your custom function class to the RTView classpath by including it in this jar.

Accessing a Custom Function in the Display Builder

Custom functions will be listed in the Edit Function dialog in the Function Type drop down menu below the built in functions. The custom function will be listed using the name you passed into the GmsRtViewFunctionDescriptor constructor. When you select a custom function from the Function Type list, the Edit Function dialog will update with one text entry field for each argument in the GmsRtViewFunctionDescriptor. The labels will display the names you passed into the GmsRtViewFunctionArgument constructor. The user can enter static values or attach any of the arguments to any available data source.

Limitation

Variables are assigned to function arguments in the order that the arguments are added. These variables are then saved to your display (.rtv) file when a functions is added to a display. Therefore, once you have created a display for a custom function, it will not be compatible with versions of the custom function where the argument order has changed.

Example: Adding a Custom Function to the Display Builder

These instructions will lead you through the process of adding a custom function to the Display Builder.

1.     In the demos directory (located in your installation directory), create a new directory and name it custom.

2.     In the custom directory, create a new file called MyFunctionHandler.java and paste the following information into that file:

import  java.util.*;

import  com.sl.gmsjrtview.*;

import  com.sl.gmsjrt.*;

public class MyFunctionHandler extends GmsRtViewCustomFunctionHandler

{

public Vector getFunctionDescriptors ()

{

// vector of function descriptors

Vector<GmsRtViewFunctionDescriptor> v = new Vector<GmsRtViewFunctionDescriptor>();

// Round

GmsRtViewFunctionArgument roundArgs[] = new

GmsRtViewFunctionArgument[1];

roundArgs[0] = new GmsRtViewFunctionArgument("Value", GMS.G_DOUBLE);

v.addElement(new GmsRtViewFunctionDescriptor("Round",  roundArgs, GMS.G_INTEGER, null,

"This function rounds the value to the nearest integer.\n",

"This is the extended Help description.\n",false));

// return the vector full of functions

return v;

}

public int getIntResult (String functionName,

GmsRtViewFunctionDescriptor functionDesc,

GmsModelVariables functionIcon)

{

int ret = 0;

//--------------------------------------------

// Add an element to this if for each custom function

//--------------------------------------------

if (functionName.equals("Round")) {

double num = Double.NaN;

try {

// get the argument value via the descriptor

num = functionDesc.getArgDoubleValue("Value", functionIcon);

} catch (Exception e) {

// show error message, if argument not found

System.out.println(e.getMessage());

return 0;

}

// round to the nearest integer

ret = (int) Math.rint(num);

}

// return the result to the caller

return ret;

}

}

3.     In the custom directory, create a new batch file named make_function.bat and paste the following into that file:

javac -classpath .;"%RTV_HOME%/lib/gmsjrtview.jar" MyFunctionHandler.java

jar -cf myclasses.jar MyFunctionHandler.class

4.     In an initialized command window, go to demos\custom and type:

run make_function

The files MyFunctionHandler.class and myclasses.jar should now appear in the custom directory.

5.     Add myclasses.jar to the “RTV_USERPATH” environment variable.

6.     Type:

run_builder.

7.     In the Display Builder, select Tools>Functions and then click Add to open the Edit Function dialog.

8.     The custom function you added (Round) should now appear in the Function Type drop down menu.