RUCAPI Reference

Key Concepts

All RUCs share a common region of interest (ROI). When the the ROI is changed by one component, all the other components are automatically notified of the change.

We define a web application as a single web page that uses one or more RUCs. For most web applications, the application can simply read the values in the Bounding Box component fields to get the current ROI.

If your application is not using the Bounding Box component or you simply need greater control over ROI behaviour, you can use the functions contained in the RUCAPI.

Example 1:

If you want your application to be notified whenever another component changes the ROI, include JavaScript in your page similar to the following:

function yourROICallback( compName, north, south, west, east )
{
  alert( 'New west value: ' + west );
}
. . .
RUC_AddROIHandler( "yourApplicationName", yourROICallback );

Here, "yourApplicationName" is an arbitrary string that you define to identify your application to the RUCAPI. It is used in the case where your application also uses the RUC_changeROI() function (see Example 3 below). If you call RUC_changeROI() with "yourApplicationName" then yourROICallback will not be called. This is to avoid an infinite loop in the case where a call to RUC_changeROI() is placed within the callback function.

Example 2:

It is possible for your application to be sent null or NaN (not a number) values when another component changes the ROI. The JavaScript in your page should be able to handle such an event. To do this include JavaScript in your page similar to the following:

function yourROICallback( compName, north, south, west, east )
{
  if ((north eq "") || (south eq "") || (east eq "") ||
      (west eq "") || ((isNaN(north)) || (isNaN(south)) ||
      (isNaN(east)) || (isNaN(west)))
  {
    alert( 'Invalid coord value found' );
  }
  else
  {
    alert( 'New west value: ' + west );
  }
}
. . .
RUC_AddROIHandler( "yourApplicationName", yourROICallback );

Example 3:

If you want your application to change the ROI based on some application specific event, include JavaScript in your page similar to the following:

function yourROIChangingEvent()
{
  RUC_changeROI( "yourApplicationName", lat1, lon1, lat2, lon2, . . . );
}

RUC_changeROI() Definition

RUC_changeROI( compName, lat1, lon1, lat2, lon2,..., latn, lonn )

Notifies all other components that the ROI boundary has changed to the rectangular box bounding the set of input co-ordinates. If the lat/lon values are strings - i.e. "abc" no notifications will take place.

Parameters	compName A string identifying the component initiating the ROI change. lati, loni A set of latitude/longitude coordinates inside the ROI. It is possible for these values to be null - e.g. "".
Callbacks Invoked	All functions registered via RUC_AddROIHandler() whose component name does not match compName will be called with the rectangular bounding box of the set of input co-ordinates.
Example	RUC_changeROI( "yourApp", 49, -120, 51, -118 );

RUC_AddROIHandler Definition

RUC_AddROIHandler( compName, handlingFunc )

Tells the RUCAPI that this application/component wants to be notified when the ROI changes. handlingFunc will only be called when the compName passed to RUC_changeROI() does not match the compName passed to RUC_AddROIHandler().  This is to prevent an endless loop of notifications.

Note that the handlingFunc does not receive the set of co-ordinates as passed in to RUC_changeROI() but rather the bounding rectangle of that set of co-ordinates.

Parameters	compName A string identifying the component requesting to be notified when the ROI changes handlingFunc User defined function to be called when the ROI changes.  This function must be of the form handlingFunc( compName, north, south, west, east ) and be able to handle null and NaN (not a number) values.
Callbacks Invoked	None.
Example	function yourHandlingFunc( compName, north, south, west, east ) { ... } ... RUC_AddROIHandler( "yourApp", yourHandlingFunc )