fillstyle = 0 = NONE , 1= solid, 3= H_BIDIAGONAL, 4 = H_CROSS, 5= H_DIAGCROSS, 6 = H_FDIAGONAL, 7 = H_HORIZONTAL, 8 = H_VERTICAL (fillstyle = 2 is not used and implies NONE)Fig. II.1 Fill Styles
FS001 Feature Selection and Query
There are four functions to initiate a user-driven feature selection, as shown in the following table:
CLIENT\SERVER INTERACTION
SELECTION APPROACH
Pick Aperture
Selection Rectangle
One-way-comm
selectSingleFeature
selectFeatureCollection
Two-way-comm
setSelectSingleFeature
setSelectFeatureCollection
All four methods take a string argument that specifies a constraining feature code. This constraining feature code can contain one or two wild card characters (see Section II-6). All four methods also set up the state of SDM to perform user-directed selection, via mouse, on an SDM graphic window. For the pick-aperture methods, the mouse click changes the cursor to a small box with cross-hairs (the pick-aperture). The visible feature nearest the center of the box (at the cross-hairs) when the mouse button is released is selected (if its feature code matches the given string argument including possible wild cards). The selection-rectangle methods allow the user to click and drag a rectangle of any size. Each visible feature that is contained within the rectangle when the mouse button is released is selected (if its feature code matches the given string argument). Selected features are highlighted in the current selection color. (The default selection color is red. It can be modified via the method setSelectionColor.) Features of any type (i.e., point, labeled point, line, closed shape) can be selected.
If the one-way-comm methods are used, it is the Client's responsibility to poll the server, via the method isOpComplete, which returns TRUE when the selection operation is complete. The Client can then determine whether a valid selection has been made, via the method getStatus. The latter returns TRUE, if a valid selection has been made.
If the two-way-comm methods are used, the Server notifies the Client (via the method receiveSelectionStatus), when the selection operation is complete. The method's argument contains the same status which would otherwise be obtained via getStatus. To use the two-way-comm methods, the Client must "expose" the receiveSelectionStatus method.
Once the Client has determined that a valid selection has been made, by any of the four methods above, the Client can query the selected features as follows:
- Obtain the list of CARIS keys associated with the selected features, via the method getKeys.
- Parse the list to derive an array of keys.
- Obtain the properties of any feature in the list, using one of two methods: either querySelectionByKey or querySelectionByIndex.
The former can be used only for features where the key exists and is unique. The latter can be used any time. For further details, see the individual method descriptions below.
FS001-1 setSelectFeatCode
void setSelectFeatCode(string fcode)
where fcode is a Feature Code specified by the Client.
This two-way (asynchronous) method sets up the state of SDM to accept a user’s mouse click on an SDM graphic window. When the user clicks on or near a feature (e.g. symbol), SDM will search for a feature with the given feature code, fcode, within an effective area (e.g. the size of the pick aperture). After the user clicks, SDM goes back to its neutral state, and method C-001 (receiveSelectedFeature, please refer to the Client Side Methods) on the client side is called.
FS001-1a setSelectSingleFeature 1
void setSelectSingleFeature( string fcode )
where "fcode" is a Feature Code specified with or without wild card characters (see Section II-6) by the Client.
This method allows the user to make a single feature selection, with automatic notification to the Client, i.e. the two-way, pick-aperture method. This method sets up SDM to accept a user's mouse click on an SDM graphic window. When the user clicks on or near a feature, SDM will search for a feature with the given feature code within an effective area (i.e., the size of the pick aperture displayed as the mouse pointer). After the user clicks, the following actions take place:
- If a feature has been found (which satisfies the fcode constraint) that feature is highlighted.
- The status of the selection is sent to the Client, via the method receiveSelectionStatus (See Section C-001a). This status is TRUE, if a feature has been selected, and FALSE otherwise.
The Client can allow any feature code to be selected by providing the wild card character, "*", for the "fcode" argument.
FS001-1b setSelectFeatureCollection
void setSelectFeatureCollection( string fcode )
where "fcode" is a Feature Code specified by the Client.
This method allows the user to make a multiple feature selection, with automatic notification to the Client, i.e. the two-way, selection-rectangle method.
This method sets up the state of the SDM to allow a user to click and drag a rectangle of any size on an SDM graphic window. When the mouse is released, the following actions take place:
- All features with the given feature code, lying within the rectangle, are selected and highlighted.
- The status of the selection is sent to the Client, via the method receiveSelectionStatus (See Section C-001a).
This status is TRUE, if at least one feature has been selected, and FALSE otherwise.
The client can allow any feature code to be selected by providing the wild card character, "*", for the "fcode" argument.
FS001-2 selectFeature
void selectFeature(string fcode)
where fcode is a Feature Code specified by the Client..
This is the one-way (synchronous) version of FS001. This method should be used in conjunction with isOpComplete, getStatus, getX, getY and getKey After calling select Feature, the client must call isOpComplete at regular intervals, until it returns TRUE. After that, it is safe to call getStatus, getX, getY, and getKey. If getStatus returns FALSE, the user did not select a valid feature, i.e., no feature with the given "fcode" was selected. In this case, a valid key cannot be obtained via getKey, and getX and getY return the location of the mouse click. Normally, they provide the location of the selected feature.
FS001-2a selectSingleFeature 2
void selectSingleFeature( string fcode )
where "fcode" is a Feature Code with or without wild card characters (see Section II-6) specified by the Client.
This method allows the user to make a single feature selection, without automatic notification to the Client, i.e. the one-way, pick-aperture method.
This method operates just like FS001-1a, except that it does not notify the Client when the selection operation is complete, i.e. action 2 does not occur. It is the Client's responsibility to determine when the selection operation is complete by executing a polling loop, using the method isOpComplete, which will return FALSE until such time as the user completes the selection operation. After receiving TRUE from isOpComplete, the Client can then determine the status of the selection, using the method getStatus.
The client can allow any feature code to be selected by providing the wild card character, "*", for the "fcode" argument.
FS001-2b selectFeatureCollection
void selectFeatureCollection( string fcode )
where "fcode" is a Feature Code specified by the Client.
This method allows the user to make a multiple feature selection, without automatic notification to the Client, i.e. the one-way (synchronous), selection-rectangle method.
This method operates just like FS001-2a, except that it does not notify the Client when the selection operation is complete, i.e. action 2 does not occur. It is the Client's responsibility to determine when the selection operation is complete by executing a polling loop, using the method isOpComplete, which will return FALSE until such time as the user completes the selection operation. After receiving TRUE from isOpComplete, the Client can then determine the status of the selection, using the method getStatus. The client can allow any feature code to be selected by providing the wild card character, "*", for the "fcode" argument.
FS001-3 getPoint
Same as VS001-2, included here for completeness.
FS001-4 getX
Same as VS001-3, included here for completeness.
FS001-5 getY
Same as VS001-4, included here for completeness.
FS001-6 getStatus
Bool getStatus()
This method confirms if a feature with the designated feature code is found
FS001-7 isOpenComplete
Same as VS001-6, included here for completeness.
FS001-8 getKey
string getKey()
This method gets the CARISKey for the selected feature from the Server
string getKeys()
In general, this method returns a comma-separated list of CARIS keys, one for each feature selected by any of the methods described in FS001-1a, FS001-1b, FS001-2a, and FS001-2b. If a pick-aperture method has been used (FS001-1a or FS001-2a), or only one valid feature has been obtained via a selection-rectangle method (FS001-2a or FS001-2b), the list will have only one key (and no commas). If a selected feature does not have a key, a place-holder comma appears in the corresponding position in the list. The following examples demonstrate the above principles:
Example 1:
three selected features where the middle feature has no CARIS key.
"key1,,key3"
Example 2:
three selected features where the last feature has no CARIS key. "key1,
key2,"
Note the last comma, which indicates that there is a third feature.
Example 3:
one feature selected which has no CARIS key. ""
FS001-9 deselectAll
void deselectAll()
This method deselects any features selected by the user.
FS001-10 getFeaturesInsideShape
string result = getFeaturesInsideShape( string ck, string fc )
Where "ck" is the CARIS key of the shape to be queried. "ck" must equal a key that was previously used in a call to "addSmokeField" or "addCircleToFeature", as described above or "ck" must identify a closed shapein the permanent CARIS data.. "fc" is a feature code, indicating the type of POINT or Labeled point features that are to be queried. Wild cards are allowed (see Section II-6). "result" is a string containing a comma-separated list of CARIS keys. These identify the features with code "fc" that have been found within the shape identified by "ck".
This method queries a specific closed shape to obtain a list of all POINT features, having a given feature code, that lie within the shape.
FS001-11 querySelectionByKey
string querySelectionByKey( string ck, BOOL show, string extra )
where "ck" is a CARIS key parsed from the string obtained via the method getKeys, "show = TRUE" tells the server to display a window showing the GIS properties of the feature with key "ck", and "extra" may contain a comma-separated list of name/value pairs of additional (non-GIS) properties the Client wants to append to the displayed properties list.
This method returns a comma-separated list of name/value pairs of GIS properties for the feature with key "ck". Each individual name/value pair consists of a property name, followed by a colon, space, and the value of the property named. For example, if there were three name/value pairs, the returned string would look like:
"name1: value1,name2: value2, name3: value3"
The first seven pairs always have the following names: 1) "Feature type", 2) "CARIS key", 3) "Feature code", 4) "Source ID", 5) "Theme number", 6) "Display priority", and 7) "Color index". The remaining pairs depend on the feature type value given in pair 1. These values can be: "CARISLine", "CARISCompoundLine", "CARISClosedShape", "CARISImage","CARISPointFeature", or "CARISLabeledPointFeature".
The Client can use this information silently, or display it for the user. However, the developer should be aware that, the Server can be commanded to display this information by setting the "show" parameter equal to TRUE. Furthermore, the Server can be commanded to append additional name/value pairs to the display, via the "extra" parameter. This string must be in the same format as that described above for the return value. If no additional pairs are to be displayed, the "extra" parameter must be NULL. If the "show" parameter is FALSE, the "extra" parameter is ignored. The GIS name value pairs are returned, even if the "show" parameter is TRUE, as the Client may need the information for purposes other than display.
If "ck" is not unique within the selection, the information returned (and displayed, if the "show" parameter is TRUE), is always for the first occurrence of "ck" within the selection list. Under these circumstances, or if there is no key, use the method querySelectionByIndex (FS001-11).
FS001-12 querySelectionByIndex
string querySelectionByIndex( int index, BOOL show, string extra )
where "index" is the zero-based position in the list returned by getKeys (FS001-8a), and all other information is exactly as described for method querySelectionByKey (FS001-11).
FS001-13 setSelectionColor
void setSelectionColor( int colorIndex )
where "colorIndex" is the index (as defined in the CARIS .cma file) of the color to be used as the selection color.
This method changes the selection color (default is red) to the color defined by the parameter "colorIndex", if the index is greater than or equal to zero. If the parameter is less than zero, the SDM displays a color selection dialog from which the user can choose the selection color.
FS002-1 zoomTofitFeature
void zoomToFitFeature(string ck )
where ck = CARIS Key of a feature that is not a point feature.
This method pans and zooms, such that the feature identified by "ck" fills the display. There may be some clipping if the aspect ratio of the feature does not match that of the window.
FS002-2 centerAt Feature
void centerAtFeature(string ck )
where ck = CARIS Key
This method pans, such that the feature identified by "ck" is centered in the display. (The zoom state remains unchanged)
FS003 Feature Addition/Deletion
FS003-1 createNewPointFeature
void createNewPointFeature(string x, string y, string fcode, string ck, string size)
where x and y are respectively the projected Easting and Northing coordinates, (or Longitude and Latitude, if the server is in the Geodetic mode) of the new point feature position. Projected coordinates must be ASCII versions of real numbers, while Geodetic coordinates must have the form given in PS007. In addition, fcode = feature code, ck = CARIS key and size = the size of the feature with the given feature code.
Based on information from the Client, the Server will create a feature with the pre-determined symbol and color, i.e. as assigned to "fcode" in the CARIS master file and .col file, respectively, at the given location with the specificed size. The size is constant, i.e. it does not change with the zoom state.
FS003-2 createNewLabeledPointFeature
void createNewLabeledPointFeature(string x, string y, string fc, string ck, string size, string label)
The first 5 arguments are the same as FS003-1, "createNewPointFeature". The 6th argument is the text to be associated with, and displayed near the symbol for, the point. Note: this text will not appear if the map is zoomed out sufficiently that the text would obscure much of the map. "label" may be a single label or a comma-separated list of labels. In the latter case, the labels are displayed in a vertical list.
FS003-3 addCircleToFeature
void addCircleToFeature(string ck , string radius , int linecolor, int fillstate , string linewidth, string circlekey )
where ck = CarisKey of a pre-existing point feature, linecolor = color index (within the CARIS .cma file) of the color to be assigned to the circle, 0 <= fillstyle <= 8 (see figure II.1 below)
linewidth = the width of the circumference, and circlekey is the CARIS Key of the circle itself.
This method adds a circle feature with the given characteristics, centered at the feature identified by "ck".
fillstyle = 0 = NONE , 1= solid, 3= H_BIDIAGONAL, 4 = H_CROSS, 5= H_DIAGCROSS, 6 = H_FDIAGONAL, 7 = H_HORIZONTAL, 8 = H_VERTICAL (fillstyle = 2 is not used and implies NONE)Fig. II.1 Fill Styles
FS003-4 addSmokeField
void addSmokeField( string ck, string x, string y, string long_radius, string short_radius, string angle, int linecolor, string lineweight )
where ck = CARIS key to be assigned to the smoke field, "x", "y", "long_radius", "short_radius", and "angle" are used as shown in Appendix A 4. Note that:
"linecolor" and "lineweight" are used in the same way as in FS003-3.
This method creates a smoke field (a special closed shape) for chemical fire applications.
FS003-6 deleteFeature
void deleteFeature(string ck )
where ck = CARIS Key
This method deletes the specific feature identified by "ck". Note that "ck" must refer to a feature previously added to the map by the client.
FS003-7 deleteFeatureAll
void deleteFeatureAll(string fcode )
where fcode = Feature Code
This method deletes all features having feature code "fcode". Note that "fcode" must refer to a collection of features added to the map by the client.
__________________________________
1Note: this
method is intended to replace FS001-1 (setSelectFeatCode), which works only for
point or labeled point features. The new method works for all feature types
(i.e., point, labeled point, line, and closed shape). Service interface FS001-1
is retained for backward compatibility. back
to main text
2 This method is intended to replace
FS001-2 (selectFeatureCode), which works only for point or labeled point
features. The new method works for all feature types (i.e., point, labeled
point, line, and closed shape). Service interface FS001-2 is retained for
backward compatibility. back to main text
3 this method is intended to replace
FS001-8 (getKey), which is used in association with obsolete methods FS001-1 and
FS001-2. Service interface FS001-8 is retained for backward compatibility. back
to main text
4 Appendix A contains two diagrams,
showing how these parameters are used. In the diagrams, "long_radius"
is "L", "short_radius" is "r", "angle"
is the Greek letter theta, and "x" and "y" are not renamed. back
to main text
