Volume 7A: XView Programming Manual

3

Creating XView Applications

This chapter covers the XView programming interface. It describes the basic XView distri-

bution and how you use it to compile and link XView applications. It also presents the

proper structure for XView applications. The structure can be summarized as:

• Initialize XView using xv_init().

• Create a top-level window (FRAME) to manage subwindows.

• Add subwindows as children of the FRAME.

• Add objects to subwindows.

• Specify notification callbacks and select input events.

• Call xv_main_loop() to start the dispatching of events.

This chapter also discusses error recovery procedures.

3.1 Interface Overview

This section gives an overview of the XView programming interface. It covers reserved

words and naming conventions in XView. It also includes a complete sample program,

which we will look at more closely when describing the calling sequence for a program.

3.1.1 Compiling XView Programs

To compile an XView program, you must link with the XView library and the

OPEN LOOK

graphics library. These libraries comprise the entire XView Toolkit. XView is written for

X11, of course, so you need to add the standard X library, which contains all the Xlib rou-

tines.

Thus, to compile a typical XView application whose source is myprog.c, you use the com-

mand:

% cc myprog.c –lxview –lolgx –lX11 –o myprog

Creating XView

Applications

Creating XView Applications 41

3.1.2 XView Libraries

The XView library is made up of two other libraries: libxvol.a and libxvin.a. XView func-

tions are found mostly in the library libxvol.a. These libraries include the code to create and

manipulate high-level objects such as frames, panels, scrollbars and icons. These packages

in turn call routines in libxvin.a to create and manipulate windows and interact with the

Notifier. These libraries are both included in the library libxview.a. The XView libraries call

routines in the Xlib library (libX11.a) that do the drawing on the screen.

The library specified by -lolgx is the OPEN LOOK graphics library. This library has rou-

tines that draw all the OPEN LOOK objects such as scrollbars and panel items. This library is

not called from the client application; it is only called by the internals to XView.

Many of the images used by this library come from special fonts that must be installed on

your X11 server. All servers newer than X11R4, as well as the X11/NeWS server, should

have these fonts.

3.1.3 Header Files

The basic definitions needed by an XView application (windows, frames, menus, icons and

cursors) are obtained by including the header file <xview/xview.h>. All XView applications

should have the line:

#include <xview/xview.h>

This header file includes many other header files that set up standard types. It also declares

external functions and includes some system-specific header files that are required by all the

XView header files.* Once <xview/xview.h> has been included, other include files specific to

the packages are included. Each object package has its own header file to declare object

types, to provide definitions for frequently used macros and to make external definitions for

routines that are specific to that object’s package. Frequently these files include other files,

which in turn may include other packages or system header files.

For instance, if your code uses the FRAME, PANEL and FONT packages, then these include files

must be specified:

#include <xview/xview.h>

#include <xview/frame.h>

#include <xview/panel.h>

#include <xview/font.h>

However, investigation shows that some header files include other header files by default.

For example, <xview/xview.h> includes <xview/frame.h>. There are “wrappers” inside the

XView header files which prevent any one of them from being included more than once.

*XView also includes C++ bindings for all its public functions.

42 XView Programming Manual

3.1.4 Naming Conventions

All the examples throughout this manual follow a consistent method in the naming of data

types, package names, and even variable names. Because of the large number of packages

and data types, you could easily confuse what a lexical string represents. Therefore, you are

advised to follow certain criteria when naming variables and declaring data types that are not

specific to XView. Whatever naming convention you choose, you should always try to be

consistent.

3.1.4.1 Reserved names

XView reserves names beginning with the object types, as well as certain other prefixes, for

its own use. The prefixes in Table 3-1 should not be used by applications in lowercase,

uppercase, or mixed case.

Table 3-1. Reserved Prefixes

attr_ icon_ server_image_

canvas_ menu_ string_

cms notice_ termsw_

cursor_ notify_ text_

defaults_ panel_ textsw_

dnd_ pixrect_ tty_

dragdrop_ pr_ ttysw_

drop_ pw_ win_

ei_ r1_ window_

es_ rect_ wmgr_

ev_ screen_ xv_

event_ scroll_

font_ scrollbar_

frame_ selection_

fullscreen_ seln_

generic_ server_

To help you choose what not to use for data types and other lexical tokens in your applica-

tion, review Table 2-1, “XView Objects, Owners, Packages, and Data Types.”

3.1.5 Example of XView-style Programming

The flavor of the XView programming interface is illustrated by the code in Example 3-1.

This program, quit.c, creates a frame containing a panel with one item: a button labeled Quit.

There are a few things to notice in the program. First, note the NULL that terminates the attri-

bute lists in the xv_create() and xv_set() calls. The most common mistake in using

attribute lists is to forget the final NULL. This will not be flagged by the compiler as an error.

Creating XView

Applications

Creating XView Applications 43

The results are actually unpredictable, but the most common result is that XView will gener-

ate a run-time error message and the program will exit.

Second, the object returned by the xv_create() for the PANEL_BUTTON is not stored into a

variable. This is primarily because it is not needed by any other portion of the code. One of

the most common programming inefficiencies is the use of global variables when they are not

needed. If you are not going to reference an object created via xv_create(), you should

not retain its handle. If you need its handle, but only temporarily, then it should be a local

variable, not a global or static one. For example, the panel variable (type Panel) is

used as a local variable.

Example 3-1. The quit.c program

/*

* quit.c -- simple program to display a panel button that says "Quit".

* Selecting the panel button exits the program.

*/

#include <xview/xview.h>

#include <xview/frame.h>

#include <xview/panel.h>

Frame frame;

main (argc, argv)

int argc;

char *argv[ ];

{

Panel panel;

void quit();

xv_init (XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

frame = (Frame)xv_create (NULL, FRAME,

FRAME_LABEL, argv[0],

XV_WIDTH, 200,

XV_HEIGHT, 100,

NULL);

panel = (Panel)xv_create (frame, PANEL, NULL);

(void) xv_create (panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Quit",

PANEL_NOTIFY_PROC, quit,

NULL);

xv_main_loop (frame);

exit(0);

}

void

quit()

{

xv_destroy_safe(frame);

}

Figure 3-1 shows the output resulting from quit.c. In the sections that follow, we are going to

look at how this program demonstrates the structure of XView programs.

44 XView Programming Manual

Figure 3-1. A frame containing a Quit button

3.2 Initializing XView

Initializing the XView system should be done as soon as possible in the application. The

xv_init() function performs many tasks, including:

• Opening the connection to the server.

• Initializing the Notifier.

• Initializing the Resource Manager database.*

The form of xv_init() is:

Xv_Server

xv_init(

attrs

)

<attribute-value list>

attrs

;

By default, xv_init() opens a connection to the server described by the DISPLAY envi-

ronment variable. With the appropriate command-line options (discussed later), a different

server may be specified. No matter which server is ultimately used, xv_init() returns a

handle to that server object.

All subsequent XView objects that are created will use this server by default. This includes

the physical screen(s) and resources. If you want your application to span multiple servers,

you need to open a separate connection to those servers via the SERVER package. For further

information on how to do this and other details of the SERVER package, see Chapter 15, Non-

visual Objects, for details.

*See Chapter 17, Resources, for more information about the resource database.

Creating XView

Applications

Creating XView Applications 45