This chapter covers V utility classes and functions. Whenever possible, any corresponding native utility has been used to implement these classes. For example, you will get the standard file interface dialog for Windows.
Since the Athena implementation has no corresponding native utilities, the V utility classes have been implemented for Athena using standard V classes as much as possible. Thus, the source code for the Athena version of these utilities provides an excellent example of V for study.
The classes and objects covered in this chapter include:
Utility class to access debugging messages.
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. For other environments, the debugging window is system dependent.
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.
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.
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.
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.
This category corresponds to command events, which include menu picks and dialog command actions.
This category corresponds to mouse events, such as a button click or a move.
This category corresponds to window events, such as a resize or redraw.
This category corresponds to actions taken to build a window, such as adding commands to a dialog.
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.
These messages are primarily used by the vTextCanvasPane class, and are useful for debugging text display.
These messages are generated when a bad parameter or illegal value is detected. These can be most useful.
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.
Messages from an object destructor.
These are provided to allow you up to three categories of your own debugging messages.
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;
}
...
A utility class to select or set a file name.
This utility class provides a dialog interface for selecting filenames. It can be used either to select an input file name, or verify or change an output file name. This utility does not open or alter files -- it simply constructs a legal file name for use in opening a file.
The vFileSelect constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.
You provide a prompt for the user, such as ``Open File.'' The user then uses the dialog to select or set a file name. FileSelect returns True if the user picked the OK button, and False if they used the Cancel button.
The filename will be filled in to the filename buffer of maximum length maxLen. The full path of the file will be included with the file name.
You can also provide a list of filter patterns to filter file extensions. If you don't provide a filter list, the default filter of ``*'' will be used. Each item in the filter list can include a list of file extensions separated by blanks. You can provide several filtering options. The first filter in the list will be the default. Only leading ``*'' wild cards are supported.
The filterIndex reference parameter is used to track which filter the user selected. After FileSelect returns, filterIndex will be set to the index of the filter list that the user last selected. For the best interface, you should remember this value for the next time you call FileSelect with the same filter list so that the user selected filter will be preserved.
You should use FileSelect to open a new or existing file. If the user is being asked to save a file (usually after picking a Save As menu choice), use the FileSelectSave method. On some platforms, there will be no difference between these two methods (X, for example). On other platforms (Windows, for example), different underlying system provided file dialogs are used. To your program, there will be no difference in functionality.
The following is a simple example of using vFileSelect.
static char* filter[] = // define a filter list
{
"*", // all files
"*.txt", // .txt files
"*.c *.cpp *.h", // C sources
0
};
static int filterIndex = 0; // to track filter picked
char name[100];
vFileSelect fsel(this); // instantiate
int oans = fsel.FileSelect("Open file",name,99,filter,filterIndex);
vNoticeDialog fsnote(this); // make an instance
if (oans && *name)
(void)fsnote.Notice(name);
else
(void)fsnote.Notice("No file name input.");
A utility class to select or set a file name.
This class provides the FontSelect method to set the font being used. This class provides a platform independent way to change fonts. Depending on the platform, the user will be able to select many or most of the fonts available on the platform. On Windows, for example, the standard Windows font selection dialog is be used. On X, a relatively full set of fonts are available.
The vFontSelect constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.
This method displays a dialog that lets the user select font characteristics. If possible, the native font selection dialog will be used (e.g., Windows). The font dialog will display the current characteristics of the font object, and change them upon successful return. A false return means the user selected Cancel, while a true return means the user finished the selection with an OK.
A utility class to display a message.
This simple utility class can be used to display a simple message to the user. The utility displays the message, and then waits for the user to enter to press OK.
The vNoticeDialog constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.
You provide a prompt for the user. If the message contains 'backslashn' newlines, it will be shown on multiple lines.
The following is a simple example of using vNoticeDialog.
#include <v/vnotice.h>
...
vNoticeDialog note(this); // instantiate a notice
(void)note.Notice("This is a notice.");
A utility class to get a text reply from the user.
This simple utility class can be used to obtain a text reply from the user. The utility displays a message, and then waits for the user to enter a reply into the reply field. The user completes the operation by pressing OK or Cancel.
The vReplyDialog constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.
You provide a prompt for the user. The text the user enters will be returned to the buffer reply of maximum length maxLen. Reply will return the value M_OK or M_Cancel.
The following is a simple example of using vReplyDialog.
#include <v/vreply.h>
...
vReplyDialog rp(this); // instantiate
char r[100]; // a buffer for reply
(void)rp.Reply("Please enter some text.",r,99);
vNoticeDialog note(this); // instantiate a notice
if (*r)
(void)note.Notice(r);
else
(void)note.Notice("No text input.");
A class for getting timer events.
This is a utility class that allows you to get events driven by the system timer. The accuracy and resolution of timers on various systems varies, so this should be used only to get events on a more or less regular basis. Use the C library time routines to get real clock time.
This constructs a timer object. The timer doesn't run until you start it with TimerSet. To make a timer useful, you can override the constructor to add a pointer to a window, and then use that pointer from within your TimerTick method to do something in that window: myTimer(vWindow* useWindow).
This starts the timer going. The timer will call your overridden TimerTick method approximately every interval milliseconds until you stop the timer. Most systems don't support an unlimited number of timers, and TimerSet will return 0 if it couldn't get a system timer.
Calling this stops the timer, but does not destruct it.
This method is called by the system every interval milliseconds (more or less). The way to use the timer is to derive your own class, and override the TimerTick method. Your method will be called according to the interval set for the timer. Note that you can't count on the accuracy of the timer interval.
A utility class to display a message, and get a Yes or No answer.
This simple utility class can be used to display a simple message to the user. The utility displays the message, and then waits for the user to enter to press Yes, No, or Cancel.
The vYNReplyDialog constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.
You provide a prompt for the user. The user will then press the Yes, No, or Cancel buttons. AskYN returns a 1 if the user selected Yes, a 0 if they selected No, and a -1 if they selected Cancel.
The following is a simple example of using vYNReplyDialog.
#include <v/vynreply.h>
...
vYNReplyDialog ynd(this); // instantiate a notice
int ans = ynd.AskYN("Exit. Are you sure?);
if (ans == 1)
exit(0);
Several useful utility functions.
V provides several utility functions that can often help with software portability (and can just be useful). These are free subprograms -- not a member of any specific class.
This will convert the unsigned char in b to a Hex character string in str. You need to make str big enough to hold the string.
This will convert the integer in intg to a character string in str. You need to make str big enough to hold the string.
This will convert the long integer in intg to a character string in str. You need to make str big enough to hold the string.
This will convert the character string in str into a long integer. You can cast to get ints.
This will return a string representation of the current local time to the string tm. The format will be ``HH:MM:SS AM''. If you need a different format, you will need to use the C functions time, localtime, and strftime directly.
This will return a string representation of the current local date to the string dt. The format will be ``MM/DD/YY''. If you need a different format, you will need to use the C functions time, localtime, and strftime directly.
The utility bmp2vbm converts a Window or OS/2 .bmp format bitmap file into a .vbm V icon bitmap format file. The .vbm file is then used with a vIcon object definition. The bmp2vbm utility will not convert all .bmp files. Specifically, it can't handle old format .bmp files, nor can it handle compressed .bmp files.
Windows has many tools to generate .bmp files. For X, the widely available tool xv can generate .bmp files from various source formats.
Bmp2vbm is a command line tool - run it from a Unix prompt, or from an MSDOS box on Windows. The command line format is: bmp2vbm inputname outputname iconname. You should specify only the base file names: bmp2vbm will automatically supply the .bmp and .vbm extension. The iconname specifies the name used to generate the date (e.g., iconname_bits).
The directory v/icons includes over 30 different monochrome icons in .vbm format suitable for building command pane tool bars. Most of these icons were derived from various Windows sources, and I would encourage their use for the standard functions they define. Some of these include creating a new file (new.vbm), opening an existing file (open.vbm), cut, copy, and paste (*.vbm), printing (print.vbm), and so on.
There is a demo program in the v/icons directory that can be compiled and used to see what all the icons look like. All the icons are 16 by 16 bits, and will match standard buttons in height on Windows. The height of standard buttons on X depends on the default system font.
As usual, contributions of other V icons is more than welcome. I hope to build up the icons directory to several hundred icons.