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 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.

1. | Start the PowerBASIC COM Browser

2. | Open the Options dialog by selecting Tools | Options and select the following options:

o | Always use an Interface Prefix : Off

o | Interface Prefix : Agent

o | Prefix ProgIDs, ClassIDs... : Off

o | Use ANSI Strings : Off

o | Use Singular Enumerations : Off

o | Generate Dispatch Interfaces : Off

o | Include Parameter Names : On

o | Use Property Get/Set statements : On

3. | Click the OK button to save and close the Options dialog.

4. | 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.

5. | 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.

6. | Click the "Save As..." button and save it with the name of "agent.inc"

7. | Close the PowerBASIC COM Browser

8. | Start the PowerBASIC For Windows IDE

9. | Click the Create New File button in the IDE

10. | Paste the following code into the new file created in the IDE

#COMPILER PBWIN 10

#COMPILE EXE

#DIM ALL

%ID_START = 1000

%ID_STOP = 1001

%ID_EVENTLIST = 1003

GLOBAL hDlg AS LONG

' MS Agent Control include file generated by PBrow.exe

#INCLUDE "agent.inc"

' Display an error message

MACRO DisplayError(TXT)

IF ISTRUE(ISOBJECT(AgentEvents)) THEN

' Detach the events handler

EVENTS END AgentEvents

END IF

' Print the error and then exit the callback routine

MSGBOX TXT, %MB_OK OR %MB_ICONERROR, "MS Agent Error"

EXIT FUNCTION

END MACRO

CALLBACK FUNCTION DlgProc

STATIC AgentCtrlEx AS IAgentCtlEx

STATIC AgentChars AS IAgentCtlCharacters

STATIC AgentCharsEx AS IAgentCtlCharacterEx

STATIC AgentEvents AS Agent_AgentEvents

LOCAL StartX AS LONG

LOCAL StartY AS LONG

LOCAL CharW AS LONG

LOCAL CharH AS LONG

LOCAL SpeakTxt AS WSTRING

SELECT CASE AS LONG CB.MSG

CASE %WM_INITDIALOG

' Create the Agent Control Object

AgentCtrlEx = NEWCOM $PROGID_Agent

IF ISFALSE(ISOBJECT(AgentCtrlEx)) THEN

DisplayError("The Microsoft Agent Control 2.0 is not installed. 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

' Create the Characters interface

AgentChars = AgentCtrlEx.Characters

IF ISFALSE(ISOBJECT(AgentChars)) OR OBJRESULT <> %S_OK THEN

DisplayError("Error creating the Microsoft Agent Control 2.0 Characters interface.")

END IF

'Enable the Start button

CONTROL ENABLE CBHNDL, %ID_START

CASE %WM_COMMAND

SELECT CASE AS LONG CB.CTL

CASE %ID_START

IF CB.CTLMSG = %BN_CLICKED OR CB.CTLMSG = 1 THEN

' Load the Merlin agent into the Characters interface

AgentChars.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

' Load the Merlin character into the CharactersEx Interface

AgentCharsEx = AgentChars.Character("Merlin"$$)

IF ISTRUE(ISOBJECT(AgentCharsEx)) THEN

' Show the Merlin agent on the screen

AgentCharsEx.Show(0)

' Get the Width and Height of the Merlin agent

CharW = AgentCharsEx.Width

CharH = AgentCharsEx.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

AgentCharsEx.MoveTo(StartX, StartY)

' Have the Merlin agent play the trumpet

AgentCharsEx.Play("Announce"$$)

' Make the Merlin agent speak

SpeakTxt = "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

AgentcharsEx.Speak(SpeakTxt)

' Disable the Start button and enable the Stop button

CONTROL DISABLE CBHNDL, %ID_START

CONTROL ENABLE CBHNDL, %ID_STOP

END IF

END IF

CASE %ID_STOP

IF CB.CTLMSG = %BN_CLICKED OR CB.CTLMSG = 1 THEN

' Stop all actions by the Merlin agent and unload it

AgentCharsEx.Stop

AgentChars.Unload("Merlin"$$)

' Enable the Start button and disable the Stop button

CONTROL ENABLE CBHNDL, %ID_START

CONTROL DISABLE CBHNDL, %ID_STOP

END IF

END SELECT

CASE %WM_DESTROY

IF ISTRUE(ISOBJECT(AgentEvents)) THEN

' Detach the event handler interface

EVENTS END AgentEvents

END IF

END SELECT

END FUNCTION

FUNCTION PBMAIN () AS LONG

DIALOG NEW 0, "COM Browser Tutorial", 201, 122, 198, 115, %WS_POPUP OR %WS_BORDER OR %WS_DLGFRAME OR %WS_CAPTION OR _

%WS_SYSMENU OR %WS_MINIMIZEBOX OR %WS_CLIPSIBLINGS OR %WS_VISIBLE OR %DS_MODALFRAME OR %DS_3DLOOK OR _

%DS_NOFAILCREATE OR %DS_SETFONT, %WS_EX_CONTROLPARENT OR %WS_EX_LEFT OR %WS_EX_LTRREADING OR _

%WS_EX_RIGHTSCROLLBAR, TO hDlg

CONTROL ADD BUTTON, hDlg, %ID_START, "Start Agent", 5, 5, 50, 15, %WS_CHILD OR %WS_VISIBLE OR %WS_DISABLED OR _

%WS_TABSTOP OR %BS_TEXT OR %BS_PUSHBUTTON OR %BS_CENTER OR %BS_VCENTER, %WS_EX_LEFT OR %WS_EX_LTRREADING

CONTROL ADD BUTTON, hDlg, %ID_STOP, "Stop Agent", 5, 25, 50, 15, %WS_CHILD OR %WS_VISIBLE OR %WS_DISABLED OR _

%WS_TABSTOP OR %BS_TEXT OR %BS_PUSHBUTTON OR %BS_CENTER OR %BS_VCENTER, %WS_EX_LEFT OR %WS_EX_LTRREADING

CONTROL ADD LISTBOX, hDlg, %ID_EVENTLIST, , 70, 0, 125, 110, %WS_CHILD OR %WS_VISIBLE OR %WS_TABSTOP OR %WS_VSCROLL, _

%WS_EX_CLIENTEDGE OR %WS_EX_LEFT OR %WS_EX_LTRREADING OR %WS_EX_RIGHTSCROLLBAR

DIALOG SHOW MODAL hDlg, CALL DlgProc

END FUNCTION

11. | 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

12. | Open the "agent.inc" file in the IDE

13. | 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> (BYREF CharacterID AS WSTRING)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Input Activated"

END METHOD

METHOD DeactivateInput <3> (BYREF CharacterID AS WSTRING)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Input Deactivated"

END METHOD

METHOD CLICK <2> (BYVAL CharacterID AS WSTRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, _

BYVAL y AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Click at ("+FORMAT$(x)+","+FORMAT$(y)+")"

END METHOD

METHOD DblClick <4> (BYVAL CharacterID AS WSTRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, _

BYVAL y AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Double Click at ("+FORMAT$(x)+","+FORMAT$(y)+")"

END METHOD

METHOD DragStart <5> (BYVAL CharacterID AS WSTRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, _

BYVAL y AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Drag Start at ("+FORMAT$(x)+","+FORMAT$(y)+")"

END METHOD

METHOD DragComplete <6> (BYVAL CharacterID AS WSTRING, BYVAL BUTTON AS INTEGER, BYVAL Param_Shift AS INTEGER, BYVAL x AS INTEGER, _

BYVAL y AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Drag Complete to ("+FORMAT$(x)+","+FORMAT$(y)+")"

END METHOD

METHOD SHOW <15> (BYVAL CharacterID AS WSTRING, BYVAL Cause AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Character is showing"

END METHOD

METHOD HIDE <7> (BYVAL CharacterID AS WSTRING, BYVAL Cause AS INTEGER)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Character is hidden"

END METHOD

METHOD RequestStart <9> (BYVAL Request AS IDISPATCH)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Request Start"

END METHOD

METHOD RequestComplete <11> (BYVAL Request AS IDISPATCH)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "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)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Move to ("+FORMAT$(x)+","+FORMAT$(y)+")"

END METHOD

METHOD SIZE <23> (BYVAL CharacterID AS WSTRING, BYVAL Param_Width AS INTEGER, BYVAL Height AS INTEGER)

' Insert your code here

END METHOD

METHOD BalloonShow <24> (BYVAL CharacterID AS WSTRING)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Showing balloon text"

END METHOD

METHOD BalloonHide <25> (BYVAL CharacterID AS WSTRING)

LISTBOX INSERT hDlg, %ID_EVENTLIST, 1, "Hiding balloon text"

END METHOD

METHOD HelpComplete <26> (BYVAL CharacterID AS WSTRING, BYVAL Param_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> (BYREF Param_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

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

15. | 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.

16. | 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.

17. | 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