When developing the FalconView™ Programming interfaces, we strive to make it as easy as possible for developers to get started. With that said, COM programming can be a complicated task in the beginning and if you are new to the concept, it may make sense to start with a very simple Visual Basic program to get some immediate results before jumping in to using Visual C++ for a production system.

The VBAutomationSample is probably enough to get you started if you are familiar with VB.

There is also a Visual Studio 2005 Wizard that generates a C# framework to start creating a plug-in Layer here Download

Table of Contents

FalconView COM Overview

Interfaces

COM from VB:

Clients and Servers

Connecting to FalconViwe from an EXE

Drawing

Callbacks

Creating an In Process (DLL) Component

Layer Editor

Naming Your Editor Object

Startup

Invoking the Editor

Adding Toolbar Buttons

Clicking and Dragging

 Start SlideShow

Slide 1: FalconView™ COM Overview

  • COM (Component Object Model) is a Microsoft specification which describes how to build components that can be dynamically shared.
  • COM components consist of executable code distributed as DLLs or EXEs
  • COM is language independent (C, C++, Visual Basic, JAVA, ADA…) But Microsoft tools such as VB Visual C++ or C# make it much easier.

With FalconView, you can use the interfaces either from a EXE running out of process or by creating a DLL running InProcess with FalconView. This first example is an EXE implementation.

Slide 2: Interfaces

  • An interface is a set of functions (methods) that a component implements and clients use.
  • A method is a function defined by an interface. 
Object:  FVW
Interfaces: 
   IMap
   ILayer
   ILayerEditor
   …

Method:
IMap:   GetElevation(Lat,Lon,elv)
   GetMapDimensions(…)
   SetMapDisplay(…)

ILayer:   AddLine(…)
   AddText(…)
   AddIcon(…)

Slide 3: COM from VB

The FVW.TLB (Type Library) ships with PFPS in the PFPS\Falcon sub directory. It contains the definition of the Interfaces and Methods for FalconView. COM also supports embedding the TLB information in the program or DLL. This is the case for most DLLs used by FalconView such as the MapRenderingEngine which is a component which draws the background maps in FalconView.

To use a COM component add it to the project under the VB Project->References menu. It will usually show up in the COM interface list but you may need to browse to the location of the TLB or the DLL.

Slide 4: Clients and Servers

When developing for FalconView you will be writing code that sometimes acts as a client of FalconView and some times acts as a Server to FalconView. For instance if you call the FalconView interface ILayer. FalconView is a service that allows you to do somthing like draw a line.

Later on, FalconView might call back into your component using the ICallback interface to get a tooltip to display when the mouse hovers over the line.

Slide 5: Connecting to FalconView from an EXE

First thing you will want to do is connect to FalconView to do this:

  • Create an interface to FVW ILayer 
Dim MyLayer As FVW.Layer
Set MyLayer = New FVW.Layer

MyLayer.RegisterWithMapServer(
   "Sample Layer", 
   Me.hWnd, Me)
  • Create a layer 
Dim LayerHandle As Integer
LayerHandle = MyLayer.CreateLayer("Sample Layer")

Slide 6: Drawing

  • Set up the pen, or font settings 
MyLayer.SetPen(LayerHandle, 
      255, 0, 0, ‘red
      10, 10, 10,  ‘grey
      0, 3, 0)  ‘3 pixel solid
  • Add point(s), line(s), Text … 
LineHandle = MyLayer.AddLine(
   LayerHandle, 
   41.24005, -111.97176, 
   33.77845, -84.39846
   , 0, 0)
  • Refresh the screen 
MyLayer.Refresh (LayerHandle)

Slide 7: Callbacks

Callbacks are used when FalconView needs to get data from a client or to notify a client of an event such as a button press.

In VB you simply add the line implements ICallback at the top of your form and VB will insert stubs for the callback functions Callback examples 

  OnFalconViewExit()
  GetHelpText()
  GetTooltip()
  OnMouseClick() 
  GetMenuItems() 
  OnToolbarButtonPressed()

Note: All methods in an interface must be fully implemented even if you do not need them in your app. (Add the method and leave them empty.)

example GetMenuItems(…) Allows the user to add there own items to the right click menu of an item. Menu_text string contains the words to put in the menu and the name of the method to call. Method called must be declared “Public” 

ICallback_GetMenuItems(layer_handle,object_handle,menu_text)
  menu_text = “Menu Text" + vbCrLf + “MyMethod"
End Sub

Public Sub MyMethod(layer_handle As Long, object_handle As Long) 
  ' do somthing like put up a dialog or calculate Pi.
End Sub

Slide 8: Creating an InProcess (DLL) component

Slide 9: Layer Editor

The [Wiki:ILayerEditor] interface is a callback interface that allows you to implement an editor inside of FalconView. Because the your editor is invoked “in process” by FalconView, it is faster than running from a standalone exe.

  • Plug in objects are implemented as an ActiveX DLL (not an exe)
  • The layer editor usualy will work in conjunction with a layer to allow the contents to be interacted with.
  • Representative Methods: 
          * =SetEditOn()= 
      * =OnDrag()=
      * =OnDrop()=
      * =OpenFile()=
      * =OnKeyDown()=

Slide 10: Naming your Editor Object

FalconView is made aware of your editor by storing the ClassIDString in the registry: 

=HKEY_LOCAL_MACHINE\software\PFPS\FalconView\Client Editors\0\classIDString = Project.class=
  • The ClassID is the combination of the VB Project Name ”.” Editor Class Name
    • The Project name is set under Project->xxx Properties
    • The class name is set the the VB properties box on the right of the screen
  • Your object must be registered on the system using RegServ?32 xxx.dll. (This is automatically done when you build the component)

Slide 11: Startup

Once registered when FalconView starts it will create one of your objects It calls: 

   * =Class_Initialize()=
   * =GetEditorName(name)=
   * =GetEditorToolbarButton(filename)=
   * =GetEditorStrings(menu_text, file_type)=
   * =GetIconName(icon_name)=

Slide 12: Invoking the Editor

When the use invoked the editor either by pressing the Editor toggle toolbar or by selecting it in the tools menu, FalconView calls:

  • SetEditOn(1) --- This is where you would add/remove toolbar for your editor
  • GetNextNewFileName(filename) --- This is the "Default" Filename until the user saves the overlay w/ a different name.
  • GetDispatchPtr(pointer) --- This should return the handle to you layer object (MPUCLayer)
  • GetIconName(icon_name) --- This is the little icon that appears in the overlay Manager or the Overlay Open Dialog
  • OnNewLayer(layer_handle) --- layer_handle is the handle to a new layer falconView automatically creates

Slide 13: Adding Toolbar Buttons

Create a bitmap which has the necessary 16 x 16 bitmaps tacked together side by side.

Add the toolbar as follows: 

Dim sep(0 To 1) As Long
    …
sTBFile = “C:\toolbar.bmp“  ' toolbar bitmap with 3 buttons 48 x 16 pixels
sep(0) = 1                  ' add a seperator (extra space) between button 1 and 2
numseps = 1                 ' a single seperator
num_buttons = 4             ' total buttons and seperators
Loc = CLIENT_TOOLBAR_TOP    ' =0  

Hndl =MyLayer.AddToolBar( sTBFile, num_buttons, “Name", loc, sep_array, num_seps)

When the user presses a toolbar button FalconView will call the wiki:ICallback interface 

ICallback_OnToolbarButtonPressed (toolbar_id, button_number)

Slide 14: Clicking and Dragging

A common operation of an overlay editor is a click and drag. To implement this the DLL would implement the following methods. Then once the layer has been created FalconView will call TestSelected(…) whenever the mouse stops. This method allows the Layer Editor to tell the user what it will do if they press the left mouse button. The editor can return a tool-tip, status bar text, and change the mouse pointer.

When the user does press the left mouse button. FalconView calls the Layer Editor 'Selected(…)' method. At this point the editor could do an immediate action such as displaying an additional information dialog or it can set the flag indicating that it wants to begin a drag operation by setting drag = true.

If drag = true, when the user moves the mouse with the left button down, FalconView calls OnDrag(…) repeatedly as the mouse moves until OnDrop() or CancelDrag(). During the drag, the software will likely update the screen such as moving the icon to correspond to the the location of the mouse location.

Finally when the user releases the mouse there will be an OnDrop(…) call to the Layer Editor. It would be expected that the editor would update the data based on the released location.

(COMMENT BOX)

-- [Wiki:ChrisBailey] - 24 May 2005

You are here: GettingStarted > FVDev > WebHome

Attachments