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

\chapter{V Programming Tools}
\index{V Programming Tools}

\section{The V Application Generator}

The \V\ Application Generator will automatically generate
C++ code needed to build a simple \V\ application. It has
several options that let you specify the name of the
application, the name of your derived classes, and what
\V\ interface elements to include in the application.
The \V\ Application Generator, \code{vgen}, does not generate code that
does any real work, it just provides a very good starting
skeleton program to build your application.

In the past, the approach for beginning a new \V\ application
has been to copy one of the example programs, and modify
it. \code{Vgen} has the advantage of allowing a certain amount
of customization with names and interface elements included
in the basic skeleton program.

On Linux or other Unix platforms, \code{vgen} will generate
the skeleton code and a makefile compatible with GNU make.
On the Windows version, just the files will be generated,
and it is up to you to include them in the project file
of your compiler. This is usually a very trivial operation.

Once you have generated and compiled the skeleton application,
you can modify the code to build your own application. It
is highly recommend that you start every new \V\ application
this way to get a consistency in the structure of the code.

\subsection{Overview}

\code{Vgen} is a very simple program to use. You run it,
and then select if you are generating a standard \V\
application skeleton, or if you are generating an
extra dialog skeleton to add to an existing application.
You can also generate a skeleton for a menuless and
canvasless \V application. You can also specify the
directory where the generated code should be placed.
Once you have generated the skelton, you should get it
to compile, either by using the generated makefile, or
by building an appropriate project with a Windows C++
compiler.

The most common use of \code{vgen} is to generate a standard \V\
application skeleton. This consists of a derived \code{vCommandWindow}
class with a simple menu bar, a command pane with a sample
button, a derived \code{vCanvasPane}, and a status pane. The
standard \V\ skeleton also allows you to generate a modeless and
a modal dialog. You can specify the name of the classes
you want to use, as well as the file names to use for each
of the generated files. The standard files generated include
a file for the derived \code{vApp} class, a file for the
derived \code{vCmdWindow} class, a file for the derived
\code{vCanvasPane} class, and files for the dialogs.
The X version will also generate a GNU compatible makefile.

\code{Vgen} also will generate extra copies of dialogs.
You can specify the class name of the dialog, and then
generate a skeleton file. These dialogs must be added
manually to the basic skeleton application.

The remainder of the reference manual will explain each
menu item and each dialog.

\subsection{File Menu}

The file menu only has an Exit command, which closes
\code{vgen}.

\subsection{Generate Menu}

The \code{Generate} menu selects which type of code you
want to generate. The \code{vgen} tool bar includes
shortcuts for the most common operations.

\subsubsection*{Generate:Standard Application}

This option brings up a dialog that controls the
generation of a standard \V\ application. This section
will explain each option contained on the Standard
V App dialog.

When \code{vgen} generates a skeleton application, it
uses some fixed conventions for naming derived classes and
file names. The \emph{Application Base Name} input lets
you specify the base name of each class. The default
base name is \code{my}. Thus, \code{vgen} will generate
the derived class names \code{myApp}, \code{myCmdWindow},
\code{myCanvasPane} or \code{myTextCanvasPane}, 
\code{myDialog}, and \code{myModalDialog}.

The \emph{File Base Name} input lets you control
the base name of the generated code files. If you
intend to do development for Windows, it is recommended
that you specify a name that follows the 8 character
limit on file base names. Using the default \code{my}
file base name, \code{vgen} will generate the files
\code{myapp.cpp} and \code{myapp.h}, \code{mycmdw.cpp}
and \code{mycmdw.h}, \code{mycnv.cpp} and \code{mycnv.h},
\code{mydlg.cpp} and \code{mydlg.h}, and \code{mymdlg.cpp}
and \code{mymdlg.h}. If you generate a makefile, it
will be called \code{makefile.my}.

The generate dialog allows you to control which interface
elements are included in the generated code. You can
elect to include a tool bar and a status bar. You can
also include code that shows the date and time on
the status bar if you wish. You can control if the
code generates Windows MDI or SDI model code (this
has no effect on the X code). The command window
class includes a short, standard menu bar that you
can later modify to add your own menu items.
You can also specify a title that will appear in
the app's title bar.

You can generate a canvas pane derived
from a \code{vCanvasPane} or a \code{vTextCanvasPane}.
You can elect to show the vertical or horizontal
scroll bars by default.

You can also control generation of a modal and a modeless
dialog. If you include these, code to activate the dialogs
will be included in the menu bar. You will usually modify
that code to activate the dialogs in a manner needed by
your application. 

You also have the option of generating
a GUN make compatible makefile. The make file needs to
know where the \code{v/include} and \V\ library files
are found on your system. The default \code{vgen}
assumes that these will be located in \code{/usr/local/v}.
There is a variable, \code{HOMEV} in the make file that
sets this path. If \V\ is found in a different place, you
can change it in the generate dialog, or you can change
an \code{ifdef} in the source code and recompile \code{vgen}.

Finally, you can control where the generated files are written.
The \emph{Set Save Path} brings up the standard file selection
dialog for where to save the \code{myapp.cpp} file. That file
and the others will be saved in whatever directory you specify.
If you don't specify a save path, the files will be saved in
the startup directory.

When you have made all your selections, the \emph{Generate}
button will generate the skeleton application.

\subsubsection*{Generate:Extra Dialog}

Many applications need more than one modeless or one modal dialog.
\code{Vgen}'s solution to this is not super sophisticated, but
it is easier than modifying an existing dialog from scratch.
The \emph{Extra Dialog} generate command allows you to generate
extra dialog classes that you can then manually add to your
main application. The dialogs generated are just like the
dialogs that the generate standard app builds, but with
a different base name. The options in this dialog include
set the class and file base names, the title, modal or
modeless, and the save path.

\subsubsection*{Generate:Menuless/Canvasless App}

\V\ supports a menuless, canvasless application. This
menu option allows you to generate a simple application
of this type, which includes only a window with a
tool bar. This option does not generate a menu bar,
a canvas, a status bar, or any dialogs.

\subsection{Future Plans}

I hope that \code{vgen} is only the beginning. It seems
pretty useful as it stands, but a full dialog layout
editor is planned to complete this tool.


\section{The V Icon Editor}
\index{Icon Editor}

The \V\ Icon Editor is a tool used to create and modify
icons. It is intended chiefly to create icons for the various
\V\ controls that use icons. It has many editing features
found in other icon or bitmap editors, but because it is intended chiefly as
an icon editor, it is limited to icons with a maximum size
of 150 pixels square and will easily manipulate up to 64 colors,
although it will display icons with up to 256 colors.
Typically, however, icons tend to be less than 64 pixels square,
and use a limited number of colors.

The current version of the \V\ Icon Editor will handle the native
\V \code{VBM} icon format, as well as \code{XBM} and \code{XPM}
X Windows format files, and Windows \code{BMP} format files,
\index{VBM icon format}\index{XBM bitmap format}
\index{XMP pixmap format}\index{BMP bitmap format}
so files generated by the X and Windows host platforms can
be easily edited and converted to \code{VBM} format.

The \V\ Icon Editor was originally developed as a team project
for the Spring, 1996 Software Engineering class at the University
of New Mexico by Philip Eckenroth, Mike Tipping, Marilee Padilla,
and John Fredric Jr. Masciantoni.  It has been heavily enhanced
by Bruce Wampler. Although this program makes use of many \V\
features, as a largely student project, the quality of the code
is somewhat variable, especially in its use of objects.

\subsection {Overview}

The icon editor functions very much
like other similar programs, and should be easy to use.
This guide is not intended as a complete tutorial, but
more as a brief, but complete, reference.

The \V\ Icon Editor will usually be called \code{viconed}.
It may be started with the name of a file to edit on
the command line.

The interface to the \V\ Icon Editor consists of a standard
menu bar, two tool bars, a drawing canvas, and a status bar.
The most common operations are supported by the tool bars
(which, for the most part, duplicate menu commands).
The drawing canvas shows an enlarged view of the icon as
well as an actual size view of the icon. The enlarged view
may be zoomed to several sizes, and displayed with or without
a grid. The remainder of this guide will describe each
menu command, and other features that can be invoked from
the tool bars.

You draw an icon using one of three types of brushes:
the normal brush, the text brush, and the copy/paste brush.
The brush will draw in one of several shapes. Not all
shapes work with all three brushes, but you can get
some interesting effects using the text or copy/paste
brush to draw a line or rectangle, for example.
The normal brush also has a choice of several sizes and styles.
Drawing with the left mouse button uses the foreground color,
while drawing with the right mouse button selects the background
color. Colors are selected with the color selection dialog.

\subsection {File Menu}

The \emph{File} menu generally includes commands needed to
open, close, and manipulate icon files.

\subsubsection*{File:New}

This will create a new icon using the current canvas. If the
current icon has been changed, you will be asked if you want
to save it. Then you will be prompted for the size of the
new icon. A blank icon of the specified size will be created,
and the color palette initialized to a set of default colors.

\subsubsection*{File:Open}

This command is used to open an existing icon in one of
the supported formats. If the current drawing canvas has
been edited or had an icon loaded, a new canvas window
will be opened. The color palette for the canvas window
will be initialized to the colors used in the opened icon.

The format of the icon is determined by the file extension.
\code{VBM} is the native \V bitmap format, and is the format
required by the various \V icon controls.  The current version
only supports the 1 and 8 bit \code{VBM} formats. \code{Viconed}
also supports the X Windows \code{XBM} monochrome bitmap files,
and \code{XPM} color pixmap files (up to about 90 colors).
The Windows \code{BMP} bitmap format is supported for
8-bit bitmaps. All icons are limited to a maximum of
150 by 150 pixels.

\subsubsection*{File:Save}

This will save the current icon. If the icon was new, you
will be prompted for a file name.

\subsubsection*{File:Save as}

You will be prompted for a name to save the current icon.
The format of the saved icon is determined by the file
extension. \code{VBM} specifies the standard \V\ icon
format. \code{Viconed} will automatically save either
the monochrome 1-bit \code{VBM} format, or the 256
color mapped 8-bit \code{VBM} format. The 24-bit
\code{VBM} format is not supported. The other formats
supported include X \code{XBM} monochrome bitmaps, and
X \code{XPM} color pixmaps up to about 90 colors.
The Windows \code{BMP} bitmap format is supported
for 8-bit bitmaps.

When \code{viconed} saves an icon, it will minimize
the size of the color map used in the file.

\subsubsection*{File:Close}

This will close the current icon, asking you if
you want to save it if it has changed, and then clear
the drawing canvas, ready to create a new icon, or
open another icon.

\subsubsection*{File:About}

This displays a dialog with information about \code{viconed}.

\subsubsection*{File:Exit}

All open icons will be closed, with save prompts as needed,
and \code{viconed} will exit.

\subsection {Edit Menu}

The current version of \code{viconed} does not yet support
standard cut, copy, and paste operations. (It does have
copy/paste brush support described later.)

\subsubsection* {Edit:Undo}

This will undo the last operation that changed the icon.
Only one level of undo is supported.

\subsubsection* {Edit:Clear}

This will clear the current icon to the background color.
A clear is \emph{not} undoable!

\subsubsection* {Edit:Resize}

You can resize the existing icon to a new size. The upper
left corner of the current icon will remain constant.
If you specify a smaller icon, you will lose the
lower and right portions. If you specify a bigger size,
then the current icon will become the upper left corner
of the new icon.  You may find the copy/paste brush
useful when resizing an icon.

\subsection {Draw Menu}

The Draw menu is used to select the shape of the brush.
The normal brush will draw the selected shape using
the current normal brush style. The text brush will
draw the shape using the current text. The copy/paste
brush will draw the shape using the copied shape.

Using the left button selects the foreground color,
while the right button selects the background color.

The shape selections are duplicated on the tool bar
for easy interaction.

\subsubsection* {Draw:Point}

This draws a single point, or instance of the text
or copy/paste brush. Holding the mouse button down and
moving will draw a series of points.

\subsubsection* {Draw:Line}

The button press selects the starting point of the
line, and the release selects the end point.

\subsubsection* {Draw:Rectangle}

The button press selects the first corner of the rectangle,
and the release the opposite corner. If snap is on,
then this will draw a square.

\subsubsection* {Draw:Rounded Rectangle}

This is a rounded rectangle instead of a square cornered
rectangle.

\subsubsection* {Draw:Ellipse}

This draws an ellipse, or a circle with snap on.

\subsubsection* {Draw:Pick Color}

This lets you pick a color from the current icon. Pressing
the left button will make the color under the cursor
the current foreground color, while the right button
will pick the background color. Using the pick color
(a dropper icon on the tool bar) is often easier than
using the color selection dialog.

\subsubsection* {Draw:Fill}

This will fill the closed area with the foreground or
background color depending on the mouse button pressed.

\subsubsection* {Draw:Refresh Image}

Normally, this command should not be needed, but it will
cause the icon to be redrawn.

\subsubsection* {Draw:Show Grid}

This will turn on or off the display of the drawing grid.

\subsection {Brush Menu}

These select the type of brush to use. Brush selection
is duplicated on the tool bar.

All three brushes actually use the same mechanism -
a general brush that can hold a pattern to draw
onto the icon. A regular brush is usually a pattern
of a single pixel, but can be any of the patterns
supported by the brush style dialog. The text
brush uses text to make the pattern. The copy/paste
brush set the pattern based on a selection
from the current icon.

You can get some interesting effects by using different
brush shapes (point, rectangle, etc.) when drawing with
any of the brushes. Using the point shape and then dragging
with the mouse held pressed can yield shadow effects,
for example.

\subsubsection* {Brush:Regular Brush}

The regular brush draws the currently selected shape
using the current regular brush style. The styles
include a single pixel point, as well as square, line, and
circular shapes of various sizes. The regular brush
style is selected from the brush dialog, which is
toggled on and off from the tool bar.

\subsubsection* {Brush:Text Brush}

When you select the text brush, you will be prompted
for some text, which will then become the brush.
You can then position the text, and press the right or
left mouse to draw the text in the icon.

Currently, only upper and lower case alphanumerics are
supported, and some of the letters don't quite look right.

\subsubsection* {Brush:Copy/Paste Brush}

Right after you select the copy/paste brush, you will
need to select an area of the current icon to "copy".
This then becomes the brush, and you then draw the brush
into the icon by pressing the right or left mouse buttons.


\subsection{Zoom Menu}

\code{Vicone} will display the icon zoomed from two up to
32 times the size of the actual icon. Use the zoom menu to
select the zoom factor.

\subsection{Tool Bars}

There are two tool bars in the code{viconed} interface.
The first tool bar shows the current foreground and background
colors on the left side. The next icon on this tool bar is
the "snap" toggle. When pressed, drawing with the rectangle
brush shape will draw squares, and the ellipse shape will draw
circles. The next icon is the brush toggle, and will display
the brush style dialog. The next icon is the color selection
toggle, and will display the color selection dialog. These three
toggles do not have corresponding entries on the menus.
The right end of the first tool bar show three toggles to
select the regular, text, and copy/paste brushes.

The second tool bar contains buttons for clear and undo,
as well as toggles for selecting the brush shape. All these
are duplicates of menu commands.

\subsubsection*{Color Selection Dialog}

The color selection dialog is used to pick and select foreground
and background colors. Internally, \code{viconed} uses 256 colors
for each icon pixel. Depending on the color resolution of your
display, all 256 colors may or may not be available. Typically,
icons do not use very many colors, so this shouldn't matter.

The color selection dialog shows a large color square
showing the current selection color. Two buttons next to the
current color square are used to apply the current selection
color to the foreground or background color.

Below that is a palette of 64 small color buttons arranged in
4 rows of 16. Selecting one of these buttons make it the
current selection color. \code{Viconed} supplies 64 default
colors for new icons. Again, depending on the color resolution
of you color display, these may or may not show as 64 colors.
When a new icon is loaded, its colors are used to load the
color selection color palette. Most icons won't use 64 colors,
and unused colors are filled with black.

Below the palette are three sliders that can be used to
change the color. Select a palette button to change, then
use the sliders to adjust the red, green, and blue. You
can also press the small red, green, or blue button
next to the sliders to enter a specific value for that
color component. The reset button will reset the palette
entry back to its original color.

Note that even though the color selection dialog only
has 64 entries, the colors shown do not necessarily have
any relation to the colors used in the icon. The colors
in the icon are set by the foreground and background
colors. You can use the sliders to specify any color,
and then apply it to the foreground or background color.
The color selection dialog allows you to easily
pick any one of the 64 palette colors.

Use only standard, basic colors in icons (black, white, red,
green, blue, etc.) to minimize the impact on the color maps used
on systems with color resolutions of 256 or less.