%***********************************************************************
%***********************************************************************
%***********************************************************************

\chapter {Utilities}
\index{utilities}

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:

\begin{description}
	\item[vDebugDialog] Utility class to access debugging messages.
	\item[vFileSelect] A utility class to select or set a file name.
	\item[vFontSelect] A utility class to select or set a font object.
	\item[vNoticeDialog] A utility class to display a message.
	\item[vReplyDialog] A utility class to get a text reply from the user.
	\item[vTimer] A class for getting timer events.
	\item[vYNReplyDialog] A utility class to display a message, and get a Yes or No answer.
	\item[Utility Functions] Several useful functions.
\end{description}

%-------------------------------------------------------------------
\Class{vDebugDialog}
\Indextt{vDebugDialog}

Utility class to access debugging messages.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vdebug.h>}
	\item [Class name:] vDebugDialog
 	\item [Hierarchy:] vModalDialog \rta vDebugDialog
\end{description}

\subsection* {Description}

\V\ provides built in debugging features. Most of the \V\ classes
contain debugging messages that are displayed on \code{stderr} or a
special debugging information window. For Unix systems, \code{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 \code{vDebugDialog} class.

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

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

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

By default, V starts with the \code{System} category \code{BadVals}
on, and all three \code{User} categories on. Unix versions of \V\
support a command line option that allows you to enable each
option using
the \code{-vDebug} command line switch. You include the switch
\code{-vDebug} on the command line, followed by a single argument
value made up of letters corresponding to the various debugging
categories. If \code{-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 \code{-vDebug SUCDm} would enable debugging messages
for both \code{System} and \code{User} constructors and destructors,
as well as \code{System} mouse events.
Note that the values are case sensitive.


\subsection*{Debugging Categories}

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

\paragraph*{System (-vDebug S)}

These are the messages defined using the \code{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.

\paragraph*{User (-vDebug U)}

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

\paragraph*{CmdEvents (-vDebug c)}

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

\paragraph*{MouseEvents (-vDebug m)}

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

\paragraph*{WindowEvents (-vDebug w)}

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

\paragraph*{Build (-vDebug b)}

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

\paragraph*{Misc (-vDebug o)}

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

\paragraph*{Text (-vDebug t)}

These messages are primarily used by the \code{vTextCanvasPane} class,
and are useful for debugging text display.

\paragraph*{BadVals (-vDebug v)}

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

\paragraph*{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
\code{UserDebug(Constructor,"X::X constructor")} messages
for all of your constructors, and a corresponding Destructor message.

\paragraph*{Destructor (-vDebug D)}

Messages from an object destructor.

\paragraph*{UserApp1, UserApp2, UserApp3 (-vDebug 123)}

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

\subsection* {Example}

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

\footnotesize
\begin{verbatim}

#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;
     }
    ...

\end{verbatim}
\normalfont\normalsize

%--------------------------------------------------------------------

\Class{vFileSelect}
\Indextt{vFileSelect}

A utility class to select or set a file name.

\subsection* {Synopsis}

\begin{description}
        \item [Header:] \code{<v/vfilesel.h>}
        \item [Class name:] vFileSelect
        \item [Hierarchy:] vModalDialog \rta vFileSelect
\end{description}

\subsection* {Description}

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.

\subsection* {Methods}

%............................................................
\Meth{vFileSelect(vBaseWindow* win)}
\Indextt{vFileSelect}
\Meth{vFileSelect(vApp* app)}

The \code{vFileSelect} constructor requires a pointer to a
\code{vBaseWindow}, which includes all \V\ windows and dialogs,
or a pointer to the \code{vApp} object.
You will usually pass the \code{this} to the constructor.

%............................................................
\Meth{int FileSelect(const char* prompt, char* filename, const
int maxLen, char** filterList, int\& filterIndex)}
\Indextt{FileSelect}

\Meth{int FileSelectSave(const char* prompt, char* filename, const int
maxLen, char** filterList, int\& filterIndex)}
\Indextt{FileSelectSave}

You provide a \code{prompt} for the user, such as ``Open File.'' The
user then uses the dialog to select or set a file name. \code{FileSelect}
returns \code{True} if the user picked the OK button, and \code{False}
if they used the Cancel button.

The filename will be filled in to the \code{filename} buffer of
maximum length \code{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 \code{filterIndex} reference parameter is used to track which
filter the user selected. After \code{FileSelect} returns, \code{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 \code{FileSelect} with the same filter list so
that the user selected filter will be preserved.

You should use \code{FileSelect} to open a new or existing file. If
the user is being asked to save a file (usually after picking a
\emph{Save As} menu choice), use the \code{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.

\subsection*{Example}

The following is a simple example of using \code{vFileSelect}.

\vspace{.1in}
\small
\includegraphics{fig/filesel.eps}
\normalfont\normalsize

\footnotesize
\begin{verbatim}
    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.");
\end{verbatim}
\normalfont\normalsize

%--------------------------------------------------------------------

\Class{vFontSelect}
\Indextt{vFontSelect}

A utility class to select or set a file name.

\subsection* {Synopsis}

\begin{description}
        \item [Header:] \code{<v/vfontsel.h>}
        \item [Class name:] vFontSelect
        \item [Hierarchy:] vModalDialog \rta vFontSelect
\end{description}

\subsection* {Description}

This class provides the \code{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.

\subsection* {Methods}

\Meth{vFontSelect(vBaseWindow* win)}
\Indextt{vFontSelect}
\Meth{vFontSelect(vApp* app)}

The \code{vFontSelect} constructor requires a pointer to a
\code{vBaseWindow}, which includes all \V\ windows and dialogs,
or a pointer to the \code{vApp} object.
You will usually pass the \code{this} to the constructor.

\Meth{int FontSelect(vFont\& font, const char* msg = "Select Font")}
\Indextt{FontSelect}

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 \code{font} object, and change
them upon successful return. A \code{false} return means the user
selected Cancel, while a \code{true} return means the user
finished the selection with an OK.

%--------------------------------------------------------------------

\Class{vNoticeDialog}
\Indextt{vNoticeDialog}

A utility class to display a message.

\subsection* {Synopsis}

\begin{description}
        \item [Header:] \code{<v/vnotice.h>}
        \item [Class name:] vNoticeDialog
        \item [Hierarchy:] vModalDialog \rta vNoticeDialog
\end{description}

\subsection* {Description}

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.

\subsection* {New Methods}

%............................................................
\Meth{vNoticeDialog(vBaseWindow* win)}
\Indextt{vNoticeDialog}
\Meth{vNoticeDialog(vApp* app)}

The \code{vNoticeDialog} constructor requires a pointer to a
\code{vBaseWindow}, which includes all \V\ windows and dialogs,
or a pointer to the \code{vApp} object.
You will usually pass the \code{this} to the constructor.

%............................................................
\Meth{void Notice(const char* prompt)}
\Indextt{Notice}

You provide a \code{prompt} for the user. If the message
contains '$backslash$n' newlines, it will be shown on multiple
lines.

\subsection*{Example}

The following is a simple example of using \code{vNoticeDialog}.

\vspace{.1in}

\small
\includegraphics{fig/notice.eps}
\normalfont\normalsize

\footnotesize
\begin{verbatim}
    #include <v/vnotice.h>
    ...
    vNoticeDialog note(this);   // instantiate a notice

    (void)note.Notice("This is a notice.");
\end{verbatim}
\normalfont\normalsize

%--------------------------------------------------------------------

\Class{vReplyDialog}
\Indextt{vReplyDialog}

A utility class to get a text reply from the user.

\subsection* {Synopsis}

\begin{description}
        \item [Header:] \code{<v/vreply.h>}
        \item [Class name:] vReplyDialog
        \item [Hierarchy:] vModalDialog \rta vReplyDialog
\end{description}

\subsection* {Description}

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.

\subsection* {New Methods}

%............................................................
\Meth{vReplyDialog(vBaseWindow* win)}
\Indextt{vReplyDialog}
\Meth{vReplyDialog(vApp* app)}

The \code{vReplyDialog} constructor requires a pointer to a
\code{vBaseWindow}, which includes all \V\ windows and dialogs,
or a pointer to the \code{vApp} object.
You will usually pass the \code{this} to the constructor.

%............................................................
\Meth{int Reply(const char* prompt, char* reply, const int maxLen, char* dflt = "")}
\Indextt{Reply}

You provide a \code{prompt} for the user. The text the user enters
will be returned to the buffer \code{reply} of maximum length \code{maxLen}.
\code{Reply} will return the value \code{M\_OK} or \code{M\_Cancel}.
Use dflt to provide a default reply.

\subsection*{Example}

The following is a simple example of using \code{vReplyDialog}.

\vspace{.1in}
\small
\includegraphics{fig/reply.eps}
\normalfont\normalsize

\footnotesize
\begin{verbatim}
    #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.");
\end{verbatim}
\normalfont\normalsize

%------------------------------------------------------------------------

\Class{vTimer}
\Indextt{vTimer}
\index{timer}

A class for getting timer events.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vtimer.h>}
	\item [Class name:] vTimer
 	\item [Hierarchy:] vTimer
\end{description}

\subsection* {Description}

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 \code{time}
routines to get real clock time.

\subsection* {New Methods}

%............................................................
\Meth{vTimer}
\Indextt{vTimer}

This constructs a timer object. The timer doesn't run until
you start it with \code{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 \code{TimerTick} method
to do something in that window: \code{myTimer(vWindow* useWindow)}.

%............................................................
\Meth{int TimerSet(long interval)}
\Indextt{TimerSet}

This starts the timer going. The timer will call your overridden
\code{TimerTick} method approximately every \code{interval}
milliseconds until you stop the timer. Most systems don't support
an unlimited number of timers, and \code{TimerSet} will return 0
if it couldn't get a system timer.

%............................................................
\Meth{void TimerStop()}
\Indextt{TimerStop}

Calling this stops the timer, but does not destruct it.

%............................................................
\Meth{void TimerTick()}
\Indextt{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 \code{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.

%--------------------------------------------------------------------
\Class{vYNReplyDialog}
\Indextt{vYNReplyDialog}

A utility class to display a message, and get a Yes or No answer.

\subsection* {Synopsis}

\begin{description}
        \item [Header:] \code{<v/vynreply.h>}
        \item [Class name:] vYNReplyDialog
        \item [Hierarchy:] vModalDialog \rta vYNReplyDialog
\end{description}

\subsection* {Description}

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.

\subsection* {New Methods}

%............................................................
\Meth{vYNReplyDialog(vBaseWindow* win)}
\Indextt{vYNReplyDialog}
\Meth{vYNReplyDialog(vApp* app)}

The \code{vYNReplyDialog} constructor requires a pointer to a
\code{vBaseWindow}, which includes all \V\ windows and dialogs,
or a pointer to the \code{vApp} object.
You will usually pass the \code{this} to the constructor.

%............................................................
\Meth{int AskYN(const char* prompt)}
\Indextt{AskYN}

You provide a \code{prompt} for the user. The user will then press
the Yes, No, or Cancel buttons. \code{AskYN} returns a 1 if
the user selected Yes, a 0 if they selected No, and a -1 if
they selected Cancel.

\subsection*{Example}

The following is a simple example of using \code{vYNReplyDialog}.

\vspace{.1in}

\small
\includegraphics{fig/ynreply.eps}
\normalfont\normalsize

\footnotesize
\begin{verbatim}
    #include <v/vynreply.h>
    ...
    vYNReplyDialog ynd(this);   // instantiate a notice

    int ans = ynd.AskYN("Exit. Are you sure?);
    if (ans == 1)
      exit(0);
\end{verbatim}
\normalfont\normalsize

%------------------------------------------------------------------
\Class{Utility Functions}
\index{utility functions}

Several useful utility functions.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vutil.h>}
\end{description}

\subsection* {Description}

\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.

\Meth{void ByteToStr(unsigned char b, char* str)}
\Indextt{ByteToStr}

This will convert the unsigned char in \code{b} to a \emph{Hex} character
string in \code{str}. You need to make \code{str} big enough to
hold the string.

\Meth{void IntToStr(int intg, char* str)}
\Indextt{IntToStr}

This will convert the integer in \code{intg} to a character
string in \code{str}. You need to make \code{str} big enough
to hold the string.

\Meth{void LongToStr(long intg, char* str)}
\Indextt{LongToStr}

This will convert the long integer in \code{intg} to a character
string in \code{str}. You need to make \code{str} big enough
to hold the string.

\Meth{long StrToLong(char* str)}
\Indextt{StrToLong}

This will convert the character string in \code{str} into a long
integer. You can cast to get ints.

\Meth{void vGetLocalTime(char* tm)}
\Indextt{vGetLocalTime}
\index{time}

This will return a string representation of the current local time
to the string \code{tm}. The format will be ``HH:MM:SS AM''. If you
need a different format, you will need to use the C functions
\code{time}, \code{localtime}, and \code{strftime} directly.

\Meth{void vGetLocalDate(char* dt)}
\Indextt{vGetLocalDate}
\index{date}

This will return a string representation of the current local
date to the string \code{dt}. The format will be ``MM/DD/YY''.
If you need a different format, you will need to use the C
functions \code{time}, \code{localtime}, and \code{strftime}
directly.

%------------------------------------------------------------------
\Class{Utility Programs}
\index{utility programs}
\index{icons} \index{bitmap}

\subsection*{bmp2vbm}

The utility \code{bmp2vbm} converts a Window or OS/2 \code{.bmp}
format bitmap file into a \code{.vbm} \V icon bitmap format file.
The \code{.vbm} file is then used with a \code{vIcon} object
definition. The \code{bmp2vbm} utility will not convert all
\code{.bmp} files. Specifically, it can't handle old format
\code{.bmp} files, nor can it handle compressed \code{.bmp} files.

Windows has many tools to generate \code{.bmp} files. For X,
the widely available tool \code{xv} can generate \code{.bmp}
files from various source formats.

\code{Bmp2vbm} is a command line tool - run it from a Unix prompt,
or from an \code{MSDOS} box on Windows. The command line format is:
\code{bmp2vbm inputname outputname iconname}. You should specify only
the base file names: \code{bmp2vbm} will automatically supply
the \code{.bmp} and \code{.vbm} extension. The \code{iconname}
specifies the name used to generate the date (e.g., \code{iconname\_bits}).

%------------------------------------------------------------------
\Class{More Goodies}
\index{goodies}
\index{icons}

The directory \code{v/icons} includes over 30 different monochrome
icons in \code{.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 \code{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.