Volume 7A: XView Programming Manual

Likewise, xv_init() creates a server instance, so you cannot establish the initial server

after calling xv_init().

15.3.2 Connecting to Multiple Servers

You can establish connections to other servers as well as the server opened by xv_init()

by using xv_create() in the way shown above. The standard way for a user to specify a

connection to a server is the -display switch; to allow the user to specify a connection to

another server, you should provide an additional command-line option that you parse your-

self.

The following code segment allows the user to specify an additional server by using the com-

mand-line switch -display2:

Xv_Server server1, server2 = NULL;

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

/* XView has parsed all the args it knows -- now look for ours */

while (*++argv) {

if (!strcmp(*argv, "-display2")) {

if (!*++argv) {

fputs("Missing server name.\n", stderr);

exit(1);

}

server2 = xv_create(NULL, SERVER, XV_NAME, *argv, NULL);

}

}

if (server2 == NULL) {

fputs("Must specify second server.\n", stderr);

exit(1);

}

If you do this, a connection will be established for both servers.

Applications that have connected to multiple servers will typically exit when one of the X

servers goes down, causing the windows displayed on the other server to go away. To avoid

having the application exit, application programmers should consider forking separate

processes for each server connection. Thus losing a server connection can be handled in a

reasonable manner.

15.3.3 Getting the Server

One way to get the server to which the application is connected is from the Xv_Screen

object described in the previous section:

server = (Server)xv_get(xv_get(frame, XV_SCREEN), SCREEN_SERVER);

354 XView Programming Manual

With the server object, you can tell the server to synchronize with your application by cal-

ling:

Xv_Server server;

...

xv_set(server, SERVER_SYNC, TRUE, NULL);

The SERVER_SYNC attribute flushes the request buffer and waits for all events and errors to be

processed by the server. When the argument is TRUE, as above, SERVER_SYNC discards all

events on the input queue.

SERVER_SYNC_AND_PROCESS_EVENTS has the same behavior as SERVER_SYNC, but this

processes any events that arrive as a result of the XSync().

Xv_Server server;

xv_set(server, SERVER_SYNC_AND_PROCESS_EVENTS, NULL);

Note that this attribute takes no value—you specify it and no other attributes. This attribute

makes sense only in xv_set().

The attributes SERVER_ATOM and SERVER_ATOM_NAME help manage atoms. SERVER_ATOM is

equivalent to XInternAtom() (with the only_if_exists flag set to false). It caches

the results on the server object so that subsequent requests for the same atom will not require

a round-trip to the X server. For example:

Atom atom;

atom = (Atom) xv_get(server_object, SERVER_ATOM, "TIMESTAMP");

SERVER_ATOM_NAME is equivalent to XGetAtomName(). It also caches the results on the

server object. The returned string is maintained by XView and should not be modified or

freed. XView will free up all strings associated with atoms on that server when the server

object is destroyed. For example:

char *atom_name;

atom_name (char *)xv_get(server_object, SERVER_ATOM_NAME, atom);

15.4 Server Images

A server image is a graphic image stored on the X server. Images on the client side can be

stored as XImages or as memory pixrects.* The XView Server_image object is not

equivalent to X Pixmaps, although pixmaps are part of the Server_image object. Even

though pixmaps are stored on the server, the XView object is a client-side object. Because it

is an XView object, you can query the dimensions of a Server_image by using XV_WIDTH

or XV_HEIGHT, which is something you cannot do with X11 Pixmaps. The server image

structure is defined in <xview/svrimage.h> as follows:

typedef struct {

Xv_drawable_struct parent_data;

*The term pixrect is a data type brought over from SunView.

Nonvisual Objects

Nonvisual Objects 355

Xv_opaque private_data;

Xv_embedding embedding_data;

Pixrect pixrect;

} Xv_server_image;

15.4.1 Creating Server Images

Applications that wish to use the SERVER_IMAGE package should include <xview/svrim-

age.h>. Server_image objects contain graphic data that is used in icons, cursors, panel

buttons—in fact, just about everything in XView that contains graphics. The

Server_image object is created using xv_create() in the following manner:

#include <xview/svrimage.h>

...

Server_image image;

image = (Server_image)xv_create(owner, SERVER_IMAGE,

attrs

,

NULL);

The owner in the call to xv_create() is an Xv_Screen object. The server that owns this

screen owns the newly created image. If the owner is NULL, then the default screen is used.

The dimensions of Server_image objects are 16 by 16 by 1, unless the attributes

XV_WIDTH, XV_HEIGHT or SERVER_IMAGE_DEPTH are specified. The bitmap data for the

server image may be set using either SERVER_IMAGE_BITS or SERVER_IMAGE_X_BITS

depending on the format of the data. The data format choices are arrays of short or char

types. X11 bitmap data is represented as array of chars, while Sun’s pixrect library repre-

sents the data as an array of shorts.* The following code segment uses SERVER_IMAGE_BITS

to produce a one-bit deep image that looks like a trash can:

short image_bits[ ] = {

#include <images/trash.icon>

};

Server_image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 32,

XV_HEIGHT, 30,

SERVER_IMAGE_BITS, image_bits,

NULL);

Here, the trash can icon was created with its bits stored in an array of shorts. A call to

xv_get() with the attribute SERVER_IMAGE_BITS returns the bits for the server image.

Manipulating this data does not change the appearance of the server image. A call to

xv_set() using SERVER_IMAGE_BITS to specify a new bitmap is required to change a

server image.

*Many of Sun’s existing applications should use SERVER_IMAGE_BITS when porting to XView. This attribute

must be used in order to load bitmap data created by iconedit.

356 XView Programming Manual

To load an image stored as an array of chars (the format used by X11), use

SERVER_IMAGE_ X_BITS:

#include <X11/bitmaps/xlogo32>

xlogo_image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_HEIGHT, xlogo32_width,

XV_WIDTH, xlogo32_height,

SERVER_IMAGE_X_BITS, xlogo32_bits,

NULL);

In both of these cases, the file specified on the #include line must be accessible at the time

the program is compiled. Once compiled, the data for the image is stored in the program and

the file is no longer needed (e.g., the file may be deleted and the program still displays the

image).

Rather than including the file containing the image’s bitmap data, you could specify the

actual file:

char *file = "/usr/include/X11/bitmaps/xlogo32";

server_image = (Server_image)xv_create(NULL, SERVER_IMAGE,

SERVER_IMAGE_BITMAP_FILE, file,

NULL);

Be aware that this file must exist and be accessible by any person who runs this program at

run time. If for some reason the file is not accessible, then an error is generated. And

because the program may be run from any directory, a full pathname should be specified. As

shown, the file points to a static string, but file could have a value that is changed by

selecting from a list of bitmap filenames. In this case, the code fragment could use

xv_set() to set the filename and thus, the Server_image’s data. Whenever xv_set()

is used to change the data of the image like this, the values of XV_WIDTH and XV_HEIGHT are

automatically updated.

Many XView objects require Server_images as values (such as MENU_IMAGE_STRINGS

in the MENU package). If you have already created a pixmap and wish to attach it to a server

image, you can use:

image = (Server_image)xv_set(NULL, SERVER_IMAGE,

SERVER_IMAGE_PIXMAP, pixmap,

NULL);

The attribute SERVER_IMAGE_PIXMAP can also be used in xv_get() to return the XID of

the pixmap associated with the Server_image.

Normally, a Server_image destroys its pixmap when a new pixmap is created using

SERVER_IMAGE_BITS, SERVER_IMAGE_X_BITS, or SERVER_IMAGE_PIXMAP. This default

behavior can be turned off by setting the SERVER_IMAGE_SAVE_PIXMAP attribute to TRUE.

Be sure to maintain a handle to the pixmap if you specify this attribute and destroy the

Server_image.

If the depth of an image is unspecified, it defaults to 1. To create a color image, use

SERVER_IMAGE_DEPTH to specify an alternate depth that can support color. You can also

specify a colormap to use with this image by specifying

SERVER_IMAGE_CMS. This is used

for multiplane color images and must be specified before the image bits are set. The

colormap specified is assumed to have been created already using the CMS package.

Nonvisual Objects

Nonvisual Objects 357

Example 15-3 demonstrates how to use a server image by creating a frame with a panel. On

the panel is a button that uses a server image as the PANEL_LABEL_IMAGE. The bits used are

the same as the trash.icon used above.

Example 15-3. The svrimage.c program

/*

* svrimage.c -- demonstrate how a server image can be created and

* used. The "bits" used to create the image are taken arbitrarily

* from <images/trash.icon>

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/svrimage.h>

#include <X11/Xlib.h>

short image_bits[ ] = {

0x0000,0x0000, 0x0000,0x0000, 0x0000,0x0000, 0x0000,0x0000,

0x0007,0xE000, 0x0004,0x2000, 0x03FF,0xFFC0, 0x0200,0x0040,

0x02FF,0xFF40, 0x0080,0x0100, 0x00AA,0xAB00, 0x00AA,0xAB00,

0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00,

0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00,

0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00,

0x00AA,0xAB00, 0x00AA,0xAB00, 0x00AA,0xAB00, 0x0091,0x1300,

0x00C0,0x0200, 0x003F,0xFC00

};

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame;

Server_image image;

Panel panel;

void exit();

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

image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 32,

XV_HEIGHT, 30,

SERVER_IMAGE_BITS, image_bits,

NULL);

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

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

(void) xv_create(panel, PANEL_MESSAGE,

PANEL_LABEL_IMAGE, image,

PANEL_NOTIFY_PROC, exit,

NULL);

window_fit(panel);

window_fit(frame);

xv_main_loop(frame);

}

358 XView Programming Manual