These events are fired by the main browser window - i.e. in
response to events that occur in the pages browsed by the user.
Handling them you can hook to everything the browser allows and
obtain information about what is happening in the browser or
prevent some actions - such as cancel navigation, cancel new
window and so on. The events are split in two groups - Frequently
needed and Rarely useful. The second group is rarely
needed for anything, but it is supported in case it is needed.
the first group contains the events that reflect the navigation
and the actions of the user.
- Fires when the browser title changes
Prototype: Sub OnTitleChange(title)
title - the text of the title.
- Fires whenever a new browser window is about to be created
Prototype: Function OnNewWindow()
Return value: If you return True the
action is cancelled. If you return nothing or False the new
window will be created.
Remarks: Note that you are not informed here why the
window opens. To determine when to allow the action you need
to collect information from other events and preserve it
while it is needed.
- fired when the status bar text is changed.
Prototype: Sub OnStatusTextChange(text)
text - the text of the statusbar.
- Reports the progress of a page download.
Prototype: Sub OnProgress(progress, progressMax)
progress - an integer value that indicates the
current progress. It is > 0 and < progressMax. If the
download is complete it should be -1.
progressMax - The maximum progress value (from which
progress is part).
Rameraks: Handle this event only if it is crucial for the
operation. It is fired too often and you may lower the
browser performance considerably. If you need this event
make your code as fast as possible.
Note that the progress reported is not reliable. The
report comes from the protocol handler used by IE and they
are not always able to determine the progress correctly. If
you are doing something important in response to the
progress you should implement a backup logic. For example
you may assume that when OnDwonloadComplete is fired the
progress is 100%. Note also that the event carries no
information about the frame, thus you cannot be sure what
has caused it without additional efforts.
- Fires when the browser begins a download of a page.
Prototype: Sub OnDownloadBegin()
- Fires when a download completes.
Prototype: Sub OnDwonloadComplete()
- Fires just before the navigation to a new page begins.
Prototype: Function OnBeforeNavigate(Frame,url,Flags,TargetFrameName,PostData,Headers)
Frame - The frame or window from which the navigation
is invoked. This is a WebBrowser2 object.
url - URL to which to navigate
Flags - not used in the known IE versions (ignore
TargetFrameName - The name of the target frame. Empty if
the navigation will occur in the same frame.
PostData - If the navigation is caused by a form post
this will contain the post data.
Headers - Any additional headers the browser is going to
send to the server.
Return value: If the event returns True the navigation is
cancelled, otherwise (False or no return value) the
navigation will proceed.
Remarks: This is one of the most useful events for any
application that wants to interfere with the browser
operations. Using this event the application can prevent the
browser from opening/downloading certain resources and for
example replace the browser functionality. One good example
is a download manager - if the url specifies a zip
for example the toolbar application can save it to a list
and pass it for further download by external application or
can perform the download in the background and so on.
The information supplied by the event is enough to allow
the toolbar script perform the action instead of the
browser. Many developers who resort to IE toolbars do this
exactly because sometimes it is useful to perform custom
handling of certain resources (for example deal in a
specific manner with documents from the intranet and so on).
- A company wide list of sites can be handled on a local
server and a toolbar application can check it from any
browser in the company and if the site is there alter the
browser operation - deny navigation to dangerous sites,
handle certain resources from these sites in specific
- An intranet download manager on a server machine. You can
build a central database in the intranet, record any
download attempt there and cancel it locally. Then the
central application can download the file and store it on a
the intranet server where all the users can access it.
- Antivirus checking. You can implement the download on your
own (using NetStreams for example) and pass the downloaded
file to an antivirus after the download.
- Fires when the navigation to an URL completes.
Prototype: Sub OnNavigateComplete(Frame,url)
Frame - Frame in which the event occurs. It is a
url - The URL (or path if it is a local path) to
which the browser has completed navigation.
Remarks: Note that this event only indicates that browser
has the resource obtained, but it does not mean that the
resource is prepared for further use. This is especially
important when a navigation to a new page is expected by the
toolbar script in order to dig into the new page's DHTML
object model. In such case you must wait until the
OnDocumentComplete is fired before digging in!
- Fires when the document displayed in a frame is ready to
Prototype: Sub OnDocumentComplete(Frame,url)
Frame - Frame in which the event occurs. It is a
url - The URL (or path if it is a local path) of the
document shown there.
Remarks: This event can be fired by a frame. When it is
received you can dig into the document because the event
means that the document is completed and ready to respond to
calls into its object model.
Recommendation: This is one of the most important events
together with OnBeforeNavigate. Most of the toolbar
applications that can be built would want to handle pairs of
these events in order to control or invoke navigation and do
some work when it is completed. The application should be
aware that this is not a guaranteed sequence - the user may
cancel the navigation or click a link in the middle of the
action (if you allow it). As the possibilities rise in
number it will be become harder to identify each navigation
process and handle all the possible cases. One of the
easiest ways to deal with this is to create a timeout when
you invoke or track a navigation process. Then you can
inspect all the completed navigations and try to identify if
one of them corresponds to a tracked/invoked navigation of
interest and perform further work if that is so. Handling a
timeout for each expected navigation will give you way to
stop waiting for it to complete when it is no longer
reasonable to expect it to complete successfully. Obviously
tracking many navigation processes requires you to implement
some kind of a register for the tracked navigation
processes. You need to remove from it each process that is
completed or failed. The success is usually easy to identify
but the failure may differ in nature - for example a
redirection to an unexpected URL may be considered failure
or success depending on the circumstances or the download
may be too slow and so on. Using a timeout with a carefully
selected value allows you to establish ultimate failure
identification no matter what else happens and if every
other technique you implement fails. Do not forget that the
browser may have other plug-ins installed which may do a
similar work and may alter the browser behavior. Identifying
a failure by using a standard error pages URL-s for instance
is a bad idea - because the browser may have a plug-in that
replaces them, perform a search on 404 errors for example or
do something else you can't guess. Thus a final resort
method to identify failures will guarantee that your code
will never fail.
- Fires when the status bar of the browser is shown or hidden
Prototype: Sub OnStatusBar(bShown)
bShown - True if the status bar is shown and False
when it is hidden
- Fires when the browser is to be hidden or shown (as whole)
Prototype: Sub OnVisible(bShown)
bShown - True if the browser is shown and False
when it is hidden
Remarks: This is practically unusable for the toolbar
applications. It is kept just for potential future
- Fires when a command changes its state
Prototype: Sub OnCommandStateChange(cmd,State)
cmd - integer identifying the command
State - True - enabled, False - Disabled
Remarks: This can be sometimes useful if you need to
adjust your toolbar UI or behavior depending on the state of
the commands in the browser. The commands correspond to the
Microsoft Internet Explorer menu identifiers.
- Fires when the IE toolbars are shown or hidden
Prototype: Sub OnToolbar(bShown)
bShown - True if the toolbars are shown and False if
they become hidden.
Remarks: This concerns the entire toolbar area which
contains all the IE toolbars including yours.
- Fires when the IE menu bar is shown or hidden
Prototype: Sub OnMenuBar(bShown)
bShown - True if the menu is shown and False if it
- Fires when the IE goes to full screen mode or to normal mode
from full screen.
Prototype: Sub OnFullScreen(bFullScreen)
bFullScreen - True if IE is in full screen mode and
- Fires when the browser is ready to quit.
Prototype: Sub OnQuit()
Remarks: Not always fired - do not count on it! Use
- Fires when the browser goes to Theater mode or to normal
mode from theater mode.
Prototype: Sub OnTheaterMode(bMode)
bMode - True for theater mode, False otherwise.
- Fires when a property changes
Prototype: Sub OnPropertyChange(name)
name - the property name. See WebBrowser2.PutProperty
These events are fired from the user interface HTML shown in
the toolbar. They are subset of the events WebBrowser object
fires. The events that are inappropriate are ignored internally.
In most cases the toolbar will load only once during the
initialization and you will not need to handle any of them, but
if you are creating a toolbar that reloads its UI you may need
to handle at least OntoolbarDocumentComplete in order to
determine when it is safe to access the new HTML user
- fires when the user passes with the mouse cursor over a
clickable menu item.
Prototype: Sub OnMenuSelect(sender)
sender - the VarioMenuItem
object that fired the event.
Toolbar.document.Body.all("tbText").innerText = sender.Info
The sample code above uses a SPAN or DIV element in the
toolbar's DHTML design for example. It shows there the value
of the Info
property of the menu item.
Remarks: In the default distributions (not the samples that
may use it) this event is disabled you will need to edit the
toolbar.cfg to enable it. It is disabled in order to save
processing power in case the event is not used.
events - There is no predefined event handler name for
these events. They are assigned by the application during the
menu structure definition. See the Menu
definition overview and the details about the Handler
Prototype: Sub <EventHandlerName>(sender)
sender - the VarioMenuItem
object that fired the event.
Assume that in the menu definition the Handler has been set
Dim i,m, root
Set root = Host.Menus.MenuTree
Set m = root.CreateSubItem("MyContextMenu")
Set i = m.CreateSubItem("itm_0")
i.Caption = "IE ScriptBar Overview"
i.Handler = "OnSampleMenuCommand"
i.HandlerNamespace = ""
i.Info = Settings("BasePath") & "info.htm"
Then after the menu "MyContextMenu" is shown we
handle the user choiice by:
Host.MsgBox "You clicked the menu item " & sender.Caption & " which has Info: " & sender.Info
By inspecting the VarioMenuItem's properties the handler
routine is able to determine what must be done. During the
menu definition the application usually sets the Info
property with data that makes the job of the handler routine
simple. The way you determine the meaning of a menu item is
up to you - it can vary from setting a key string which is
then used to determine the operation to object or even
collection (you can use VarDictionary
for instance) that contains all or most of the data the
handler would need in order to respond to the user action.
The best way is usually in the middle - you are free to
choose any technique that will make your work easier.
Most often it is convenient to use a set of menu item
click handlers. The best approach is to use one handler for
each kind of operation you need to perform. For example one
handler for simple navigation to an URL, one handler for
state information, another handler for save state/data and
so on. Of course, you can implement separate event handler
for every menu item - but in most cases this will be