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, PNG) on which operations
can be performed. The following parameters relate to this main image:
IMG_URL |
URL of
the image (GIF or JPEG) 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">
|
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. If
not provided, the value will be set to 1.0;
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>
.....
|