The PowerBASIC COM Browser Tutorial

As described in the What is the PowerBASIC COM Browser topic, the PowerBASIC COM Browser is a browser utility application that exposes the Interfaces, Methods, and Properties in a type-library. It is also used to generate PowerBASIC compatible source code to be used in your application.

We will walk through and example of using the PowerBASIC COM Browser to locate a registered type library, generate the PowerBASIC compatible source code, and then use this source code in a PowerBASIC Console Compiler application.

  1. Start the PowerBASIC COM Browser

  2. Locate the Microsoft Agent Control 2.0 type library. This will be listed under the "Registered Library" heading with the text of "Microsoft Agent Control 2.0" or under the "Filename" heading of "agentctl.dll". If you do not have this type library installed it can be downloaded for free from http://www.microsoft.com/msagent/downloads/user.aspx. After installing the Microsoft Agent Control 2.0 type library click the Reload button to update the list of registered type libraries.

  3. Double-click on the Microsoft Agent Control 2.0 type library listed in the list of Registered type libraries, to generate the PowerBASIC compatible source code for this object.

  4. Click the "Save As..." button and save it with the name of "agentcc.inc"

  5. Close the PowerBASIC COM Browser

  6. Start the PowerBASIC Console Compiler IDE

    Click the Create New File button in the IDE

  7. Paste the following code into the new file created in the IDE 

#COMPILE EXE
#DIM ALL


#INCLUDE "agentcc.inc"
#INCLUDE "Win32api.inc"


' Menu options
%START = 49    ' "1" key to start the Agent Control
%STOP  = 50    ' "2" key to stop the Agent Control
%QUIT  = 51    ' "3" key to quit the application


' Display an error message and exit the application
MACRO DisplayError(txt)
  IF ISTRUE(ISOBJECT(AgentEvents)) THEN
    ' Detach the events handler
    EVENTS END AgentEvents
  END IF


  ' Print the error and then exit the program
  COLOR 12
  PRINT txt
  COLOR 7
  PRINT
  PRINT "Press any key to exit..."
  WAITKEY$
  EXIT FUNCTION
END MACRO


' Check for user input
MACRO CheckForInput
  ' The Agent Control requires a GUI (PBWin) style message loop
  DO
    ' Are there any messages pending, if so do them
    IF (PeekMessage(msg, %NULL, 0, 0, %PM_REMOVE)) THEN
      TranslateMessage(msg)
      DispatchMessage(msg)
    ELSE
      ' The program is idle, so check for user input
      SLEEP 1     ' Prevent 100% CPU usage
      Action = ASC(INKEY$)
      IF Action THEN EXIT LOOP
    END IF
  LOOP
END MACRO


FUNCTION PBMAIN AS LONG
  LOCAL AgentCtrlEx  AS IAgentCtlEx
  LOCAL AgentEvents  AS Int__AgentEvents
  LOCAL msg          AS tagMSG
  LOCAL Action       AS LONG
  LOCAL IsRunning    AS LONG
  LOCAL StartX       AS LONG
  LOCAL StartY       AS LONG
  LOCAL CharW        AS LONG
  LOCAL CharH        AS LONG


  ' Display the introduction
  CLS
  PRINT "PowerBASIC COM Tutorial"
  PRINT
  PRINT "Press:"
  PRINT "  1) Start the agent control"
  PRINT "  2) Stop the agent control"
  PRINT "  3) Exit this application"
  PRINT


  ' Create the Agent Control
  AgentCtrlEx = NEWCOM $PROGID_Agent2
  IF ISFALSE(ISOBJECT(AgentCtrlEx)) THEN
    DisplayError("The Microsoft Agent Control 2.0 is not intalled." + _
                 "This control can be downloaded from http://www.microsoft.com/msagent/downloads/user.aspx")
  END IF


  ' Create the Events handler interface
  AgentEvents = CLASS "Class_Int__AgentEvents"
  IF ISFALSE(ISOBJECT(AgentEvents)) THEN
    DisplayError("Error creating the event interface.")
  END IF


  ' Attach the Events handler interface to the Agent Control
  EVENTS FROM AgentCtrlEx CALL AgentEvents


  DO
    ' Is there any user input pending?
    CheckForInput


    IF Action = %START THEN
      IF IsRunning THEN
        ITERATE
      ELSE
        IsRunning = 1
      END IF


      ' Load the Merlin agent
      AgentCtrlEx.Characters.Load("Merlin", "Merlin.acs")
      IF OBJRESULT <> %S_OK THEN
        DisplayError("The Microsoft Agent Control 2.0 Merlin Character is not installed. " + _
                     "This character can be downloaded from http://www.microsoft.com/msagent/downloads/user.aspx")
      END IF


      COLOR 15
      PRINT "Events Received"
      PRINT "---------------"
      COLOR 14


      ' Show the Merlin agent on the screen
      AgentCtrlEx.Characters.Character("Merlin").Show


      ' Get the Width and Height of the Merlin agent
      CharW = AgentCtrlEx.Characters.Character("Merlin").Width
      CharH = AgentCtrlEx.Characters.Character("Merlin").Height


      ' Get the Width and Height of the Desktop
      DESKTOP GET CLIENT TO StartX, StartY


      ' Find the center of the desktop for Merlin agent
      StartX = (StartX - CharW)\2
      StartY = (StartY - CharH)\2


      ' Move the Merlin agent to the center of the desktop
      AgentCtrlEx.Characters.Character("Merlin").MoveTo(StartX, StartY)


      ' Have the Merlin agent play the trumpet
      AgentCtrlEx.Characters.Character("Merlin").Play(UCODE$("Announce"))


      ' Make the Merlin agent speak
      AgentCtrlEx.Characters.Character("Merlin").Speak("With \map="+$DQ+"PowerBAYSIK"+$DQ+"="+$DQ+"PowerBASIC"+$DQ+"\ \Pau=300\ you can be a wizard too!")


    ELSEIF Action = %STOP THEN
      IF IsRunning THEN
        ' Stop all actions by the Merlin agent and unload it
        AgentCtrlEx.Characters.Character("Merlin").Stop
        AgentCtrlEx.Characters.Unload("Merlin")
        IsRunning = 0
      END IF


    ELSEIF Action = %QUIT THEN
      IF IsRunning THEN
        ' Stop all actions by the Merlin agent and unload it
        AgentCtrlEx.Characters.Character("Merlin").Stop
        AgentCtrlEx.Characters.Unload("Merlin")
      END IF


      IF ISTRUE(ISOBJECT(AgentEvents)) THEN
        ' Detach the event handler interface
        EVENTS END AgentEvents
      END IF


      COLOR 7
      EXIT LOOP
    END IF


  LOOP


END FUNCTION

  1. Click the Save All button and save this file as "agent.bas" in the same directory that you save "agent.inc" too in step #4

  2. Open the "agent.inc" file in the IDE

  3. Search (CTRL+F) in the IDE for the text of "IAgentCtl event interface" (without the quotes). The methods of this interface are called when an event occurs in the Microsoft Agent Control occurs. We will add code to these methods that will display the event that occurred in the dialogs listbox. Make the Int__AgentEvents, look like the following:

CLASS Class_Int__AgentEvents $CLSID_Event__AgentEvents AS EVENT
  INTERFACE Int__AgentEvents $IID_Int__AgentEvents
    INHERIT IDISPATCH


    METHOD ActivateInput <1> (BYREF CharacterID AS STRING)
      ' The Merlin Agent is now ready to receive mouse and speech input
      PRINT "Input Activated"
    END METHOD


    METHOD DeactivateInput <3> (BYREF CharacterID AS STRING)
      ' The Merlin Agent is no longer ready to receive mouse and speech input
      PRINT "Input Deactivated"
    END METHOD


    METHOD Click <2> (BYVAL CharacterID AS STRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, BYVAL y AS INTEGER)
      ' The user clicked on the Merlin Agent
      PRINT "Click at ("+FORMAT$(x)+","+FORMAT$(y)+")"
    END METHOD


    METHOD DblClick <4> (BYVAL CharacterID AS STRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, BYVAL y AS INTEGER)
      ' The user double-clicked on the Merlin Agent
      PRINT "Double Click at ("+FORMAT$(x)+","+FORMAT$(y)+")"
    END METHOD


    METHOD DragStart <5> (BYVAL CharacterID AS STRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, BYVAL y AS INTEGER)
      ' The user has started dragging the Merlin Agent
      PRINT "Drag Start at ("+FORMAT$(x)+","+FORMAT$(y)+")"
    END METHOD


    METHOD DragComplete <6> (BYVAL CharacterID AS STRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, BYVAL y AS INTEGER)
      ' The user has finished dragging the Merlin Agent
      PRINT "Drag Complete to ("+FORMAT$(x)+","+FORMAT$(y)+")"
    END METHOD


    METHOD Show <15> (BYVAL CharacterID AS STRING, BYVAL Cause AS INTEGER)
      ' The Merlin Agent is now showing on the desktop
      PRINT "Character is showing"
    END METHOD


    METHOD Hide <7> (BYVAL CharacterID AS STRING, BYVAL Cause AS INTEGER)
      ' The Merlin Agent is now hidding
       PRINT "Character is hiding"
    END METHOD


    METHOD RequestStart <9> (BYVAL Request AS IDISPATCH)
      ' The Merlin Agent is processing a Speak, Play, or Get Method
      PRINT "Request Start"
    END METHOD


    METHOD RequestComplete <11> (BYVAL Request AS IDISPATCH)
      ' The Merlin Agent has finished processing a Speak, Play, or Get Method
      PRINT "Request Complete"
    END METHOD


    METHOD Restart <21> ()
      ' Insert your code here
    END METHOD


    METHOD Shutdown <12> ()
      ' Insert your code here
    END METHOD
    METHOD Bookmark <16> (BYVAL BookmarkID AS LONG)
      ' Insert your code here
    END METHOD


    METHOD Command <17> (BYVAL UserInput AS IDISPATCH)
      ' Insert your code here
    END METHOD


    METHOD IdleStart <19> (BYVAL CharacterID AS STRING)
      ' Insert your code here
    END METHOD


    METHOD IdleComplete <20> (BYVAL CharacterID AS STRING)
      ' Insert your code here
    END METHOD


    METHOD Move <22> (BYVAL CharacterID AS STRING, BYVAL x AS INTEGER, BYVAL y AS INTEGER, BYVAL Cause AS INTEGER)
      ' The Merline Agent has moved
      PRINT "Move to ("+FORMAT$(x)+","+FORMAT$(y)+")"
    END METHOD


    METHOD Size <23> (BYVAL CharacterID AS STRING, BYVAL Param_Width AS INTEGER, BYVAL Height AS INTEGER)
      ' Insert your code here
    END METHOD


    METHOD BalloonShow <24> (BYVAL CharacterID AS STRING)
      ' The Merlin Agent is showing a word balloon
      PRINT "Showing balloon text"
    END METHOD


    METHOD BalloonHide <25> (BYVAL CharacterID AS STRING)
      ' The Merlin Agent is hiding a word balloon
      PRINT "Hiding balloon text"
    END METHOD


    METHOD HelpComplete <26> (BYVAL CharacterID AS STRING, BYVAL Param_Name AS STRING, BYVAL Cause AS INTEGER)
      ' Insert your code here
    END METHOD


    METHOD ListenStart <27> (BYVAL CharacterID AS STRING)
      ' Insert your code here
    END METHOD


    METHOD ListenComplete <28> (BYVAL CharacterID AS STRING, BYVAL Cause AS INTEGER)
      ' Insert your code here
    END METHOD


    METHOD DefaultCharacterChange <30> (BYREF Param_GUID AS STRING)
      ' Insert your code here
    END METHOD


    METHOD AgentPropertyChange <31> ()
      ' Insert your code here
    END METHOD


    METHOD ActiveClientChange <32> (BYVAL CharacterID AS STRING, BYVAL Active AS INTEGER)
      ' Insert your code here
    END METHOD


  END INTERFACE
END CLASS

  1. In the IDE, click the compile and run button. The application will be displayed as

     

  2. Press the "1" key and the Merlin character will display in the top left corner of the screen then move to the center of the desktop and play a trumpet then speak. If you wish to hear the text shown in the balloon when Merlin is speaking, you will need to download and install the free SAPI 4.0 and a Text to Speech Engine from http://www.microsoft.com/msagent/downloads/user.aspx.

  3. You can click, double-click, drag and drop, hide (right-click on Merlin and select Hide), or show (right-click on Merlin in the systems tray and select Show) and see these events listed in the Console window.

  4. Press the "2" key to stop and unload the Merlin character.

See Also

What is the PowerBASIC COM Browser

The PowerBASIC COM Browser User Interface