Chapter 1. Overview of ViewKit
Prev |  | Next

## Chapter 1. Overview of ViewKit

ViewKit is a C++ toolkit that makes it easier for you to develop applications. It provides a collection of high-level user interface components and other support facilities that you typically must implement in every application. For example, it provides high-level user interface components, such as windows, menus, and dialogs.

ViewKit does not replace Motif or any other user interface toolkit. In fact, it uses Motif widgets to implement all of its user interface components; also, you can directly call Motif functions to create and manipulate widgets in a ViewKit application. The ViewKit architecture helps mask much of the complexity of programming with Motif.

ViewKit offers you several benefits:

- It provides support for common user interface components such as windows, menus, and dialogs. It also provides specialty interface components for tasks such as displaying and managing arc-and-node graphs, displaying and managing toggle check boxes, and managing the layout of other widgets. Creating these elements using ViewKit is much simpler and faster than using low-level widgets to build them from scratch. Furthermore, by using the same basic components, applications that use ViewKit components have greater visual and behavioral consistency.

- It simplifies interaction with the X resource manager, allowing you to customize your application using resources more easily. By designing your application to use resource values rather than hard-coding the values in your program, you can easily modify the appearance of your application. This approach is particularly useful for preparing your application for internationalization.

- All user interface components in ViewKit are C++ classes, which provides a framework for using Motif in a highly structured, object-oriented way. The ViewKit architecture encourages you to develop self-contained objects that you can re-use in multiple applications.

- It provides support for other common application services such as interprocess communication.

## Major ViewKit Elements

You can think of ViewKit as consisting of several sets of classes: framework classes, interface components, interapplication communication, and convenience utilities. The following sections discuss these groups.

### Framework Classes

ViewKit provides a small set of classes that are either essential for all applications or provide fundamental support for all other classes. The most basic of these classes is the VkComponent class, which defines the basic structure of all user interface components. All user interface classes are derived from VkComponent.

The framework classes also include support for features needed by nearly all applications, including application management and X server setup, top-level windows, menus, and dialog management. All classes are designed to implement as many typical features as possible. For example: all top-level windows and dialogs handle the window manager quit/close protocol; dialogs are cached to balance memory use and display speed; the menu system goes beyond simply constructing menus to support dynamically adding, removing, and replacing items, and more.

The classes that make up the framework of ViewKit are closely integrated and work together to support essential features required by most applications as automatically as possible. Among the basic services supported by the core ViewKit framework are single and multi-level undo; interruptible tasks; and an application-level callback mechanism that allows C++ classes to dynamically register member functions to be invoked by other C++ classes.

### Interface Components

In addition to the basic user interface support provided by the core framework classes, ViewKit provides an assortment of ready-to-use interface components. Examples of these components are a graph viewer/editor, an input field that supports name expansion, and an outliner component for displaying and manipulating hierarchical information.

You are encouraged to use the architecture of ViewKit to create new components and extend existing components. Creating reusable, high-level components promotes consistency throughout a set of applications by providing elements that users can learn once and then easily recognize in multiple applications.

### Convenience Utilities

ViewKit provides various utility functions and classes for your convenience. These utilities include simple functions that make it easier to load resources (including automatic type conversion), classes that support the use of icons, and other miscellaneous utilities.

## Mixing ViewKit and Standard X and Motif Functions

As stated earlier, ViewKit does not replace Motif. It uses Motif widgets to implement all of its user interface components, and you are free to make X and Motif calls directly in a ViewKit application. ViewKit doesn't do anything that you can't do yourself using Motif directly, but the advantage of using ViewKit is that many commonly needed services are already implemented for you.

Naturally, not all ViewKit services are appropriate for all applications at all times. If a situation arises in which a ViewKit facility doesn't meet your needs, you can use the lower-level Motif, Xt, or Xlib facilities to perform the desired operation yourself.

Most ViewKit classes are optional; however, you should be aware that certain ViewKit classes depend on other classes. In particular, most classes depend on the existence of an instance of the VkApp class for application management. If you plan to use any ViewKit facilities, you should not attempt to bypass VkApp and open your own connection to the X server, or directly call `XtAppInitialize()` or an equivalent function. For best results, you should always allow VkApp to handle the Xt initialization and event dispatching. VkApp is described in detail in Chapter 3, “The ViewKit Application Class.”

Also, you should use VkSimpleWindow or VkWindow for all top-level windows. These classes are described in detail in Chapter 4, “ViewKit Windows.”

As an example of some optional classes, consider the ViewKit dialog management facilities. These are intended to let you use dialogs easily and effectively. ViewKit automatically recycles dialogs (reusing the same dialog over and over for multiple purposes), which uses less memory and can lead to faster response times. It is also easy to add additional buttons to any dialog, to provide context-sensitive help on individual dialogs, and much more. The ViewKit dialog management facility is designed to be as flexible as possible, while minimizing the amount of work required of you. You can even write your own custom dialogs that take advantage of the dialog manager.

However, because the design of the ViewKit dialog management classes makes assumptions about the way typical applications use dialogs, the ViewKit dialog manager can't offer the same control that you could obtain by directly constructing and manipulating an Motif dialog. Should you encounter a situation where the behavior of the dialog manager doesn't match your application's needs, you can always take the same approach you would have to take if the dialog manager didn't exist: create and manipulate your own Motif dialog directly using Motif and Xt functions. This doesn't interfere with ViewKit in any way.

Before implementing your own mechanisms, you should be sure you understand the support offered by ViewKit. Situations in which it's necessary to duplicate functionality supported by ViewKit should be rare. On the other hand, extending the class library by deriving new classes, or writing completely new classes to meet application-specific needs, is a natural part of developing any application based on ViewKit or any C++ class library.

## Compiling and Linking ViewKit Programs

This section describes the software needed to compile and link ViewKit programs.

### Required Packages

To compile and link with the ViewKit libraries, you must install a C++ compiler and a Motif development environment (either 1.2 or 2.1), along with the ViewKit development option subsystems. Consult the ViewKit Release Notes for a complete list of subsystems that you must install on your system to compile and link ViewKit programs.

| Note: See “Required Packages (ViewKit 2.1 Addendum)” in Appendix B for ViewKit 2.1 subsystems.

The ViewKit development option contains the following subsystems:

ViewKit_dev.sw.base |  | You are required to install this subsystem, which contains the optimized, unshared C++ ViewKit libraries and include files. (The shared ViewKit libraries are included in the IRIX system software as the ViewKit_eoe.sw.base subsystem.)
ViewKit_dev.sw.debug |  | This subsystem contains the debug version of the optimized ViewKit libraries. You can optionally install this subsystem in addition to the ViewKit_dev.sw.base subsystem. Use this library for program debugging only.
ViewKit_dev.man.pages |  | The complete set of C++ reference pages (man pages) for ViewKit. This subsystem is optional, but recommended.
ViewKit_dev.man.relnotes |  | The online version of the ViewKit Release Notes. This subsystem is optional, but recommended.
ViewKit_dev.books.ViewKit_PG |  | The IRIS InSight™ version of this guide. This subsystem is optional, but recommended.
ViewKit_dev.sw.demo |  | Sample source code to various ViewKit programs. This subsystem is optional, but recommended.

The ViewKit_dev.sw.base subsystem installs the following libraries:

`libvk.a` |  | The basic ViewKit class library.
`libvkmsg.a` |  | Classes that support inter-process communication based on the ToolTalk™ library.
`libXpm.a` |  | A library that supports X pixmap creation. Some ViewKit classes use Xpm.

The ViewKit_dev.sw.debug subsystem installs the following libraries:

`libvk_d.a` |  | The debug version of the basic ViewKit class library.
`libvkmsg_d.a` |  | The debug version of the classes that support inter-process communication based on the ToolTalk library.

### Required Header Files

All ViewKit header files appear in `/usr/include/Vk`. In most cases, the header file for a given class is the class name followed by.h. For example, the header file for the VkWindow class is `<Vk/VkWindow.h>`. Some minor classes are grouped together into single header files. For example, the header file for the VkMenu class automatically includes the header information for every type of menu supported by ViewKit. These cases are noted in the text where appropriate.

You need to include Motif header files for only those Motif widgets that you explicitly use in a ViewKit program. ViewKit automatically includes any X or Motif header files required by ViewKit components that you use in your program.

### Required Libraries

You must link all ViewKit programs with the ViewKit library, `libvk`, and the Motif and X libraries. If you use an external help system with your application, you should link with the appropriate help library. (See Chapter 11, “Using a Help System With ViewKit” for more information.)

For example, to compile a file `hello.c++` to produce the executable `hello`, enter

    CC -o hello hello.c++ -lvk -lXm -lXt -lX11

If you are debugging a program, you might find it useful to compile your program with the debug libraries, which contain additional symbol table information.

## Getting Started

This section gives you information on example programs that you might find helpful when getting started with ViewKit programming. It first describes the simplest ViewKit program, which displays a window containing a single label, and discusses the structure of the program. Then, it discusses the demonstration programs provided with ViewKit.

### The Simplest ViewKit Program

Applications based on ViewKit must obey certain organizational conventions. To see how this organization works, consider Example 1-1, a simple ViewKit application that displays the label “hello” in a window.

Example 1-1. The Simplest ViewKit Program: hello.c++

    #include <Vk/VkApp.h>
    #include <Vk/VkSimpleWindow.h>
    #include <Xm/Label.h>

    // Define a top-level window class

    class HelloWindow: public VkSimpleWindow {

      public:
        HelloWindow (const char *name);
        ~HelloWindow();
        virtual const char* className();
    };

    // Construct a single rooted widget tree, and designate the
    // root of the tree as the window's view.  This example is very
    // simple, just creating a single XmLabel widget to display the
    // string "hello".

    HelloWindow::HelloWindow (const char *name) : VkSimpleWindow (name)
    {
        Widget label =  XmCreateLabel (mainWindowWidget(), "hello",
                                       NULL, 0);
        addView(label);
    }

    const char* HelloWindow::className()
    {
        return "HelloWindow";  // Identify this class
    }

    HelloWindow::~HelloWindow()
    {
        // Empty
    }

    // Main driver. Just instantiate a VkApp and a top-level window,
    // "show" the window and then "run" the application.

    void main ( int argc, char **argv )
    {
        VkApp        *app = new VkApp("Hello", &argc, argv);
        HelloWindow  *win = new HelloWindow("hello");

        win->show();
        app->run();
    }

To build this example, simply compile the file `hello.c++` and link with the ViewKit library, and the Motif and X libraries:

    CC -o hello hello.c++ -lvk -lXm -lXt -lX11

Running the `hello` program displays a window that says “hello,” as shown in Figure 1-1.

Figure 1-1. Result of Running hello

This example uses two classes: the VkApp class and an application-defined class, HelloWindow. The HelloWindow class is derived from the ViewKit VkSimpleWindow class.

First look at `main()`. All ViewKit applications start by creating an instance of VkApp. The arguments to this constructor specify the Xt-style class of the application, a pointer to argc, and the argv array. Instantiating a VkApp object opens a connection to the X server and initializes many other services needed by typical applications. VkApp is described in detail in Chapter 3, “The ViewKit Application Class.” Next, the `hello.c++` program instantiates a HelloWindow object that serves as the application's top-level window. The constructor for this class requires only a name for the window. Finally, the application concludes by calling the HelloWindow object's`show()` function and the VkApp object's `run()` function. The `run()` method never returns. The bodies of most ViewKit programs are similar to this short example.

Now look at the HelloWindow class. ViewKit encourages you to create classes to represent all major elements of the user interface. In this simple example, the only major user interface component is a top-level window that contains a label widget. ViewKit provides a class, VkSimpleWindow, that supports many features common to all top-level windows and that works closely with the VkApp class to implement various ViewKit features. To use the VkSimpleWindow class, you derive a new subclass and create a single-rooted widget tree that the window displays as its view. ViewKit applications do not have to create shell widgets directly.

The `hello.c++` example is so simple that the HelloWindow class creates only a single XmLabel widget. The XmLabel widget is created in the constructor and then designated as the window's view. More complex classes might create a manager widget and create other widgets as children, or might instantiate other objects, as well. Chapter 4, “ViewKit Windows,” describes how to create windows using ViewKit.

The `className()` member function is supported, by convention, by all ViewKit classes. This function is used by several ViewKit facilities and is discussed in “VkComponent Access Functions”.

### Demonstration Programs

The ViewKit_dev.sw.demo subsystem installs in the `/usr/share/src/ViewKit` directory several demonstration programs that illustrate different features of ViewKit. A few of the highlights include:

- `/usr/share/src/ViewKit/ProgrammersGuide` contains several of the example programs from this guide.

- `/usr/share/src/ViewKit/Components/CBrowser` contains the source for a component browser, which shows examples of many ViewKit components. You might find this particularly useful to run when you read the later chapters in this guide that describe the prebuilt components shipped with ViewKit.

- `/usr/share/src/ViewKit/Applications/PhoneBook` creates PhoneBook, a full-fledged application that keeps track of names, phone numbers, and addresses. PhoneBook uses a variety of ViewKit classes.

- `/usr/share/src/ViewKit/Applications/GLX` builds Rotate, a sample application that uses GLX to do GL rendering in an X window.

- `/usr/share/src/ViewKit/Applications/Inventor` builds IvClock, a ViewKit implementation of the Inventor clock sample program from Inventor 2.0.

Prev | Table of Contents | Next
Introduction |  | Chapter 2. Components