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 an 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 For Windows application.
Start the PowerBASIC COM Browser
Open the Options dialog by selecting Tools | Options and select the following options:
Always use an Interface Prefix : Off
Interface Prefix : Agent
Prefix ProgIDs, ClassIDs... : Off
Use ANSI Strings : Off
Use Singular Enumerations : Off
Generate Dispatch Interfaces : Off
Include Parameter Names : On
Use Property Get/Set statements : On
Click the OK button to save and close the Options dialog.
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/DOWNLOADS/en/default.aspx. After installing the Microsoft Agent Control 2.0 type library click the Reload button to update the list of registered type libraries.
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.
Click the "Save As..." button and save it with the name of "agent.inc"
Close the PowerBASIC COM Browser
Start the PowerBASIC For Windows IDE
Click the Create New File button in the IDE
Paste the following code into the new file created in the IDE
#COMPILER PBCC 6 #COMPILE EXE #DIM ALL ' MS Agent Control include file generated by PBrow.exe #INCLUDE "agent.inc" ' Win32 Api include file #INCLUDE "WinUser.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 Agent_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_Agent 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/DOWNLOADS/en/default.aspx") END IF ' Create the Events handler interface AgentEvents = CLASS "Class_Agent_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/DOWNLOADS/en/default.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+"Powur bay sick!"+$DQ+"="+$DQ+"PowerBASIC"+$DQ+ _ "\ \Pau=300\you can be a \map="+$DQ+ "wizurd too!"+$DQ+"="+$DQ+"wizard too!"+$DQ) 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
Click the Save All button and save this file as "agent.bas" in the same directory that you save "agent.inc" to in step #4
Open the "agent.inc" file in the IDE
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. We will add code to these methods that will display the event that occurred in the dialogs listbox. Make the Class_Agent_AgentEvents, look like the following:
CLASS Class_Agent_AgentEvents $CLSID_Event__AgentEvents AS EVENT INTERFACE Agent_AgentEvents $IID_Agent_AgentEvents INHERIT IDISPATCH METHOD ActivateInput <1> (BYVAL CharacterID AS WSTRING) ' The Merlin Agent is now ready to receive mouse and speech input PRINT "Input Activated" END METHOD METHOD DeactivateInput <3> (BYVAL CharacterID AS WSTRING) ' The Merlin Agent is no longer ready to receive mouse and speech input PRINT "Input Deactivated" END METHOD METHOD CLICK <2> (BYVAL CharacterID AS WSTRING, BYVAL Button AS INTEGER, BYVAL PB_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 WSTRING, BYVAL Button AS INTEGER, BYVAL PB_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 WSTRING, BYVAL Button AS INTEGER, BYVAL PB_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 WSTRING, BYVAL Button AS INTEGER, BYVAL PB_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 WSTRING, 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 WSTRING, 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 WSTRING) ' Insert your code here END METHOD METHOD IdleComplete <20> (BYVAL CharacterID AS WSTRING) ' Insert your code here END METHOD METHOD MOVE <22> (BYVAL CharacterID AS WSTRING, 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 WSTRING, BYVAL PB_Width AS INTEGER, BYVAL Height AS INTEGER) ' Insert your code here END METHOD METHOD BalloonShow <24> (BYVAL CharacterID AS WSTRING) ' The Merlin Agent is showing a word balloon PRINT "Showing balloon text" END METHOD METHOD BalloonHide <25> (BYVAL CharacterID AS WSTRING) ' The Merlin Agent is hiding a word balloon PRINT "Hiding balloon text" END METHOD METHOD HelpComplete <26> (BYVAL CharacterID AS WSTRING, BYVAL PB_Name AS WSTRING, BYVAL Cause AS INTEGER) ' Insert your code here END METHOD METHOD ListenStart <27> (BYVAL CharacterID AS WSTRING) ' Insert your code here END METHOD METHOD ListenComplete <28> (BYVAL CharacterID AS WSTRING, BYVAL Cause AS INTEGER) ' Insert your code here END METHOD METHOD DefaultCharacterChange <30> (BYVAL PB_GUID AS WSTRING) ' Insert your code here END METHOD METHOD AgentPropertyChange <31> () ' Insert your code here END METHOD METHOD ActiveClientChange <32> (BYVAL CharacterID AS WSTRING, BYVAL Active AS INTEGER) ' Insert your code here END METHOD END INTERFACE END CLASS
In the IDE, click the compile and run button. The application will be displayed as
Click the "Start Agent" button 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/DOWNLOADS/en/default.aspx.
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 listview
control on the dialog box.
Click the Stop Agent button to stop and unload the Merlin character.
See Also
What is the PowerBASIC COM Browser
The PowerBASIC COM Browser User Interface