Toolbar internal events

These events are fired by the toolbar core host. 

OnTimeout - you receive call to this routine whenever a timeout previously set through Host.Timeout has expired.

Prototype: Sub OnTimeout(timerId)
Parameters: 
timerId - The id of the timeout. The Id is obtained as return value of Host.Timeout when the timeout is set.

OnShow - Fired when the toolbar changes its visible state - from hidden to visible or from visible to hidden.

Prototype: Sub OnShow(bShow)
Parameters:
bShow - indicates if the toolbar is being shown or hidden. True - toolbar becomes visible, False - toolbar becomes hidden.

Remarks: You can use this event to enable/disable the toolbar operations (or part of them) if it is supposed to work only when visible. The event occurs when the user unselects the toolbar from the menu (View->Toolbars). If the toolbar is once shown it is not unloaded until the browser window is closed.

OnUnload - Fired just before the toolbar unloads.

Prototype: Sub OnUnload()
This is a good place to uninitialize your script if it is needed - for example close files or database(s) kept open during the whole lifetime of the toolbar. 

Browser main window events

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.

Frequently needed

OnTitleChange - Fires when the browser title changes

Prototype: Sub OnTitleChange(title)
Parameters:
title - the text of the title.

OnNewWindow - Fires whenever a new browser window is about to be created (a pop-up).

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.

OnStatusTextChange - fired when the status bar text is changed.

Prototype: Sub OnStatusTextChange(text)
Parameters:
text -  the text of the statusbar.

OnProgress - Reports the progress of a page download.

Prototype: Sub OnProgress(progress, progressMax)
Parameters:
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. 

OnDownloadBegin - Fires when the browser begins a download of a page.

Prototype: Sub OnDownloadBegin()

OnDwonloadComplete - Fires when a download completes.

Prototype: Sub OnDwonloadComplete()

OnBeforeNavigate - Fires just before the navigation to a new page begins.

Prototype: Function OnBeforeNavigate(Frame,url,Flags,TargetFrameName,PostData,Headers)
Parameters:
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 it)  
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).

Interesting ideas: 
- 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 manner. 
- 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.

OnNavigateComplete - Fires when the navigation to an URL completes.

Prototype: Sub OnNavigateComplete(Frame,url)
Parameters:
Frame - Frame in which the event occurs. It is a WebBrowser2 object.
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! 

OnDocumentComplete - Fires when the document displayed in a frame is ready to use.

Prototype: Sub OnDocumentComplete(Frame,url)
Parameters:
Frame - Frame in which the event occurs. It is a WebBrowser2 object.
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.

Rarely useful

OnStatusBar - Fires when the status bar of the browser is shown or hidden

Prototype: Sub OnStatusBar(bShown)
Parameters:
bShown - True if the status bar is shown and False when it is hidden

OnVisible - Fires when the browser is to be hidden or shown (as whole)

Prototype: Sub OnVisible(bShown)
Parameters:
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 compatibility needs.

OnCommandStateChange - Fires when a command changes its state

Prototype: Sub OnCommandStateChange(cmd,State)
Parameters:
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.

OnToolbar - Fires when the IE toolbars are shown or hidden

Prototype: Sub OnToolbar(bShown)
Parameters:
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.

OnMenuBar - Fires when the IE menu bar is shown or hidden

Prototype: Sub OnMenuBar(bShown)
Parameters:
bShown - True if the menu is shown and False if it becomes hidden.

OnFullScreen - Fires when the IE goes to full screen mode or to normal mode from full screen.

Prototype: Sub OnFullScreen(bFullScreen)
Parameters:
bFullScreen - True if IE is in full screen mode and False otherwise.

OnQuit - Fires when the browser is ready to quit.

Prototype: Sub OnQuit()

Remarks: Not always fired - do not count on it! Use OnUnload instead.

OnTheaterMode - Fires when the browser goes to Theater mode or to normal mode from theater mode.

Prototype: Sub OnTheaterMode(bMode)
Parameters:
bMode - True for theater mode, False otherwise.

OnPropertyChange - Fires when a property changes

Prototype: Sub OnPropertyChange(name)
Parameters:
name - the property name. See WebBrowser2.PutProperty and GetProperty.

Toolbar user interface events

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

OnToolbarDocumentComplete - Like the OnDocumentComplete, but this is fired by the toolbar user interface and not by the browser.

OnToolbarNewWindow - Like the OnNewWindow, but this is fired by the toolbar user interface and not by the browser.

OnToolbarDownloadBegin - Like the OnDownloadBegin, but this is fired by the toolbar user interface and not by the browser. 

OnToolbarDwonloadComplete - Like the OnDwonloadComplete, but this is fired by the toolbar user interface and not by the browser.

OnToolbarBeforeNavigate - Like the OnBeforeNavigate, but this is fired by the toolbar user interface and not by the browser.

OnToolbarNavigateComplete - Like the OnNavigateComplete, but this is fired by the toolbar user interface and not by the browser.

Menu events (version 1.1 and later)

OnMenuSelect - fires when the user passes with the mouse cursor over a clickable menu item.

Prototype: Sub OnMenuSelect(sender)
Parameters:
sender  - the VarioMenuItem object that fired the event.

Sample:

Sub OnMenuSelect(sender)
  Toolbar.document.Body.all("tbText").innerText = sender.Info
End Sub

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.

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

Prototype: Sub <EventHandlerName>(sender)
Parameters:
sender  - the VarioMenuItem object that fired the event.

Sample:

Assume that in the menu definition the Handler has been set this way:

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:

Sub OnSampleMenuCommand(sender)
  Host.MsgBox "You clicked the menu item " & sender.Caption & " which has Info: " & sender.Info
End Sub

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.

Suggestions:

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