QuickStart: Customizing the Error Dialog

In place of the old VBE error dialog, we have provided a new programmable error dialog that is designed to be very flexible and provides full access to all of the advanced features provided by vbWatchdog.

To invoke the dialog, call it from your global error handler like this:

Public Sub MyGlobalErrorHandler()

    ErrEx.State = ErrEx.ShowErrorDialog()

End Sub

The new error dialog uses a basic form of HTML to allow formatting of the dialog contents.  The error dialog uses a template-based system.  This allows you to setup a simple template in your startup routine which is then effective throughout the running of your application.

There are actually two dialogs; the main Error dialog, and an optional Variables dialog that is opened from an optional button on the main dialog.  Both of these dialogs are fully customizable using the same set of properties.

To customize the main error dialog, we use the properties of the ErrEx.DialogOptions object.   To customize the variables dialog, we use the properties of the ErrEx.VariablesDialogOptions object.

To get started, download the Sample.mdb and use the "Customize the Error Dialog" button which will open up the main form that we use for testing out changes that we make to our error dialogs.

There are six menu options provided on the customization form (3 for the main dialog, 3 for the variables dialog):

There are two main HTML sections that you can edit, called "Main body" and "More info section".  The main body HTML is always visible, whereas the More Info section is only visible if the user presses the "More Info" button on your error dialog.  The "Callstack Section" and "Variables Section" are sub-sections that you can import into your main sections (we will discuss this in more detail later on this page).

This is how the two main sections look in the actual error dialog:

These are the basic HTML formatting tags that are supported:

<b>Bold</b>
<u>Underline</u>
<i>Italic</i>
<font face=Calibri size=10pt color=#808080 bgcolor=#F5FA70>Some Text</font>
<s>Strikethrough</s>
<br>Linefeed or vbCrLf

The pipe character ("|") can be used to represent column/indented data.  When the dialog is painted to the window, the vbWatchdog HTML parser will ensure that column data (separated by the pipe character) is aligned correctly.

The following standard tags can be used anywhere in the HTML

<VERSION>	equivalent to ErrEx.Version
<VBEVERSION>	equivalent to ErrEx.VBEVersion
<LOADEDDLLS>	equivalent to ErrEx.LoadedDLLs

The following special tags can be used to represent the data relating to the error being handled:

<ERRDESC>	equivalent to ErrEx.Desctipion
<ERRNUMBER>	equivalent to Hex(ErrEx.Number)
<ERRNUMBERHEX>	equivalent to ErrEx.NumberAsHex
<ERRDATETIME>	equivalent to Now()
<SOURCEPROJ>	equivalent to ErrEx.SourceProject
<SOURCEMOD>	equivalent to ErrEx.SourceModule
<SOURCEPROC>	equivalent to ErrEx.SourceProcedure
<SOURCELINENUMBER>	equivalent to ErrEx.SourceLineNumber
<SOURCELINECODE>	equivalent to ErrEx.SourceLineCode Can also specify a NULLVALUE string, e.g.: <SOURCELINECODE NULLVALUE='Unavailable'>
<SOURCEPROJECTCOMPILED>	equivalent to ErrEx.SourceProjectIsCompiled
<SOURCEPROJECTSAVED>	equivalent to ErrEx.SourceProjectIsSaved
<SOURCEFILENAME>	equivalent to ErrEx.SourceProjectFilename
<SOURCEPROJECTCONDITIONALARGS>	equivalent to ErrEx.SourceProjectConditionalCompilationArgs
<CALLSTACK>	parses DialogOptions.HTML_CallStackItem for each call in the callstack.

To display callstack data, you must use the <CALLSTACK> tag inside one of the main sections (either the Main body, or more usually in the More info section).  When vbWatchdog encounters the <CALLSTACK> tag, it will then import the HTML code that you have specified in the "Callstack Section" for each call frame in the callstack.

Here's a list of the special tags that are available in the "Callstack Section":

<SOURCEPROJ>	equivalent to ErrEx.Callstack.ProjectName
<SOURCEMOD>	equivalent to ErrEx.Callstack.ModuleName
<SOURCEPROC>	equivalent to ErrEx.Callstack.ProcedureName
<SOURCELINENUMBER>	equivalent to ErrEx.Callstack.SourceLine
<SOURCELINECODE>	equivalent to ErrEx.Callstack.SourceLineCode Can also specify a NULLVALUE string, e.g.: <SOURCELINECODE NULLVALUE='Unavailable'>
<SOURCEPROJECTCOMPILED>	equivalent to ErrEx.Callstack.ProjectIsCompiled
<SOURCEPROJECTSAVED>	equivalent to ErrEx.Callstack.ProjectIsSaved
<SOURCEFILENAME>	equivalent to ErrEx.Callstack.ProjectFilename
<SOURCEPROJECTCONDITIONALARGS>	equivalent to ErrEx.Callstack.ProjectConditionalCompilationArgs
<VARIABLES>	parses DialogOptions.HTML_VariablesItem for each variable declared in the current procedure.

To display variable information, you must use the <VARIABLES> tag inside of your Callstack Section.  When vbWatchdog encounters the <VARIABLES> tag, it will then import the HTML code that you have specified in the "Variables Section" for each variable identified in the callframe that is being displayed.

Finally, here's a list of the special tags that are available in the "Variables Section":

<VARSCOPE>	equivalent to ErrEx.Callstack.VariablesInspector.ScopeDesc Can also specify custom values for each variable scope type, e.g.: <VARSCOPE LOCAL='local', PARAM='param', MODULE='mod', STATIC='static'>
<VARNAME>	equivalent to ErrEx.Callstack.VariablesInspector.Name
<VARTYPE>	equivalent to ErrEx.Callstack.VariablesInspector.TypeDesc
<VARVALUE>	equivalent to ErrEx.Callstack.VariablesInspector.ValueDesc

There are two types of buttons: standard buttons and custom buttons. Standard buttons have a BUTTONACTION_ associated with them. Custom buttons are created by specifying the name of a callback VB routine that vbWatchdog will call when the button is pressed.

Classic VB6 users: the name specified for the callback routine will instead be used to call a method on your EvalObject instance.

Most of these properties are self explanatory. For background colors you can now specify 2 colors and a gradient fill type. For example, to create a gradient effect for the main background, set two different colors for the MainBackColor and MainBackColor2 properties, and then set the MainBackFillType to an allowed value. Allowed values for the fill type are currently between 0 and 8. Each of these filltype values offers a different type of gradient (e.g. horizontal, vertical, corner etc).

You can also customize the dialog image here (to a BMP bitmap file), and the sample application will then integrate the binary data of the BMP file into the generated VB code at the end. vbWatchdog supports 4 bit, 8 bit, 24 bit and 32 bit (inc alpha channel) bitmap images (16 bit and monochrome bitmaps are not supported).

You can now create custom tags in your HTML template strings.  This feature enables you to add variable data to your error dialogs at runtime without having to change the actual HTML template.

To define a new custom tag, just include it in the HTML template encased in tag brakets and with a leading exclamation mark, like this:

<!MyCustomField>

In your global error handler, before you call ErrEx.ShowErrorDialog, you can now set the value of the custom tag by setting:

ErrEx.CustomVars("MyCustomField") = "My data..."

You can pass a maximum of 512 custom named tags in this manner. As a bonus, you can also use custom tags (and the normal context tags) in the WindowCaption string.

Here's an example for using the new OnKeyDown event available in v3 of vbWatchdog:

Public Sub Startup()
    ErrEx.Enable "OnError"
    ErrEx.DialogOptions.OnKeyDown = "DoKeyDown"
End Sub

Public Function DoKeyDown(ByVal Key As Long, _
                          ByVal ShiftState As Boolean, _
                          ByVal CtrlState As Boolean, _
                          ByVal AltState As Boolean) As OnErrorStatus
    If CtrlState = True And Key = vbKeyC Then
        ErrEx.Helper_SetClipboardText "An error occurred: " & Hex(ErrEx.Number) & ", " & ErrEx.Description 
    End If
End Function

TIP: providing a return value in your DoKeyDown routine will close the dialog, returning the given OnErrorStatus value as the return value of the ShowErrorDialog call in your global error trap.