VDAMon v1.4 August 1999

Description The VDAMon control is an interface to some Windows API's which cannot be used directly from Visual Basic. It contains some features found in the DBAppMon VBX as well as "Message Blaster" functionality, tray icon support etc. Overview.
File Name VDGT.OCX
Class name VDAMon
About This control was developed by Visual Design Softscape AB. For more information, visit us at www.visual-design.se, or contact us at info@visual-design.se.
Distribution As soon as you have licensed the control, you may distribute it freely along with your EXE files.
Disclaimer Disclaimer

Release history

Aug 96 v0.1 First beta release.
Sep v1.0 No changes.
Nov v1.1 Added a way to create an own window and trap messages to it. Under Win95, the SubclassWindow method doesn't trap messages posted or sent from other applications.
Added a method to read environment variables.
Added CBT (computer based training) hook callbacks. This will detect window changes in the whole system.
June 98 v1.2 Recompiled with Visual C++ v5
Bugfix: An application monitored with the CreateDebugProcess which generated certain exceptions could freeze.
Aug 99 v1.4 New method: TaskList
New method: NotifyOnProcessID

Properties

*CBTProcEnabled *CBTUnownedWindowsOnly *CPTID

* = The property applies only to VDAMon


Methods

*ActivatePID *CreateDebugProcess *GetEnv *Hotkey
*NotifyOnProcessID *PtrRef *ShellWithNotify *SubclassNewWindow
*SubclassWindow *TaskbarIconAdd *TaskbarIconModify *TaskbarIconRemove
*TaskList *TrapMessage

* = The method applies only to VDAMon


Events

*CBTProc *CreateProcess *DebugProcessDone *ExitProcess
*Hotkey *TaskbarNotify *WndProc

* = The event applies only to VDAMon


Properties

CBTProcEnabled property

Description
This property enables or disables firing of the CBTProc event. The name CBT (computer based training) may seem a little confusing, but this is what it's called if you want to search for more information on, for example, MS Developer Network.

Usage
VDAMon.CBTProcEnabled [ = state ]

Remarks
This property is not available at design-time.

Data type
Boolean

Example
VDAMon1.CBTProcEnabled = True


CBTUnownedWindowsOnly property

Description
This property states that the CBTProc event shall only fire for windows that belongs for other processes than the current one (the program that's using this instance of VBAMon).

Usage
VDAMon.CBTUnownedWindowsOnly [ = state ]

Remarks
This property is not available at design-time.

Data type
Boolean

Example
VDAMon1.CBTUnownedWindowsOnly = True


CPTID property

Description
This property may be read directly after executing CreateDebugProcess or ShellWithNotify. It will return the ID of the newly created thread (as opposed to the return value of these methods, which is the ID of the process).

Usage
VDAMon.CPTID

Remarks
This property is not available at design-time and it is read only at run-time.

Data type
Long

Example
tid = VDAMon1.CPTID


Methods

ActivatePID method

Description
This is similar to the Visual Basic ActivateApp statement, but instead of taking an application title as argument, ActivatePID takes a process ID. Optionally, ActivatePID may restore the application if it is currently minimized.

Usage
[hwnd =] VDAMon.ActivatePID ( pid, RestoreMinimized )

Remarks
When RestoreMinimized is not zero, ActivatePID will sleep for a brief time (100ms) after activating the application's top level window. Thereafter will ActivatePID determine which window really got focus before investigating if the window is minimized or not. This has proved necessary since not all applications use the top level window as their main window.

Example
VDAMon1.ActivatePID pidNotepad, 2


CreateDebugProcess method

Description
This is similar to the Visual Basic Shell statement, but executes the new application as a debug process, which makes it possible to track the applications that process starts in turn.

Usage
[pid =] VDAMon.CreateDebugProcess ( filename, windowstyle )

Remarks
When a process is being debugged, the CreateProcess, ExitProcess and DebugProcessDone events will be fired.

Example
VDAMon1.CreateDebugProcess "notes.exe", vbMinimizedNoFocus

IMPORTANT: THIS METHOD CANNOT BE USED TO EXECUTE 16-BIT APPLICATIONS!


GetEnv method

Description
Reads an environment variable.

Usage
envvarvalue = VDAMon.GetEnv( envvarname )

Remarks
This method offers no advantages over the standard VB function Environ$, but may prove useful in other scripting languages.

Example
strPath = VDAMon1.GetEnv("PATH")


Hotkey method

Description
Registers a hotkey. Each time the hotkey is pressed, a Hotkey event is fired.

Usage
[ retval =] VDAMon.Hotkey( id, virtkey, modifier )

Remarks
To unregister a hot key, just register(!) it with it's negative ID.

Example
VDAMon1.Hotkey 1, Asc("A"), 5 'register alt+shift+a

VDAMon1.Hotkey -1, 0, 0 'unregister


NotifyOnProcessID method

Description
This method causes the ExitProcess event to fire when the supplies process ID terminates. This method is useful if you want to monitor an application you didn't start, or if you couldn't use ShellWithNotify to start it (one reason could be that you needed to use the ShellExecute API).

Usage
VDAMon.NotifyOnProcessID lPID

Remarks
The process ID could have been achieved using the GetWindowThreadProcessID or the TaskList method.


PtrRef method

Description
This method is used to de-reference pointer variables. This may be useful when trapping messages where some arguments (as wParam or lParam in the WndProc event) may be pointer variables.

Usage
value = VDAMon.PtrRef( pointer, vartype )

Remarks
Passing an invalid pointer value may cause a protection fault.

Example
strText = VDAMon1.PtrRef( lParam, vbString )


ShellWithNotify method

Description
This method works like the VB Shell function, but when the executed application ends, the ExitProcess event will be fired.

Usage
[ pid =] VDAMon.ShellWithNotify( filename, windowstyle )

Remarks
The thread started will just wait for the process to end using the WaitForSingleObject WIN32 function.

Example
pidNotepad = VDAMon1.ShellWithNotify( "Notepad", vbMaximizedFocus )


ShellWithNotify method

Description
This method works like the VB Shell function, but when the executed application ends, the ExitProcess event will be fired.

Usage
[ pid =] VDAMon.ShellWithNotify( filename, windowstyle )

Remarks
The thread started will just wait for the process to end using the WaitForSingleObject WIN32 function.

Example
pidNotepad = VDAMon1.ShellWithNotify( "Notepad", vbMaximizedFocus )


SubclassNewWindow method

Description
The name of this method is quite misleading, since it doesn't perform any subclassing whatsoever! The name has been chosen because of its close resemblance with the SubclassWindow method, which takes an existing window handle and begins spying upon it. In contrast, SubclassNewWindow creates a completely new window and makes it possible to trap it's messages the same way as if SubclassWindow had been used on that window.

This method has primarily been added because of problems with SubclassWindow when trying to detect messages posted or sent from other applications when running under Win95.

Usage
hWnd = VDAMon.SubclassNewWindow ( windowtitle )

Remarks
This method cannot be used at the same time as SubclassWindow, for that you must add several VDAMons to your project. To destroy the window (and stop receiving messages through WndProc) call SubclassWindow (note: not SubclassNewWindow), with a zero value as window handle.

Example
VDAMon1.SubclassNewWindow vbNullString
VDAMon1.TrapMessage WM_USER

VDAMon1.SubclassWindow 0 ' destroy the window


SubclassWindow method

Description
This method subclasses another window, which means that VDAMon is able to spy on all messages received by that window. Messages registered with the TrapMessage method is passed on to the WndProc event, where the application may perform further processing.

One typical use is to trap WM_DROPFILES messages. The sample code shows how to do this.

Usage
VDAMon.SubclassWindow hwnd

Remarks
In order to spy on several windows you must add several VDAMons to your project. To stop subclassing, pass a zero as window handle. When you stop subclassing, all messages added with TrapMessage are deleted.

Example
VDAMon1.SubclassWindow Picture1.hWnd ' begin subclassing
VDAMon1.TrapMessage WM_DROPFILES

VDAMon.SubclassWindow 0 ' stop subclassing


TaskbarIconAdd method

Description
This method will add an icon to the "tray" area on the taskbar. This may be used by an application that wishes to be invisible but still provide a way to communicate with the user.

Usage
[ retval =] VDAMon.TaskbarIconAdd( id, hIcon, ToolTip )

Remarks
When an icon has been added to the tray, all user interactions with the icon (mouse movements and clicks) will be fire a TaskbarNotify event. The TaskbarIconModify method may be used to change the icon appearace or the tool tip text later. When the taskbar icon is not needed anymore, or when the application ends, it must be removed using the TaskbarIconRemove method.

Example
VDAMon1.TaskbarIconAdd 1, Image1.Picture, "Click here"


TaskbarIconModify method

Description
Use this method to modify the icon or tool tip text for an icon added using TaskbarIconAdd.

Usage
[ retval =] VDAMon.TaskbarIconModify( id, hIcon, ToolTip )

Example
VDAMon1.TaskbarIconModify 1, 0, "Don't click here"


TaskbarIconRemove method

Description
Use this to remove an icon from the taskbar.

Usage
[ retval =] VDAMon.TaskbarIconRemove( id )

Remarks
VDAMon will not remove taskbar icons when the application ends. This must be done manually.

Example
VDAMon1.TaskbarIconRemove 1


TaskList method

Description
This method returns a list of all currently running process in the system, similar the the system Task Manager.

Usage
strTasks = VDAMon.TaskList

Remarks
The returned string is made up of CDLF separated lines, where each line is one process. Each line, in turn is made out of three parameters; lPID, hTask16 and the filname of the EXE file. lPID is the process ID and hTask16 is the 16-bit task handle if the process is a 16-bit app.

In order for this method to work one of these two conditions must be met:

Otherwise, and empty string is returned.


TrapMessage method

Description
After a window has been subclassed using the SubclassWindow method, this method is used to specify which messages the WndProc event will receive.

Usage
VDAMon.TrapMessage message

Remarks
This method will raise an error if no window has been subclassed before attempting to trap messages. To remove trapping of a message, pass it to TrapMessage as a negative value.

Example
VDAMon1.TrapMessage WM_SETTEXT 'pass this message to WndProc

VDAMon1.TrapMessage -WM_SETTEXT 'don't want to see it anymore


Events

CBTProc event

Description
The event is called when CBTProcEnabled is True and something happens (see below) to a window in the system.

Sub VDAMon_CBTProc ( message As Long, hWnd As Long, pid As Long, tid As Long )

Remarks
The following values for message may be received:

message description
0 The specified window was MOVED or RESIZED. You may call the GetWindowRect API function to determine the its new location and size.
1 The specified window was MINIMIZED or MAXIMIZED. You may call the IsZoomed or IsIconic API functions to find out which.
3 The specified window just became CREATED.
4 The specified window was DESTROYED. The hWnd passed is now invalid and may not be used for anything.
5 The specified window became the ACTIVE window.

This event is fired right after the action took place. Even so, under a pre-emptive multitasking operating system like WinNT or Win95, there is no guarantee that the window handle is still valid.


CreateProcess event

Description
This event is fired each time a new process is created within a process started using the CreateDebugProcess method.

Sub VDAMon_CreateProcess ( pidOrg As Long, pid As Long )

Remarks
If pidOrg = pid then this event is fired as a result of the process created with CreateDebugProcess being created, otherwise it is a process being created by that process or any of its children.

The sample program shows how this works by executing PBrush.exe with CreateDebugProcess. (PBrush.exe will execute Paint.exe and then exits, this would be tricky to monitor without VDAMon.)


DebugProcessDone event

Description
This event is fired when the last process created within a process started using the CreateDebugProcess method exits.

Sub VDAMon_DebugProcessDone ( pidOrg As Long )

Remarks
Note that the process pidOrg may have ceased to exist a long time ago. The sample code will show how this works by executing and monitoring PBrush.exe.


ExitProcess event

Description
This event is fired when a process exits. Only process (or children to a process) started using the CreateDebugProcess or ShellWithNotify methods are detected.

Sub VDAMon_ExitProcess ( pidOrg As Long, pid As Long, ExitCode As Long )


Hotkey event

Description
This event is fired each time a hotkey is pressed. Hotkeys are registered using the Hotkey method.

Sub VDAMon_HotKey ( id As Long )

Remarks
A normal action may be to activate the application. If you are writing some kind of shell application and wishes to activate other (running) applications, the ActivatePID method may prove invaluable.


TaskbarNotify event

Description
This event is fired when the user interacts with an icon in the taskbar tray, previously added using the TaskbarIconAdd method.

Sub VDAMon_TaskbarNotify ( id As Long, message As Long )

Remarks
Take appropriate action depending on message. You may want to include the following in your project to ease interception of the messages:

Public Const WM_LBUTTONDBLCLK = &H203
Public Const WM_LBUTTONDOWN = &H201
Public Const WM_LBUTTONUP = &H202
Public Const WM_MOUSEMOVE = &H200
Public Const WM_RBUTTONDBLCLK = &H206
Public Const WM_RBUTTONDOWN = &H204
Public Const WM_RBUTTONUP = &H205

Upon receiving a WM_RBUTTONDOWN, it is common practice to display a menu or properties window.


WndProc event

Description
This event is fired each time the subclassed window receives a message registered by TrapMessage.

Usage
Sub VDAMon_WndProc ( message As Long, wParam As Long, lParam As Long, retvalue As Long, bCancel As Boolean )

Remarks
For some messages, wParam or lParam may be pointer variables. These may be accessed using the PtrRef method.


Properties, methods & events by category

Process creation, monitoring and interaction

Message Blaster functions

Taskbar (Tray icon)

Hotkeys

Miscellaneous


Migrating DBAppMon

Since VDAMon is very different from DBAppMon, re-coding is definitely necessary, and since you're not likely to have more than one DBAppMon in your project anyway, no action has been taken to support migration; just load your 16-bit project and accept the error when DBAppMon.VBX cannot be loaded and then add VDAMon to the project.


Rev 2000-02-28