The V C++ GUI Framework User Guide:Tutorial:Getting Started
This chapter is intended to cover the elements that make up a V application. The first section covers the general organization of a ``Standard V Application. Read this section to get an overview of a V application. Don't worry about the details yet - just the the main idea. Then read Section Tutorial Example and the Tutorial Code, which has the source code of a small, complete V application, to get the details.
Contents
Getting Started with Your Own V Application
As with any new system, V has a learning curve before you can write applications of your own. V's learning curve is actually pretty short. The experience of the students using V has shown the best way to get started with V is to first read the first part of this reference manual, including this chapter. Then begin with an example V application.
The V application generator, vgen, included with the V distribution is the easiest way to begin building a V application. Run vgen, select the basic options you want to include in your application, select the directory to save the generated code in, and then generate the basic skeleton application. From the skeleton app, it is relatively easy to add your own functionality.
The tutorial application described in this page is also an excellent V example. Start by getting the example to compile. Then modify the code to add or remove features. Before long, you will have a good feel for V, and be able to add all the features you need.
There are several other example programs provided with the V distribution. This tutorial is found in ~/v/tutor. The VDraw program is found in ~/v/draw. The program used to test all V functionality is found in ~/v/test. It will have an example of how to use every V feature, although it is not as well structured as the other examples.
A Standard V Application
While the V framework is flexible enough to allow many different approaches to building an application, you should find it easier to base your applications on a model Standard V Application. The software organization described by a Standard V Application can support MVC (Model-View-Controller) object-oriented architecture paradigm.
Figure 1 shows the hierarchy of a standard V application. A standard V application consists of the parts described below. Each part consists of a pair of .cpp (or .cxx) and .h files (except the makefile).
Figure 1: Standard V Application
The Application
In many ways, the heart of a Standard V Application is the application class derived from the vApp class. By convention, this derived class is called myApp (but you can use a different name if you want.) There will always be exactly one instance of the myApp class. The myApp class acts as a coordinator between the windows that implement the user interface (the views) and the objects and algorithms that actually make up the application (the model). The myApp class will contain in a whole/part (or aggregation) relationship the windows defined by the application, as well as any classes needed to implement the application.
The vApp class has several utility methods that are usually used unmodified, plus several methods that are usually overridden by the myApp class. These are described in the section covering vApp. In addition, your myApp class will usually have several other programmer defined methods used to interface the command windows with the application model.
Windows and Canvases
Each Standard V Application will have at least one top level window, and possible subwindows. These will usually be command windows derived from the vCmdWindow class. Your main derived class should be called myCmdWindow, and include a constructor that defines a menu bar, a canvas, and possible command and status bars. Of course, there will be a corresponding destructor. The .cpp file will contain the static definitions of the menu and any command and status bars. It will also override the WindowCommand method of vCmdWindow superclass. In your WindowCommand method, you will have a switch with a case for each menu item and button defined for the window.
Since a vCmdWindow contains different panes such as vMenus, vCanvasPanes, vCommandPanes, and vStatusPanes, your top level command window object will usually define the appropriate pointers to each of these objects as required by the specific application. The myCmdWindow constructor will then have a new for each pane used.
Each instance of a window will be built using a call to the vApp::NewAppWin method. This allows the app object to track windows, and control interaction between the app model and the views represented by each window.
Some applications need to open subwindows. These windows may or may not use the same menu, command bar, and canvas as the top level window. If they do, then they can use the same static definitions used by the top level window. Subwindows may also have their own menu, button, and canvas definitions.
Canvases for Windows
Since each window usually needs a canvas, you will usually derive a canvas object from the vCanvasPane class. At this point in the life of V, there are only two possible kinds of canvas. The first is for graphics drawing, and is derived directly from the vCanvasPane class. The other kind is a text canvas derived from the vTextCanvasPane class. The derived class will define override methods required for the user to interact with the canvas.
Optional Dialogs
Most applications will need dialogs - either modeless or modal. A Standard V dialog consists of a .cpp file with the static definition of the dialog commands, and the definitions of methods derived from the vDialog class. These will include a constructor and destructor, and a DialogCommand override with a switch with a case for each command defined for the dialog. Each case will have the code required to carry out useful work.
The top level window (or the subwindow that defines and uses the dialog) will create an instance of each dialog it needs (via new). The constructor for the dialog sets up the commands used for the dialog.
Typically, the top level window defines menu and button commands that result in the creation of a dialog. The top level window is thus usually responsible for invoking dialogs.
Optional Modal Dialogs
Modal dialogs are almost identical to modeless dialogs. The main difference is how the dialog is invoked from the defining window.
Menu, Command and Status Bars
By definition, the look and feel of a V application requires a menu bar on the command window. A V application also typically has a command bar and a status bar, but these are not required.
The Application Model
Each application will need code to implement its data structures and algorithms. The design of the application model is beyond the scope of V, but will usually be defined as a relatively independent hierarchy contained by the myApp object. Interaction between the application model and the various views represented by myCmdWindows can be coordinated with the myAppWinInfo class.
The Makefile
Each V Standard Application should have an associated makefile that can be used to compile and link the application.
Please note that while V is object-oriented, the objects represent real screen windows. Thus, it makes no sense for most V objects to support copy constructors or object assignment. If you use one of these V objects in a way requiring a copy constructor or an assignment (fortunately, it is difficult to contrive such an example), the code will generate a run time error.
Special V Applications
Windows MDI/SDI
The standard V application includes a command window with a menu, a command bar, a canvas, and a status bar. While this model suits most applications, there are some special cases that V supports.
First, on Windows, V supports the standard Windows MDI model (Multiple Document Interface) by default. The MDI model consists of a parent window that can contain several children canvases, each with a different menu that changes in the main parent window when a child gets focus. In practice, the menus are usually the same for all children windows, and each window is used to hold a new document or data object. One of the main advantages of the MDI model is that each application has a main window to distinguish it from other Windows applications, and as many child windows as it needs to manipulate its data.
On X versions, there is no need for a special parent window. Each time you open a new command window, you get a new window on the X display.
The Windows MDI model forces some screen decorations that are not appropriate for all applications. Thus, V also supports the standard Windows SDI model. The SDI model allows only one canvas/command window combination. There is a parameter to the vApp constructor that tells V to use the SDI model. This parameter is not used on the X version.
Sometimes an application needs just a command bar with no menu or canvas. By setting the simSDI parameter to 1, and supplying a width and height value to the vApp constructor, V allows this kind of simple interface. Instead of adding a menu and a canvas as is done for normal V apps, a menuless and canvasless app just defines a command pane for the command bar. The height and width are used to specify the height and width of the application, and require different values for Windows or X.
A Tutorial Example V Application
Now that you've read about the parts of a standard V application, it might be useful to go over a simple example of a V application. Appendix A contains the source code for a simple V application. The code is tutorial, and well commented. You can read the code directly and get a good understanding of what elements are required for a V application. This section will give a higher level overview of the code in the tutorial source.
You should read this code, paying special attention to the comments. Most of the information you need to build a typical V application is explained in this code. This sample code is also available on line under the ~/v/tutor directory. The source code of a slightly different standard V application is included the ~ /v/examp directory of the V distribution.
The previous section suggested using myApp for names. This tutorial uses a t prefix instead of my. You really can use whatever names you want. It will help to be consistent, however.
The code is broken down into five sections, corresponding to the main application, the main window, a simple canvas, and modal and modeless dialogs. The source code for each of these parts is included in Appendix A. The source code is extensively commented, and the comments contain much detail on how you should structure a V application, so please read them carefully. The following sections give a brief overview of each source file included in the tutorial example.
The Base Application Class
The file tutapp.cpp contains the overridden definitions of the classes NewAppWin, Exit, CloseAppWin, AppCommand, and KeyIn methods. These examples don't do much work, but are provided as a template for building complete applications.
The single definition of the application (static tutApp tut_App("TutorApp"), and the AppMain main program are also in this file. The initial window is created in AppMain by calling NewAppWin.
One thing that can be difficult to grasp when using a framework such as V is understanding where the program starts, and how you get things rolling. This happens in tutapp.cpp, so it is especially important to understand this piece of code. The essential thing to understand is that C++ will invoke the constructors of static objects before beginning execution of the program proper. Thus, you declare a static instance of the vApp object, and its constructor is used to initialize the native GUI library and get things going. Your program will not have a main function (see AppMain in the description of the vApp class for more details).
As with all files in the tutorial, each has a .cpp source file, and its associated .h header file. All V code has been written using the coding guidelines given in Appendix B. This includes the order of the declarations included in header files.
The Command Window
The file tcmdwin.cpp contains the code for the main command window. Of particular interest are the definitions of the main menu, command pane, and status pane. These panes are defined and added to the window in the constructor.
There is also code to demonstrate handling keyboard and window command events in the KeyIn and WindowCommand methods. There is also a simple example of using the vFileSelect utility class, as well as invoking modeless and modal dialogs.
The Canvas
The file tcanvas.cpp contains the code for the canvas. This is a really simple canvas example which supports drawing a few lines. This class handles redrawing after expose events very simply, but demonstrates what must be done in general.
A Modeless Dialog
The file tdialog.cpp contains the code for a modeless dialog. There are just a few example buttons, check boxes, and radio buttons. The DialogCommand methods demonstrates how to handle commands from a dialog.
A Modal Dialog
The file tmodal.cpp contains the code for a modal dialog. The definition of a modal dialog is nearly identical to a modeless dialog. The main difference is how they are invoked, which is shown in the tcmdwin.cpp code.
The Makefile
The file makefile contains a sample Unix-style make file. This version is for Gnu make, which has features different than some other flavors of make. It should still serve as a decent example.
