[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
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, vgen, does not generate code that
does any real work, it just provides a very good starting
skeleton program to build your application.
On approach for beginning a new
V application
is to copy one of the example programs, and modify
it. Vgen has the advantage of allowing a certain amount
of customization with names and interface elements included
in the basic skeleton program.
Vgen will generate
the skeleton code and a makefile compatible with GNU make. On the
Windows version, vgen will generate a makefile compatible
with mingw32. If you use a different compiler, it is up to you to
build a project file for 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.
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.
The most common use of vgen is to generate a standard
V\
application skeleton. This consists of a derived vCommandWindow
class with a simple menu bar, a command pane with a sample
button, a derived 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 vApp class, a file for the
derived vCmdWindow class, a file for the derived
vCanvasPane class, and files for the dialogs.
Vgen also generates a GNU compatible makefile.
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.
The file menu only has an Exit command, which closes
vgen.
The Generate menu selects which type of code you
want to generate. These are duplicated on the tool bar.
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 vgen generates a skeleton application, it
uses some fixed conventions for naming derived classes and
file names. The
Application Base Name input lets
you specify the base name of each class. The default
base name is my. Thus, vgen will generate
the derived class names myApp, myCmdWindow,
myCanvasPane or myTextCanvasPane,
myDialog, and myModalDialog.
The
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 my
file base name, vgen will generate the files
myapp.cpp and myapp.h, mycmdw.cpp
and mycmdw.h, mycnv.cpp and mycnv.h,
mydlg.cpp and mydlg.h, and mymdlg.cpp
and mymdlg.h. If you generate a makefile, it
will be called makefile.my.
The generate dialog allows you to control which interface
elements are included in the generated code.
The first section of the dialog controls the Command Window
options. 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. Finally,
you can have vgen generate code that implements a vTimer
in the CommandWindow. This is most likely to be useful for OpenGL
apps.
The second section of the dialog controls the generation of
the canvas pane.
You can generate a canvas pane derived
from a vCanvasPane, a vTextCanvasPane,
or a vBaseGLCanvasPane. You also have the choice
of no canvas pane at all. If you select no canvas pane,
then your app
must have a tool bar.
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 GNU make compatible makefile. The make file needs to
know where the v/include and
V library files
are found on your system. On Unix-like systems, the default
vgen assumes that these will be located in
/usr/local/v. There is a variable, HOMEV in the
makefile 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 ifdef in the source code and recompile vgen.
In the MS-Windows version, vgen assumes you are using
mingw32 installed on C:, with the
Vlibraries and includes
also installed in the mingw32 path.
Finally, you can control where the generated files are written.
The
Set Save Path brings up the standard file selection
dialog for where to save the 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
Generate
button will generate the skeleton application.
Many applications need more than one modeless or one modal dialog.
Vgen's solution to this is not super sophisticated, but
it is easier than modifying an existing dialog from scratch.
The
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.
The current version of the
V Icon Editor will handle the native
VVBM icon format, as well as XBM and XPM
X Windows format files, and Windows BMP format files,
so files generated by the X and Windows host platforms can
be easily edited and converted to 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.
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 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.
The
File menu generally includes commands needed to
open, close, and manipulate icon files.
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.
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.
VBM is the native
Vbitmap format, and is the format
required by the various
Vicon controls. The current version
only supports the 1 and 8 bit VBM formats. Viconed
also supports the X Windows XBM monochrome bitmap files,
and XPM color pixmap files (up to about 90 colors).
The Windows BMP bitmap format is supported for
8-bit bitmaps. All icons are limited to a maximum of
150 by 150 pixels.
This will save the current icon. If the icon was new, you
will be prompted for a file name.
You will be prompted for a name to save the current icon.
The format of the saved icon is determined by the file
extension. VBM specifies the standard
V icon
format. Viconed will automatically save either
the monochrome 1-bit VBM format, or the 256
color mapped 8-bit VBM format. The 24-bit
VBM format is not supported. The other formats
supported include X XBM monochrome bitmaps, and
X XPM color pixmaps up to about 90 colors.
The Windows BMP bitmap format is supported
for 8-bit bitmaps.
When viconed saves an icon, it will minimize
the size of the color map used in the file.
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.
This displays a dialog with information about viconed.
All open icons will be closed, with save prompts as needed,
and viconed will exit.
The current version of viconed does not yet support
standard cut, copy, and paste operations. (It does have
copy/paste brush support described later.)
This will undo the last operation that changed the icon.
Only one level of undo is supported.
This will clear the current icon to the background color.
A clear is
not undoable!
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.
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.
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.
The button press selects the starting point of the
line, and the release selects the end point.
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.
This is a rounded rectangle instead of a square cornered
rectangle.
This draws an ellipse, or a circle with snap on.
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.
This will fill the closed area with the foreground or
background color depending on the mouse button pressed.
Normally, this command should not be needed, but it will
cause the icon to be redrawn.
This will turn on or off the display of the drawing grid.
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.
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.
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.
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.
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.
There are two tool bars in the codeviconed 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.
The color selection dialog is used to pick and select foreground
and background colors. Internally, 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. 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.
With the use of GNU g++ on Linux, and a growing number of
MS-Windows users of mingw32, the standard
Vdistribution now
includes a basic Integrated Development Environment (IDE)
called VIDE. VIDE lets you compile via Makefile,
and edit your source code with a generic windowing editor
with C++ syntax highlighting.
The current version of VIDE is rather basic, but still
provides a useful environment for developing programs. This
is a very basic overview of using VIDE.
VIDE is currently designed to work only with GNU g++,
either on a Unix-like system, or on MS-Windows with mingw32.
Operation of VIDE is based on standard GNU makefiles.
To build a project, you must have a working Makefile - either
based on one generated by vgen, or one you've written
yourself.
Once you start VIDE, the first action normally is to
select a Makefile. The opening window will be the message window,
and is used to output the results of your make. Click on the
Sel Mk button to select a makefile. You can then run
the makefile by clicking Make. This runs make with
the default target (often äll"). The results of the
make are shown in the message window. If you get an error,
you can usually right click on the error line and the source
file will be loaded into an edit window, and the cursor placed
on the offending line. This all assumes that the source and
makefile are in the same directory.
After you correct the problem, clicking Make again will
rerun make. On the MS-Windows version, there seems to be some
problem with GNU make and time stamps, and sometimes the final
.exe target is not made until you click Make again.
You can also make a specific target in your makefile by using
the Make menu: make:Make <target>. If you include a "clean" target
in your make file, make:Make Clean will run make clean.
The tools menu allows you to run a program (this will often be
the program you just compiled. Future versions of VIDE will
be able to run your program.). Tools:Run a program will prompt
you for a program to run, or you can browse.
Tools:Run OS Shell will run a MS-DOS command window, or execute
rxvt on X. Tools:V App Gen will run vgen if it is installed
in your PATH, and Tools:V Icon Editor will run the V icon editor.
Future versions of VIDE will include management of code
projects - you will be able to specify source files, and a makefile
will be automatically generated. You will also be able to customize
options as needed. Work is also being done on writing an interactive dialog
builder. A V based class browser is also waiting to be included.
I also plan to include support for the gdb debugger, and
probably RCS. While future versions of
Vwill be included
with
V, incremental versions will be released independently.
Appendix D
V Programming ToolsD.1 The V Application Generator
4.1.1 Overview
4.1.2 File Menu
4.1.3 Generate Menu
Generate:Standard Application
Generate:Extra Dialog
D.2 The V 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.
4.2.1 Overview
4.2.2 File Menu
File:New
File:Open
File:Save
File:Save as
File:Close
File:About
File:Exit
4.2.3 Edit Menu
Edit:Undo
Edit:Clear
Edit:Resize
4.2.4 Draw Menu
Draw:Point
Draw:Line
Draw:Rectangle
Draw:Rounded Rectangle
Draw:Ellipse
Draw:Pick Color
Draw:Fill
Draw:Refresh Image
Draw:Show Grid
4.2.5 Brush Menu
Brush:Regular Brush
Brush:Text Brush
Brush:Copy/Paste Brush
4.2.6 Zoom Menu
4.2.7 Tool Bars
Color Selection Dialog
D.3 The V Integrated Development Environment
[Table of Contents]
[Previous Chapter]
[Next Chapter]
[Object Central Home]