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

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

### Canvasless, menuless V Application

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.