Volume 7A: XView Programming Manual

3.2.1 Using xv_init( )

Initialization should be done before the application attempts to parse its own command-line

options. Since many programs tend to have command-line parameters, a program tends to

report unknown parameters as illegal arguments. Because XView parameters can also be

specified on the command line to the application, the program must be able to distinguish

between the application’s parameters and XView’s parameters.

xv_init() accepts the attributes XV_INIT_ARGS and XV_INIT_ARGC_PTR_ARGV for pur-

poses of parsing command-line arguments. These attributes both take two parameters as val-

ues: argc and argv. These are typically the same ones passed into main(). Using the

XV_INIT_ARGC_PTR_ARGV attribute, the xv_init() function can be told to modify argc

and argv by removing parameters that are XView-specific, like so:

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

When xv_init returns, argv contains only those parameters that are not specific to

XView, and the application can now assume that all remaining arguments are specific to the

application. So a hypothetical command line might look like this:

% program –display maui:0

The command line is first parsed by xv_init(), and in this case, all arguments are stripped

from the argv variable, leaving just argv[0], whose value is program. argc is modi-

fied to have the value 1 (it was originally 3). The example command-line parameters change

the default server to be the X server running on the machine named maui.

The macro XV_INIT_ARGS is similar:

xv_init(XV_INIT_ARGS, argc, argv, NULL);

Here, argc and argv are not modified at all and are returned unchanged by xv_init().

Therefore, the value, not the address, of argc is used. This method is less advantageous for

initializing XView because it leaves the application with the responsibility of parsing XView

command-line parameters later.

NOTE

Once XView has been initialized, subsequent calls to xv_init() are ignored,

as are all parameters consisting of

XV_INIT_ARGS or XV_INIT_

ARGC_PTR_ARGV

.

A common error that users make is to enter bad command-line arguments. These arguments

can be specific to XView or specific to the application, so XView handles the XView-specific

argument and then expects the programmer to handle application-specific arguments.

Upon receiving a bad argument, XView prints an error message, indicating what XView-

specific values are legal, and then calls exit(1). The function that provides this message is

specified by the attribute XV_USAGE_PROC. In most cases, you want to leave this alone

because it is not the way you handle application-specific arguments.

46 XView Programming Manual

The attribute XV_ERROR_PROC is used to install an error recovery routine. See Chapter 24,

Error Recovery, for details about error handling.

3.3 Creating and Modifying Objects

After the system has been initialized, objects can be created and modified using

xv_create(), xv_find(), xv_get(), and xv_set(). A closer look at

xv_create() and xv_find() shows how these functions can be used to create new

objects or find existing objects with particular attributes from various packages.

3.3.1 Using xv_create( )

xv_create() is typically used as shown in Example 3-2.

Example 3-2. xv_create() creates XView objects

#include <xview/xview.h>

main(argc, argv)

char *argv[ ];

{

Frame frame;

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

frame = (Frame)xv_create(NULL, FRAME, NULL);

xv_main_loop(frame);

}

In Example 3-2, a frame is created from the FRAME package and no additional attribute-value

pairs are specified. Therefore, all the default properties from the frame class are set into the

instance of this new frame when it is created.

The form of xv_create() is:

Xv_object

xv_create(owner, package,

attrs

)

Xv_object owner;

Xv_pkg package;

<attribute-value list>

attrs

In most cases, owner is another XView object. As shown in the example, when the frame is

created, it has no owner, per se. This means that the owner should default to a pre-specified

owner that XView has in mind. Defaulting is not always possible, but for this base frame, the

default owner is the root window of the current server. As a child of the root window, the

frame is under the constraints that the window manager might impose upon it (the colormap,

for example).

Objects must have an owner for several reasons. One reason is that the X server may not be

running on the same machine as the application (client) program. Therefore, because XView

is running on the client side, objects that are created by the application have to contact the

Creating XView

Applications

Creating XView Applications 47

server. There could be more than one server to contact if the application supports multiple

displays or runs on several machines simultaneously. To do this, XView needs to know what

server or screen a particular object is associated with.

Another reason is that certain attributes are inherited from the owner, such as color and event

masks. It is up to the individual package to determine what it inherits from its owner.

When owner is NULL, the owner of the object being created is either defaulted to a predeter-

mined owner, or the object is said to have delayed binding. That is, the object is not associ-

ated with any other object until it is displayed on the screen. A scrollbar that is created with

a NULL owner will not be displayed until it is attached to an object, and this object becomes

its owner. Most objects are required to have owners at the time of their creation. Frames,

windows and fonts must have a valid (default) owner because they need to access the

screen’s default colors, available fonts and so on.

Table 3-2 shows the default owner if owner is NULL in the call to xv_create.

Table 3-2. Default Ownership of Objects

Object’s Package Owner If Owner is NULL

CANVAS Frame The window manager of

xv_default_screen

CMS

Screen xv_default_screen

CURSOR Window, screen or anything that The window manager of

returns XV_ROOT xv_default_screen

DRAGDROP Window NULL owner not allowed

DROP_SITE_ITEM Window NULL owner not allowed

FRAME

Another frame or the root window The window manager of

xv_default_screen

Panel Items

Panel NULL owner not allowed

MENU Ignores its owner Always use NULL

NOTICE Window NULL owner not allowed

PANEL Frame xv_default_screen

Menu Items

Menu Allows delayed binding

ICON Same as cursor Same as cursor

SCROLLBAR

An openwin object Allows delayed binding

SCROLLABLE_PANEL Frame NULL owner not allowed

SCREEN, Server xv_default_server

FULLSCREEN

SELECTION_ITEM

Selection Owner NULL owner not allowed

SELECTION_OWNER Window NULL owner not allowed

SELECTION_REQUESTOR Window NULL owner not allowed

SERVER

Ignores its owner Always use NULL

48 XView Programming Manual

Table 3-2. Default Ownership of Objects (continued)

Object’s Package Owner If Owner is NULL

SERVER_IMAGE Screen xv_default_screen

TEXT Frame The window manager of

xv_default_screen

The object that is returned from xv_create() is an opaque data type called Xv_object.

The return value should be coerced into the type of the object being created.

Each time xv_create() is used, it creates a new and entirely different object. The type of

object that is returned depends on the package specified.

Panel panel;

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

Here, a panel is created as a child of a frame. As in the previous example, there are no attri-

bute-value pairs specified, so the panel is created with all the default values intrinsic to a gen-

eric panel object from the PANEL package. The panel is then installed inside the frame

accordingly. Panel items can be installed inside the panel as:

Panel_item button;

button = (Panel_item)xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Quit",

PANEL_NOTIFY_PROC, quit,

NULL);

Here, xv_create() is used to create a panel item of type PANEL_BUTTON. This is a special

type of object that is created inside of panels only. That is why the owner of the item is the

panel created in the previous example. In the attribute-value list provided in this example,

the label is set by specifying the PANEL_LABEL_STRING attribute and a string as the value

portion of the pair. Similarly, the callback routine specified is the routine called quit().

Because the intent of panel buttons is to select them with the pointer, the callback routine is

the function to call if the user presses the mouse button in the panel button item.

3.3.2 Using xv_find()

In all the examples so far, the routine xv_create() has been used to create new objects of

different types or classes. However, it might not always be possible to know whether or not a

particular object has been created. The best way to handle such cases is to use xv_find().

If the object has been created, xv_find() returns the handle to the pre-existing object; if

not, xv_find() creates it. The definition of the routine follows:

Xv_opaque

xv_find (owner, package,

attrs

)

Xv_object owner;

Xv_pkg package;

<attribute-value list>

attrs

;

Creating XView

Applications

Creating XView Applications 49

As you can see, the form of xv_find() is the same as xv_create(). Fonts are objects

that usually only need to be created once and are then used throughout the application wher-

ever necessary. For example, say the application needs to use the font named fixed (because

it is usually available on any X server and is almost guaranteed to be found). Several places

in the application need to use the font, but only one instance of the font needs to be created.

To avoid multiple instances of the object, the following function call is made:

Xv_Font my_font;

my_font = xv_find(frame, FONT,

FONT_NAME, "fixed",

NULL);

This code segment demonstrates how xv_find() tries to find an existing font named fixed

that has already been created by the application. If the application has not yet created this

font, then xv_find() acts just like xv_create(), and a new font is created. This func-

tion is not intended to replace xv_create() at all. It is intended to be used in the case

where only one instance of an object is desired and that one instance is shared throughout the

application. While you could use xv_find() rather than xv_create() in the other

examples shown so far, the problem arises if you need two copies of a particular instance of

an object. For example, if you were going to create another PANEL using all the default val-

ues of the PANEL package, then xv_find() would return the previously created panel. Any

new objects attached to that panel would also be attached to the other panel because they are,

in fact, one and the same.

As shown, fonts are frequent users of the xv_find() function.*

3.3.3 Using xv_destroy()

The correct way for an XView application to exit is to destroy all objects created and call

exit() with an appropriate exit status. The function xv_destroy() destroys an instance

of an XView object. The function xv_destroy_safe() does the same thing but ensures

that it is safe to do so.† In general, it is better to be safe than sorry. The definition of these

routines are as follows:

int

xv_destroy_safe(object)

Xv_opaque object;

int

xv_destroy(object)

Xv_opaque object;

The return value from the routines is either XV_OK or XV_ERROR. Example 3-2 in Section

3.1.5, “Example of XView-style Programming,” shows a base frame containing a panel

subwindow with one panel button created inside it. The callback routine for the panel item,

quit(), is intended to exit the application. Rather than actually calling exit(), a more

elegant way to exit would be to destroy all the objects that have been created. If a text

*Chapter 16, Fonts, describes how to create fonts using xv_find().

†Chapter 20, The Notifier, discusses the difference between a safe and an immediate destruction of an object.

50 XView Programming Manual