Status XShmGetImage (display, d, image, x, y, plane_mask) Display *display; Drawable d; XImage *image; int x, y; unsigned long plane_mask;

The following table lists each argument and its description.

Argument	Description
display	The display of interest.
d	The source drawable.
image	The destination XImage.
x	X-offset within the source drawable.
y	Y-offset within the source drawable.
plane_mask	The planes that are to be read.

To destroy a shared memory XImage, first instruct the server to detach from it, then destroy the segment itself. The following example illustrates how to destroy a shared memory XImage:

XShmDetach (display, shminfo); XDestroyImage (image); shmdt (shminfo.shmaddr); shmctl (shminfo.shmid, IPC_RMID, 0);

6.3.1.3 Using Shared Memory Pixmaps

Unlike X images, for which any image format is usable, the shared memory extension supports only a single format for the data stored in a shared memory pixmap (XYPixmap or ZPixmap). This format is independent of the depth of the image and independent of the screen. (For 1-bit pixmaps the format is irrelevant.)

The XShmPixmapFormat routine returns the shared memory pixmap format for the server. The XShmPixmapFormat routine has the following format:

int XShmPixmapFormat (display) Display *display;

Your application can only use shared memory pixmaps in the format returned by the XShmPixmapFormat routine (including bits-per-pixel). To create a shared memory pixmap do the following:

• Create a shared memory segment and shminfo structure exactly the same way as is listed for shared memory XImages steps 1 through 4 (see Section 6.3.1.2). While it is not necessary to create an XImage first (step 1), doing so incurs little overhead and provides an appropriate bytes_per_line value to use.
• Call the XShmCreatePixmap routine, which has the following format:

  Pixmap XShmCreatePixmap (display, d, data, shminfo, width, height, depth); Display *display; Drawable d; char *data; XShmSegmentInfo *shminfo; unsigned int width, height, depth;

  
  The arguments are the same as for XCreatePixmap (see the X Window System) except for two additional parameters, data and shminfo. The data parameter is the pointer to the shared memory segment and is the same as the shminfo.shmaddr field. The shminfo parameter is the same as the previous structure.
  If successful, a pixmap is returned, which you can manipulate. You can manipulate its contents directly through the shared memory segment. Shared memory pixmaps are destroyed with the XFreePixmap routine, although you should detach and destroy the shared memory segment (see step 4 in Section 6.3.1.2).

V1.1

Starting with DECwindows Motif for OpenVMS Version 1.1, DECwindows Motif supports the X Image Extension (XIE). XIE allows image display processing using resources on the server side of the X client-server model. XIE eliminates the need to transmit image data repeatedly from the client to the server and also allows data to be transmitted in compressed form, reducing the network load.

DECwindows Motif includes the XIE client side sharable library (XIE$SHRLIB.EXE) and C language header files. These allow applications to communicate with any X11 server that supports the XIE extension.

An XIE program uses a structure called the XIEImage to describe image data on the client side. This general mechanism describes data that the destination server is incapable of processing. Consult the documentation for the server system for information on what data types and sizes are supported. Unless the documentation specifies different limits, the server is capable of processing unsigned byte (UdpK_DTypeBU), unaligned bit field (UdpK_DTypeVU), and aligned bit field (UdpK_DTypeV) data, with a maximum depth of 8 bits per pixel per component. The XIE client library supports these data types, as well as unsigned word (UdpK_DTypeWU), and a depth of up to 16 bits per pixel per component.

Although the XIE protocol and programming interface have been standardized for X11R6, DECwindows Motif has not yet migrated to the latest implementation of this protocol.

6.4 DECwindows Extensions to Motif

The following sections describe features related to DECwindows extensions to the X Window System.

6.4.1 SVN Widget Supports Extended Selection

V1.2--6

The Structured Visual Navigation (SVN) widget now allows users to extend a range of selection using the Shift+Down-Arrow key sequence. Note that this change has also been applied to the sample program SVNMSAMPLE.C.

6.4.2 DXmCSText Input Method Support

V1.2

X11R5 input method support was added to the DXmCSText widget. Specify input methods using the vendor shell XmNinputMethod resource. However, to maintain backward compatibility, the existing input method resources DXmNinputMethod and DXmNinputMethodType are still available.

6.5 Application Programming

The following sections describe features related to application programming.

6.5.1 Drag-and-Drop Enabled Widgets

V1.2

The drag-and-drop feature lets you move or copy information between widgets. This feature is provided primarily for programmers to incorporate the feature into their applications.

All DECwindows Motif for OpenVMS Version 1.2 and higher applications support the drag-and-drop feature, with the exception of Notepad. DECwindows Mail supports drag-and-drop in all windows except the main message area, where DECwindows Mail has its own drag-and-drop feature; you can use MB2 to move messages around with the SVN interface.

Drag-and-drop functionality has been implemented in the widgets listed in Table 6-1.

Table 6-1 Drag-and-Drop Widgets

Widget	Drag Operation	Drop Operation
XmText	copy and move	copy and move
XmTextField	copy and move	copy and move
XmLabel	copy
XmPushButton	copy
XmToggleButton	copy
XmList	copy

For information about how to include additional drag-and-drop functionality in applications and for an example of a drag-and-drop program, see the Open Software Foundation: OSF/Motif Programmer's Guide, Revision 1.2 manual.

6.5.2 CDA Programming

This section describes features and changes related to CDA programming.

6.5.2.1 Changes to the CDA Programming Interface

V1.2

This section describes the changes to the programming interface for this version of CDA Run-Time Services.

This version provides a new set of header files that define CDA constants, types, and routines using portable naming conventions. By using these new naming conventions, you can use a wider variety of C compilers to minimize the amount of system-specific code in your CDA applications.

The names of the new set of header files are the same as the names of the previous set of header files, except that the dollar sign ($) has been removed. For example, the cda$msg.h include file is now called cdamsg.h. Other examples include the following: The DDIF$K_DSC_MAJOR_VERSION symbol is now declared as DDIF_K_DSC_MAJOR_VERSION, and the CDA$_NORMAL status value is now defined as CDA_NORMAL.

The previous set of header files is also included in this version, but these files will no longer be updated. Changes introduced since the release of DECwindows Motif Version 1.1 (for example, the new definitions for audio support), are available only in the new set of header files. To use the new CDA features, change the file names in your source code.

The new set of header files supplements the previous set of header files. If you want to write ANSI-compliant applications using CDA definitions and CDA Toolkit calls, use the new set of header files. However, you can continue to use the header files that define symbols containing the dollar sign ($) provided you choose a non-ANSI compilation mode.

By using the previous set of header files, you can successfully build existing source code that uses the previous naming conventions.

See Table 6-2 for a list of new header file names.

Table 6-2 New Header File Names

Previous Name	New Name
cda$def.h	cdadef.h
cda$msg.h	cdamsg.h
ddif$def.h	ddifdef.h
dtif$def.h	dtifdef.h
cda$ptp.h	cdaptp.h
cda$typ.h	cdatyp.h
dvr$msg.h	dvrmsg.h
dvr$cc_def.h	dvrccdef.h
dvr$cc_ptp.h	dvrccptp.h
dvr$decw_def.h	dvrwdef.h
dvr$decw_ptp.h	dvrwptp.h

6.5.2.2 Changes to CDA External Reference Processing

V1.2

CDA Run-Time Services supports relative file specifications for external references. Relative references are also supported: that is, a reference where the directory path is not fully specified but is relative to the directory path of the parent document.

6.5.2.3 Restructuring CDA Shareable Images

V1.2

The CDA Viewer includes two shareable images to allow installation on systems where DECwindows is not installed.

In DECwindows Motif for OpenVMS Version 1.2 software, shareable images that use the X services were renamed. Table 6-3 lists the shareable images in the various versions of the CDA Viewer.

Table 6-3 Names of Shareable Images

CDA Version	Image Name	Description
Version 1.6	CDA$ACCESS	CDA Run-Time Services shareable image.
	DDIF$VIEWSHR	Callable viewer widget.
Version 1.7	CDA$ACCESS	CDA Run-Time Services shareable image.
	DDIF$VIEWSHR DDIF$DECW_VIEWSHR DDIF$CC_VIEWSHR	The DDIF$DECW_VIEWSHR widget is a callable viewer widget that uses the LIB$FIND_IMAGE_SYMBOL routine to invoke the DDIF$DECW_VIEWSHR (DECwindows interface) and DDIF$CC_VIEWSHR (character-cell interface) widgets.
Version 1.8A or later	CDA$ACCESS	CDA Run-Time Services shareable image.
	DDIF$VIEWSHR12	The DDIF$VIEWSHR12 widget is a callable viewer widget that uses LIB$FIND_IMAGE_SYMBOL to invoke the DDIF$DECW_VIEWSHR12 (DECwindows interface) and DDIF$CC_VIEWSHR (character-cell interface) widgets.

By using the LIB$FIND_IMAGE_SYMBOL routine to reference the entry points to the DDIF$DECW_VIEWSHR, DDIF$DECW_VIEWSHR12, and DDIF$CC_VIEWSHR images, an application can dynamically determine whether it can execute in a given environment. The DDIF$VIEW.EXE application now replaces this routine.

The previous DDIF$VIEWSHR.EXE shareable image is still included to maintain compatibility with applications linked against it. However, new applications (and previous applications that take advantage of new features) should use the new shareable images.

6.5.3 DECterm Programming

V1.2--3

DECterm supports the following input cursors: cross-hair, rubber-band line, diamond, and rubber-band rectangle. To select input cursors use the S(C(In)) command. Table 6-4 shows the values of n.

Table 6-4 ReGIS Input Cursors---Cursor styles and Values

Cursor Style	Variable n
Cross-hair	Omitted
Cross-hair (default)	0
Diamond	1
Cross-hair	2
Rubber-band line	3
Rubber-band rectangle	4

V1.2

The following page-movement escape sequences are implemented in DECterm:

NP <CSI> Pn U Next Page PP <CSI> Pn V Previous Page PPA <CSI> Pn P Page Position Absolute PPB <CSI> Pn R Page Position Backward PPR <CSI> Pn Q Page Position Relative

Note that "Pn" is the number of pages to move; the exception is PPA, where "Pn" is the actual page number.