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:
IMG_URL-
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.
IMG_XY-
(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">
BG_COLOR-
(Optional)
Background color to use for the applet.
ex: <PARAM NAME="BG_COLOR" VALUE="#FFFFFF">
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:
INP_FORM_NAME-
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.
ex: <PARAM NAME="INP_FORM_NAME" VALUE="MY_FORM">
INP_TYPE_NAME-
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.
ex: <PARAM NAME="INP_TYPE_NAME" VALUE="INPUT_TYPE">
INP_COORD_NAME-
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.
ex: <PARAM NAME="INP_COORD_NAME" VALUE="INPUT_COORD">
LOADING_MSG-
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:
TB_POSITION-
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.
ex: <PARAM NAME="TB_POSITION" VALUE="left">
TB_ALIGN-
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">
TB_BUTTONS-
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">
TB_SELECTED_BUTTON-
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.
ex: <PARAM NAME="TB_SELECTED_BUTTON" VALUE="zoomin">
TB_BUT_?_IMG-
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">
TB_BUT_?_IMG_PR-
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">
TB_BUT_?_XY-
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">
TB_BUT_?_BORDER-
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.
ex: <PARAM NAME="TB_BUT_query_BORDER" VALUE="0">
TB_BUT_?_HINT-
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">
TB_BUT_?_INPUT-
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">
TB_BUT_?_NAME-
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.
ex:
<PARAM NAME="TB_BUT_query_NAME" VALUE="ACTION">
<PARAM NAME="TB_BUT_query_VALUE" VALUE="query">
TB_BUT_?_VALUE-
Specifies
the value to set in the form parameter specified by TB_BUT_?_NAME
when the button is pressed.
TB_BUT_?_TARGET-
Target value to set on the form
before submitting if this button triggers a submit.
Applies only to "auto_*" and "submit" button types.
TB_BUT_?_JSACTION-
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.
TB_BUT_?_CURSOR_TYPE-
Specifies the cursor type when the
button is selected. There are currently three cursor types defined :
- "CROSSHAIR"
- "HAND"
- "MOVE"
ex: <PARAM NAME="TB_BUT_query_CURSOR_TYPE" VALUE="CROSSHAIR">
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-
Pixel
size in ground units. This value is used to convert the distance
in pixels into a corresponding distance on the ground.
ex: <PARAM NAME="PIXEL_SIZE" VALUE="100000">
DIST_MSG-
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:
DYN_LEGEND-
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:
<PARAM NAME="DYN_LEGEND"
VALUE="0000FF=Lakes and Rivers|
FF0000=Roads|
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)
<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
document.RosaApplet.SetImageURL("/ms_tmp/newimage.png");
</SCRIPT>
.....
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)
<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
document.RosaApplet.SetPixelSize(2000);
</SCRIPT>
.....
|
