The V C++ GUI Framework:vDebugDialog

From EDM2
Jump to: navigation, search

Utility class to access debugging messages.

Synopsis

Header:
[vquickr.htm#vDebugDialog <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; } ...