Monday, August 01, 2005

Capturing Feature Events in your Code with GTVx

GTVx has a simple yet power mechanism for allowing features selected in the view to be processed by your code. It may not be clear how to use this functionality at first glance, so this blog entry will attempt to clarify this process.

The process of capturing a feature in your code involves two things: activating the feature capture mode and catching an event that is fired by GTVx when a feature is captured.

The method to activate the feature capture mode is (not too surprisingly) called: ActivateFeatureCaptureMode It takes two parameters: ID and FitlerString.

The ID parameter is the sometimes confusing to developers, but it simply provides a developer-defined id that will appear in any feature captured event fired while in this mode (the uses for this id should become clearer when we look at the Event).

The FilterString parameter is a comma-delimited string of <category Id>:<filter id> pairs used to restrict which features can be selected. The filter id can be an asterisk “*” to indicate that all filter ids in the specified category are allowed. This parameter can be very important for custom applications; for example, if you have a pole inspection application, you only want the user to be able to select poles, so you only give it the pole’s category id/filter id pair. If you did not restrict select to just poles, your code will have to determine if the feature can be processed or not and tell the user that he or she can’t selected that features. The FitlerString can be an empty string which means the user can select anything in the view. This unrestricted access is usually not desired, but is available (and is unfortunately used too much in applications). Two other options are the <SessionPriority> token that will look to see if a session graphic has the same linkage as a regular feature that was selected; if so, the session graphics is always returned. The Session Priority feature is very useful if your application places session graphics on top of regular graphics to indicate something; with the session priority, you will always know you are getting the session graphic if one exists. Here are some examples on how the feature capture mode can be activated:

GTVX1.ActivateFeatureCaptureMode 1, ""

Any feature can be selected in the view.

GTVX1.ActivateFeatureCaptureMode 1, "2:7"

Only features in Category 2 with FilterId 7 can be selected.

GTVX1.ActivateFeatureCaptureMode 1, _
"2:7, 2:10, 2:20, 3:10"

Only features in Category 2 with Filter Id 2, 10, or 20 or in Category 3 with Filter Id 10 can be selected.

GTVX1.ActivateFeatureCaptureMode 1, "2:*, 3:*"

All features in Categories 2 and 3 can be selected.

GTVX1.ActivateFeatureCaptureMode 1, _
"2:7, 3:10, <SessionPriority>"

Features in Category 2 with Filter Id 7 or in Category 3 with Filter Id 10 can be selected. However, if a session graphic has the same linkage as one of these features, it will be returned instead.

The second part of capturing features is an Event that is fired by GTVx when a feature is selected in the view while the feature capture mode is active. The FeatureCaptured event looks like the following:

Private Sub GTVX1_FeatureCaptured(ByVal id As Long, _
ByVal categoryId As Long, _
ByVal offset As Long)

.
.
.

End Sub

The FeatureCaptured event has 3 parameters: Id, CategoryId, and Offset. The Id is the same value specified in the ActivateFeatureCaptureMode. There is only one FeatureCaptured event in your code, so you must use this Id value to tell how the feature is to be handled. It may be that you only have one ActivateFeatureCaptureMode in your code and there is only one thing for this event to do; however, it is usually the case that you capture different features for different reasons and need some way to see how the capture mode was started. For example, if you had an inspection application that has a Pole Inspection mode and a Valve inspection mode. You might have something like this:

Private Sub PoleInspectionCommand_Click()

GTVX1.ActivateCaptureFeatureMode 1, "2:3"

End Sub

Private Sub ValveInspectionCommand_Click()

GTVX1.ActivateCaptureFeatureMode 2, "7:7"

End Sub


Private Sub GTVX1_FeatureCaptured(ByVal id As Long, _
ByVal categoryId As Long, _
ByVal offset As Long)

If mode = 1 Then ' Pole Mode
.
.
.
ElseIf mode = 2 Then ' Valve Mode
.
.
.
End If

End Sub


Note that the PoleInspection activated the capture mode with the id set to 1 and the Valve Inspection activated the capture mode with the id set to 2. Then in the FeatureCaptured event, the id is checked to see if it is 1 or 2. If 1, the PoleInspection code is executed and if 2, the Valve Inspection code is executed. In this example, it would be possible to tell how to handle the captured feature by the feature’s characteristics (since you can get filter id from Category and Offset). However, if your two modes were Edit Pole and Delete Pole, you can tell so easily.

The CategoryId and Offset values are the standard keys to looking up an element in the GTViewer data. Most element related function take these values as inputs. You can also refer to a previous blog entry on determining a feature’s keys from Category Id and Offset.

It should also be pointed out that Capturing Features in GTViewer is very similar to this process. Events are handled slightly differently in GTViewer, so there are some minor coding differences, but the process is the same.

1 comment:

Larry Cosgrove said...

Joey,

As always, an excellent blog entry. But hey, was this a test to make sure we are reading? (because we always are).

In one of the examples you posted it says:

-------------------------------
GTVX1.ActivateFeatureCaptureMode 1, "2:7"

Only features in Category 7 with FilterId 7 can be selected.
-------------------------------

If my GTVx manual is correct the example above would actually read, "Only features in Category 2 with FilterId 7 can be selected" - Not a Category 7.

Gold Star anyone?

Cos