ROSA    Home  |  Docs  |  Support  |  Bugs  |  CVS  |  Downloads

ROSA enjoys a well-deserved retirement after serving thousands of users for several years.

Active development and maintenance of the ROSA Applet has ended with version 1.2.0. This website is maintained here only for reference for those still using ROSA and for the posterity.

ROSA Applet Parameters

Updated August 19, 2002

Following is the list of applet PARAMs and their meaning. Note that in this version of the applet, the parameter names are case-sensitive, but this may change in future version.

1. Main Image:

The main task of the applet is to display an image (GIF, JPEG or PNG) on which operations can be performed. The following parameters relate to this main image:


URL of the image (GIF, JPEG or PNG) to display in the applet.

ex: <PARAM NAME="IMG_URL" VALUE="/images/ttt.gif">

Note: Relative URLs such as "../images/ttt.gif" or "images/ttt.gif" and absolute URLs like "/images/ttt.gif" (on the same site) should all be supported.


(Optional) Use this to specify the position of the image in the applet. The value in the form "X,Y" is the requested position of the top-left of the image in pixel coordinates relative to the top-left corner of the applet.

The default is "0,0"

ex: <PARAM NAME="IMG_XY" VALUE="10,10">

(Optional) Background color to use for the applet.



2. User Inputs:

When the user performs a mouse drag or click on top of the image, the applet returns the user's input information through form parameters and then submits the form (if selected button is auto-submit). The communication between the Java applet and the HTML form is done through LiveConnect. Note that the form and the specified form parameters have to exist in the HTML document that holds the applet in order for the applet to be able to set them.

The following applet parameters are used to define the form parameters that will be set by the applet:


Name of the FORM in which parameters will be set based on the user's action. Note that the form MUST exist in the HTML page that holds the applet.

This parameter is optional. If it is not specified, then the first form in the page is used.


Name of the FORM parameter that will be set with the selected input type (i.e. point, rect, ellipse) at the time a submit is performed. The returned type value is defined by TB_BUT_name_INPUT parameter value of the button that is currently selected in the toolbar.


Name of the FORM parameter in which the coordinates of the user's input will be returned.

When the FORM is submitted, this form parameter's value will take one of the following forms, depending on the type of input that was performed. Note that all returned coordinates are in pixel units, with (0,0) at the top-left of the main image:

  • Point: "x,y". e.g. "12,34" for a point click at location (12,34) on top of the image.
  • Rect: "x1,y1;x2,y2" with (x1,y1) and (x2,y2) being the 2 opposite corners of the rectangle.
  • Ellipse: "x1,y1;x2,y2" with (x1,y1) and (x2,y2) being the 2 opposite corners of the ellipse's MBR.
  • Poly: "x1,y1;x2,y2;x3,y3..." contains one pair of (x,y) coordinates for each point digitized by the user.

Display message while the map image is being loaded into the Rosa applet. If this parameter is not provided, the default message will be "Loading map... Please wait."

ex: <PARAM NAME="LOADING_MSG" VALUE="New loading message">


3. Toolbar and Buttons:

The applet can have an optional toolbar. Buttons can also be placed anywhere inside the applet's area. The currently selected (i.e. pressed) button in the toolbar controls which type of input can be performed on top of the applet's main image (i.e. point, rectangle, ellipse, polygon.).

Buttons usually remain in their pressed state until another button is pressed. All buttons in the toolbar are mutually exclusive, this means that only one button can be in pressed state at any time.

The following parameters control the toolbar and buttons:


Position of the toolbar in the applet area. Value can be one of:

  • For a vertical toolbar: "left" or "right".
  • For a horizontal toolbar: "top" or "bottom"

This parameter is optional, the default is "right". Note that defining the absolute location of one (or more) button using the "TB_BUT_name_XY" parameter overrides the TB_POSITION setting for that button.


Alignment of the toolbar. Used in combination with TB_POSITION. Valid values are:

  • For a vertical toolbar: "top" (the default), "middle", or "bottom".
  • For a horizontal toolbar: "left" (the default), "center" or "right"
ex: <PARAM NAME="TB_ALIGN" VALUE="middle">

Contains the list of all the button names separated by "|" characters. These names are then used when looking for the "TB_BUT_?_*" button parameters below.

There is a special button name that can be used to define spaces between buttons: use "space_nn" to insert 'nn' pixels of space.

ex: <PARAM NAME="TB_BUTTONS" VALUE="query|space_05|zoomin|zoomout">

Name of the button that should be in pressed sate when the applet loads. This parameter is optional and the default is to have no button pressed.


URL of the image to use for the default state of the button. The same URL rules that apply to the "IMG_URL" parameter also apply to this one.

ex: <PARAM NAME="TB_BUT_query_IMG" VALUE="images/query.gif">

URL of the image to display when this button is in pressed state. This parameter is optional and the default behavior is to use the image passed in TB_BUT_?_IMG and change the look of the drop-shadow to give a pressed look to the button.

Users of round buttons (or other special buttons) should use this parameter in combination with the TB_BUT_?_BORDER parameter to disable the drop-shadow and fully control the look of a button.

ex: <PARAM NAME="TB_BUT_query_IMG_PR" VALUE="images/query_pressed.gif">

Use this optional parameter to specify the absolute position of the top-left corner of the button in the applet's area. The coordinates of the top-left corner of the button are passed in the form "x,y", in pixel units with (0,0) being the top-letf of the applet.

The default when TB_BUT_?_XY is not set is to follow the rules set by the TB_POSITION and TB_ALIGN parameters.

ex: <PARAM NAME="TB_BUT_query_XY" VALUE="25,25">

Width of the border (drop-shadow when the button is pressed) to draw around the button's image. The default is a 1 pixel border. Set this parameter to 0 to disable the automatic drop-shadow.


Hint text to display as a tool-tip label on top of the button when the mouse passes on top of the button. On systems where tool-tips cannot be supported, the hint text will be displayed in the browser's status bar. To make tool-tips on 2 or more lines use the "|" (without the quotes) inside the text as a separator. Example : zoom in : select this|tool to zoom in.

ex: <PARAM NAME="TB_BUT_query_HINT" VALUE="Query map information">

Type of action that can be performed on the main applet image when the button is pressed, one of:

  • "point" for single point click
  • "rect" to drag a rectangle
  • "ellipse" to drag an ellipse
  • "poly" to digitize a polyline

By default, the input is NOT auto-submit. To enable auto-submit, precede the action name with "auto_" (e.g. "auto_point", "auto_rect", etc.).

See also the INP_COORD_NAME parameter description. The user's input coordinates will be returned through the form parameter specified in that applet parameter.

In addition to the standard (point, rect, ellipse and poly) input types, a button can also be used to activate special client-side tools. When a button is used with one of the client-side tools, it does not set any of the form parameter values. There are currently 3 possible ones:

  • "dist" for the distance measurement tool
  • "legend" for the legend query tool
  • "submit" for a button that submits the page as soon as it is clicked, which implies no operation on the image

Note that auto-submit cannot be applied to the "dist" and "legend" tools since they do all their work on the client-side. These client-side tools are documented in more details in a separate section.

ex: <PARAM NAME="TB_BUT_query_INPUT" VALUE="auto_point">

Name of a form parameter to set to set when this button is pressed. The value to set has to be specified through the TB_BUT_?_VALUE.

Note that it is OK to have several buttons with the same TB_BUT_?_NAME but with a different TB_BUT_?_VALUE. This is actually the way most applications will work: using a single form parameter that always carries the status of the toolbar.

    <PARAM NAME="TB_BUT_query_VALUE" VALUE="query">

Specifies the value to set in the form parameter specified by TB_BUT_?_NAME when the button is pressed.


Target value to set on the form before submitting if this button triggers a submit.

Applies only to "auto_*" and "submit" button types.


JavaScript command to execute instead of submitting the form when this button would trigger a submit. Similar to an onSubmit FORM callback, except that the form is never submitted.

Applies only to "auto_*" and "submit" button types.


Specifies the cursor type when the button is selected. There are currently three cursor types defined :

  • "HAND"
  • "MOVE"


4. Distance Measurement Tool:

The applet has the ability to perform cumulative distance measurements by digitizing a polyline on the image when the following parameters are provided and one of the button's TB_BUT_?_INPUT is set to "dist".

Here is the way this tool works:

  • User selects the distance measurement button
  • As the user digitizes points on the map, a rubber-band polyline is drawn on top of the image
  • The cumulative distance, based on the PIXEL_SCALE parameter is displayed into the browser's status bar.
  • The measurement ends when the user hits ESC or selects another button in the applet.

Important Note: The map projection and the extents of the view have an impact on the precision of the measured distances, so this tool should be used with care and the measured distances should only be considered as approximations. It might be a good idea to include a note in your application's user documentation about that.

The following parameters control the measurement tool:


Pixel size in ground units. This value is used to convert the distance in pixels into a corresponding distance on the ground.


Printf-style format string to use to display the distance value. The string should contain a "%s" that will serve as a placeholder for the distance inside the string.

The default format when this parameter is not provided is "%s".

ex: <PARAM NAME="DIST_MSG" VALUE="Approximative distance: %s km">


5. Dynamic Legend Tool:

The Dynamic Legend Tool allows the user to click on a point on the image, and based on the color of the pixel that has been clicked, a search is made by the Java Applet in a lookup table and a legend label for this color is returned to the user.

Ideally, the label would be displayed as a Windows tool-tip, but if not possible, then the result goes in the task bar at the bottom of the window.

The Dynamic Legend tool is activated by a toolbar button whose TB_BUT_?_INPUT is set to "legend".

Important Note: This function currently works only with GIF images since they have a static color table. JPEG images use 24 bits colors and this is not supported yet.

Here is the way this tool works:

  • User selects the Dynamic Legend button
  • The user moves the mouse on top of the map and clicks at a location
  • The applet fetches the color of the pixel at the click location and displays a legend label that corresponds to that color in the legend's lookup table.
  • The tool can work for multiple legend queries, it is disabled when the user hits ESC or selects another button in the applet.

The following parameters control the Dynamic Legend tool:


A string containing one "color=label" entry for each legend entry, with "|" separators between each entry. This is turned into a lookup table internally.

The colors are specified as hexadecimal RGB values (RRGGBB)

ex: For a map with Blue Lakes and Rivers, Red Roads, and Black province boundaries, this parameter's value could be:

       VALUE="0000FF=Lakes and Rivers|
               000000=Province Boundaries">


6. Utility functions to update Rosa parameters:

Few utility functions have been added in Version 1.2 to be mainly able to update Rosa parameters from Javascript.

6.1 - SetImageURL

This function allows to send from Javascript to ROSA a new URL pointing to an image that will be loaded by the applet to update the current image displayed.

Example of use (assuming that the applet name in the HTML is RosaApplet)


6.2 - SetPixelSize

This function allows to set the "PIXEL_SIZE" parameter used with the distance measuring tool. Please refer to section 4 on how to use the measuring tool.

Example of use (assuming that the applet name in the HTML is RosaApplet)



Printer Friendly



ROSA Parameters



Contact Information

ROSA Users List