ICallback

ICallback is a COM interface defined by FalconView but implemented by the third party program. Most Programs that use [[ILayer will want to implement it. When the user interacts with a graphical item created by the 3rd party, FalconView will call the appropriate method on the ICallback interface which allows the 3rd party program to interact with the user.

For instance if a program calls ILayer::AddIcon(...) FalconView will display the icon on the map at the specified map and returns a "handle" to the icon to the calling program. Later if the user clicks the icon, FalconView will call the ICallback_OnSelected(...) method wand pass the handle of the icon. The program then could perform some sort of function such as displaying a dialog box with additional information or changing the color of line style of the line.

In a number of instances, FalconView needs to request information from a client application or allow a client to take action whenever a certain event occurs.  To allow FalconView to make these types of callbacks the client must implement a COM object with a dispatch interface that implements the standard interface defined below.  The interface is passed to FalconView in the method RegisterWithMapServer.

The following functions are methods that the component can implement to take advantage of these callbacks.

See also ICallback2

Methods

GetMenuItems

GetHelpText

HRESULT GetHelpText(long layer_handle, long object_handle, BSTR* help_text);

 

When the cursor is above an object in the layer, FalconView calls this function to determine the text to place on the status bar.

 

Parameters

 

layer_handle	the value of the handle to the layer
object_handle	the value of the object that needs the help text
help_text	a pointer to a BSTR used to receive the help text

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

GetInfoText

HRESULT GetInfoText(long layer_handle, long object_handle, BSTR* title_bar_txt,
BSTR''' dialog_txt, long''' result);

 

When a layer object is left-clicked in FalconView, FalconView attempts to call OnSelected.  If OnSelected was not implemented or returns failure, FalconView then tries to call GetInfoText to fill in the standard FalconView "Get Info" box with the given title bar and dialog text.

 

Parameters

 

layer_handle	the value of the handle to the layer
object_handle	the value of the object handle that was selected in FalconView
title_bar_txt	a pointer to a BSTR used to receive the title bar for the info box dialog
dialog_txt	a pointer to a BSTR used to receive the dialog text displayed in the info box dialog
result	set to SUCCESS to denote the keystroke was handled, FAILURE to allow FalconView to process the keystroke

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

GetTimeSpan

HRESULT GetTimeSpan (long layer_handle, DATE FAR''' begin, DATE FAR''' end);

 

If a client has specified that its layer is a time sensitive overlay using SetIsTimeSensitiveOverlay, then this function is called when the view time dialog box is opened to determine the beginning and ending times for the overlay.

 

Parameters

 

layer_handle	the value of the handle to the layer
begin	a pointer to a DATE to receive the beginning time of the layer
end	a pointer to a DATE to receive the ending time of the layer

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

GetToolTip

HRESULT GetToolTip(long layer_handle, long object_handle, BSTR* tool_tip);

 

When the cursor is above an object in the layer, FalconView calls this function to determine the text to place in the tooltip.

 

Parameters

 

layer_handle	the value of the handle to the layer
object_handle	the value of the object that needs the tool tip text
tool_tip	a pointer to a BSTR used to receive the tool tip text

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

OnDoubleClicked

HRESULT OnDoubleClicked([in] long layer_handle,[in] long object_handle,
[in] long fvw_parent_hWnd, [in] double lat,
[in] double lon);

 

FalconView calls this method when the map is double-clicked.  OnDoubleClicked is only called when the cursor is over an object.

 

The handle to FalconView's window is passed to the method so that a window or dialog that you may wish to create can become a child of the FalconView window.

 

Parameters

 

layer_handle	the value of the handle to the layer
object_handle	the handle to the double-clicked object
fvw_parent_hWnd	the value of FalconView's main window handle
lat	latitude that was double-clicked
lon	longitude that was double-clicked

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

OnFalconViewExit

HRESULT OnFalconViewExit(long layer_handle);

 

When FalconView is closed, it attempts to call OnFalconViewExit for each open layer.  After this, OnFalconViewExit is called with a layer_handle of -1.  Calling OnFalconViewExit with the layer_handle set to -1 allows clients to receive this callback even in the case where no open layers exist.  Make certain you perform any cleanup necessary for the layer at this time

 

Parameters

 

layer_handle

the value of the handle to the layer

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

OnOverlayClose

HRESULT OnOverlayClose(long layer_handle);

 

When an overlay is closed in FalconView, the OnOverlayClose method for each client is called with the handle to that overlay.  This includes your client's layer overlay.

 

Parameters

 

layer_handle

the value of the handle to the layer

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

OnPreClose

HRESULT OnPreClose(long layer_handle, long* cancel);

 

OnPreClose informs the layer that it is about to be closed, so it can perform any necessary clean-up operations.  If the overlay returns cancel = 1, then the close is canceled.  When this function is called with cancel set to NULL, the layer is closed immediately.

 

Parameters

 

layer_handle	the value of the handle to the layer that is about to be closed
cancel	NULL   the layer is closed immediately   0          proceed with layer close   1          cancel close

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

OnSelected

HRESULT OnSelected(long layer_handle, long object_handle, long fv_parent_hWnd;
double latitude, double longitude, long* result);

 

When the map is left-clicked in FalconView, the overlay manager loops through each of the overlays, from top to bottom, and calls the overlay’s OnSelected method.  In general, the loop is terminated when an overlay’s OnSelected method returns SUCCESS.  A client layer, however, can terminate the loop only if OnSelected sets result to SUCCESS and the object handle does not equal -1.  If the client’s OnSelected fails, and the object handle is non-negative, then GetInfoText is called.  The loop can be terminated if GetInfoText sets its result equal to SUCCESS.

 

The handle to FalconView's window is passed to the method so that a window or dialog that you may wish to create can become a child of the FalconView window.

 

Parameters

 

layer_handle	the value of the handle to the layer
object_handle	the value of the object that was selected
fv_parent_hWnd	the value of FalconView's main window handle
latitude	the latitude of the mouse click
longitude	the longitude of the mouse click
result	set to SUCCESS to denote the keystroke was handled, FAILURE to allow FalconView to process the keystroke

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

 

Remarks

 

OnSelected must immediately return in order to avoid a deadlock situation.

OnToolbarButtonPressed

HRESULT OnToolbarButtonPressed(long toolbar_id, long button_number);

 

When a button in a client toolbar created with AddToolbar is pressed, FalconView calls this method.

 

Parameters

 

toolbar_id	the value of the toolbar handle
button_number	the 0-indexed value of the button that was pressed

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

SetCurrentViewTime

HRESULT SetCurrentViewTime(long layer_handle, DATE date);

 

If a client specified that its layer is a time-sensitive overlay using SetIsTimeSensitiveOverlay, then this function is called when the view time dialog changes the current time.  Layers should be updated accordingly.

 

Parameters

 

layer_handle	the value of the layer handle
date	the value of the current view time

 

Returns

 

S_OK (success)

 

For failure, a variety of standard HRESULT values can be returned.  Consult your COM documentation for these standard values.

---

Questions

Calling ICallback

The Callback example uses a class derived from CCmdTarget and has a lot of MFC auto generated message maps, but does not actually use ICallback anywhere. I need that same functionality for the ICallback2 interface because I need access to OnCoverageChanged(). How do I go about gettin MFC to generate all the message maps for me. Or can the [[ICallback2 class be used directly? -- !MattF - 18 Apr 2006

A) Maybe I am misunderstanding your question but the ICallback interface is implemented by the third party tool and is called by FalconView when the user interacts with an object added to a layer. I can not think of an instance where you would call the methods on yourself. In your example you would implement wiki:ICallback2]] then you would register you component with FalconView by calling RegisterWithMapServer(...) on the [[ILayer interface.

If you are using MFC you use the class wizard to add your implementation but most developers will find using ATL easier. There is an empty implementation of ICallback2 in the TestMask.zip found under the ILayer2 topic.

-- ChrisBailey - 20 Apr 2006

OnFalconViewReady

I am attempting to write a plugin for FalconView that will be using the ICallback, ICallback2, and ICallback3 interfaces. I have been successful with ICallback, but it seems that FalconView never makes calls to ICallback2 or ICallback3. The process I went through to get just ICallback working is roughly as follows:

• Create MFC DLL project, and #import fvw.tlb
• Add a ATL Simple Object that implements ICallback, ICallback2, and ICallback3
• Add in smart pointers of type ILayerPtr and IMapPtr, instantiated with CreateInstance
• Create the ATL object with CComObject, and pass it into the RegisterWithMapServer function of the ILayerPtr and the SetDispatchPtr function of the IMapPtr

I had also attempted to call RegisterWithMapServer on ILayer2Ptr and ILayer3Ptr, but it appears that the succeeding versions of the ILayer interface do not incorporate the previous versions. These attempts would not compile, and the error given said that there was no RegisterWithMapServer method in ILayer2 or ILayer3.

Any suggestions on what else needs to be done to get the ICallback2 and ICallback3 functions to be called? -- WilliamMorrell - 13 Jun 2006

Update: Thanks for the info, that explains a few things that I thought were a little strange. So it turns out that my issue was partially due to depreciated code. I also discovered shortly after posting the question that OnFalconViewReady is only called if the client app launches FalconView; if an instance of FalconView is already opened, OnFalconViewReady is never called. My fix to check if it is safe to use the other FalconView functions is to first check if GetMapDisplay returns success, and proceed if so. If failure is returned, then wait for OnFalconViewReady to be called. -- WilliamMorrell - 20 Jun 2006

A) You are probably doing everything correctly. We checked into this and it turns out that OnCoverageChanged is no longer called in FalconView 4.0 or later. This feature was lost in the large amount of rearchitecture done to the map data server. You can, however, still do the same thing using the MDSUtilNotifyEvents in 4.0 and later.

Q) Can anyone offer advice to speed up icon selection? when using the ICallback OnDoubleClicked, it can take up to 30 seconds for the function to be reached. (!) This is in an out of process program. The results are the same for a single icon or about 300.

That is bizarre, I have no idea off the top of my head why it would take so long. In process, there is no perceivable delay and the marshaling code cant take anywhere near that long. Ill try to create a test program.