# vDebugDialog

Utility class to access debugging messages.

## Synopsis

Header:
  `<v/vdebug.h>`
Class name:
  vDebugDialog
Hierarchy:
  vModalDialog ->vDebugDialog

## Description

V provides built in debugging features. Most of the V classes contain debugging messages that are displayed on `stderr` or a special debugging information window. For Unix systems, `stderr` is usually the xterm window used to launch the V application.

NOTE: vDebugDialog is NOT currently implemented for Windows WIN32. This will be changed in the near future.

Several categories of debugging messages have been defined by V, and display of messages from different categories is controlled by the `vDebugDialog` class.

V provides several macros that can be used to insert debugging messages into your code. These are of the form `SysDebugN` for system code, and `UserDebugN` for your code. Display of these messages is controlled by the `vDEBUG` symbol, and the settings of the `vDebugDialog` class.

You define an error message using a `UserDebug` macro. Your message is a format string using the conventions of `sprintf`. You can have none to three values by using the corresponding `UserDebug` through `UserDebug3` macros. Each macro takes a debug type, a message, and any required values for the message format string. For example, `UserDebug(Misc,"myClass: %d\n", val)` will print the message ``myClass: xx'' when it is executed and the `Misc` debug message type is enabled.

If `vDEBUG` is not defined, your debugging messages will be null macros, and not occupy any code space. If `vDEBUG` is defined, then your messages will be conditionally displayed depending on their type.

By default, V starts with the `System` category `BadVals` on, and all three `User` categories on. Unix versions of V\ support a command line option that allows you to enable each option using the `-vDebug` command line switch. You include the switch `-vDebug` on the command line, followed by a single argument value made up of letters corresponding to the various debugging categories. If `-vDebug` is specified, all debugging categories except those specified in the value are turned off. The value for each category is listed in its header. For example, using the switch `-vDebug SUCDm` would enable debugging messages for both `System` and `User` constructors and destructors, as well as `System` mouse events. Note that the values are case sensitive.

## Debugging Categories

Each of the following debug categories can be set or unset using the `vDebugDialog` class. These category names are to be used as the first argument to the `UserDebug` macro.

*System (-vDebug S)

These are the messages defined using the `SysDebug` macro. These messages can sometimes be useful to determine if you are using the classes properly. The constructor, destructor, and command events are often the most useful system debug messages. Turning this off will disable all system messages.

*User (-vDebug U)

These are the messages defined using the `UserDebug` macros. Turning this off will disable all user messages, while turning it on enables those user messages that have been enabled.

*CmdEvents (-vDebug c)

This category corresponds to command events, which include menu picks and dialog command actions.

*MouseEvents (-vDebug m)

This category corresponds to mouse events, such as a button click or a move.

*WindowEvents (-vDebug w)

This category corresponds to window events, such as a resize or redraw.

*Build (-vDebug b)

This category corresponds to actions taken to build a window, such as adding commands to a dialog.

*Misc (-vDebug o)

This is a catch all category used for miscellaneous system messages. The `o` vDebug stands for other. You should probably use a UserAppN category for your miscellaneous messages.

*Text (-vDebug t)

These messages are primarily used by the `vTextCanvasPane` class, and are useful for debugging text display.

*BadVals (-vDebug v)

These messages are generated when a bad parameter or illegal value is detected. These can be most useful.

*Constructor (-vDebug C)

These messages are displayed whenever a constructor for an object is called. These messages can be very useful for tracking object creation bugs. You should try to have `UserDebug(Constructor,"X::X constructor")` messages for all of your constructors, and a corresponding Destructor message.

*Destructor (-vDebug D)

Messages from an object destructor.

*UserApp1, UserApp2, UserApp3 (-vDebug 123)

These are provided to allow you up to three categories of your own debugging messages.

### Example

To use the V debugging facilities, it is usually easiest to add a Debug command to a menu item - controlled by the `vDEBUG` symbol. Then add calls to `UserDebug` as needed in your code. This example shows how to define a Debug menu item, and then invoke the `vDebugDialog` to control debugging settings.

    #include <v/vdebug.h>

        vMenu FileMenu[] =
          {
            ...
    #ifdef vDEBUG
            {"-", M_Line, notSens,notChk,noKeyLbl,noKey,noSub},
            {"Debug", M_SetDebug,isSens,notChk,noKeyLbl,noKey,noSub},
    #endif
            ...
          };

        ...
        case M_SetDebug:
         {
            vDebugDialog debug(this);    // instantiate
            UserDebug(Misc,"About to show Debug dialog.\n");
            debug.SetDebug();            // show the dialog
            break;
         }
        ...