[Table of Contents]
[Previous Chapter]
[Next Chapter]
[Object Central Home]
The V C++ GUI Reference Manual - Vers. 1.20 - 6/30/98
Copyright © 1998, Bruce E. Wampler
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:
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.
*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.
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.
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.
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.
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 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.
The following is a simple example of using vNoticeDialog.
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.
The following is a simple example of using vReplyDialog.
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 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.
The following is a simple example of using vYNReplyDialog.
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.
The utility bmp2vbm converts a Window or OS/2 .bmp
format bitmap file into a .vbm
Vicon 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).
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
Vicons is more than welcome.
I hope to build up the icons directory to several hundred icons.
Chapter 9
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.
Utilities
9.1 vDebugDialog
Utility class to access debugging messages.
Synopsis
Description
Debugging Categories
Example
#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;
}
...
9.2 vFileSelect
A utility class to select or set a file name.
Synopsis
Description
Methods
vFileSelect(vBaseWindow* win)
vFileSelect(vApp* app)
int FileSelect(const char* prompt, char* filename, const
int maxLen, char** filterList, int& filterIndex)
int FileSelectSave(const char* prompt, char* filename, const int
maxLen, char** filterList, int& filterIndex)
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.
Example
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.");
9.3 vFontSelect
A utility class to select or set a file name.
Synopsis
Description
Methods
vFontSelect(vBaseWindow* win)
vFontSelect(vApp* app)
int FontSelect(vFont& font, const char* msg = "Select Font")
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.
9.4 vNoticeDialog
A utility class to display a message.
Synopsis
Description
New Methods
vNoticeDialog(vBaseWindow* win)
vNoticeDialog(vApp* app)
void Notice(const char* prompt)
You provide a prompt for the user. If the message
contains 'backslashn' newlines, it will be shown on multiple
lines.
Example
#include <v/vnotice.h>
...
vNoticeDialog note(this); // instantiate a notice
(void)note.Notice("This is a notice.");
9.5 vReplyDialog
A utility class to get a text reply from the user.
Synopsis
Description
New Methods
vReplyDialog(vBaseWindow* win)
vReplyDialog(vApp* app)
int Reply(const char* prompt, char* reply, const int maxLen, char* dflt = "")
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.
Use dflt to provide a default reply.
Example
#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.");
9.6 vTimer
A class for getting timer events.
Synopsis
Description
New Methods
vTimer
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).
int TimerSet(long interval)
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.
void TimerStop()
Calling this stops the timer, but does not destruct it.
void TimerTick()
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.
9.7 vYNReplyDialog
A utility class to display a message, and get a Yes or No answer.
Synopsis
Description
New Methods
vYNReplyDialog(vBaseWindow* win)
vYNReplyDialog(vApp* app)
int AskYN(const char* prompt)
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.
Example
#include <v/vynreply.h>
...
vYNReplyDialog ynd(this); // instantiate a notice
int ans = ynd.AskYN("Exit. Are you sure?);
if (ans == 1)
exit(0);
9.8 Utility Functions
Several useful utility functions.
Synopsis
Description
void ByteToStr(unsigned char b, char* str)
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.
void IntToStr(int intg, char* str)
This will convert the integer in intg to a character
string in str. You need to make str big enough
to hold the string.
void LongToStr(long intg, char* str)
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.
long StrToLong(char* str)
This will convert the character string in str into a long
integer. You can cast to get ints.
void vBeep()
This utility routine will sound an audible beep.
void vGetcmdIdIndex(ItemVal cmdId, CommandObject *cmdObj)
Sometimes when you work with a CommandObject array to define a
dialog, you need to access the elements of a particular item in
the array. This is especially true for manipulating lists.
This routine will return the index into a CommandObject array
of an entry with the supplied ItemVal cmdId.
void vGetLocalTime(char* tm)
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.
void vGetLocalDate(char* dt)
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.
9.9 Utility Programs
bmp2vbm
9.10 More Goodies
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.
[Table of Contents]
[Previous Chapter]
[Next Chapter]
[Object Central Home]