V1.2

Users familiar with emacs may want to add the following translations to their DECW$XDEFAULTS.DAT files:

*XmText.translations: Mod1<Btn3Down>: scroll-cursor-vertically()\n\ Mod1<Btn3Motion>: scroll-cursor-vertically()\n\ Ctrl<key>a: beginning-of-line()\n\ Ctrl<key>b: backward-character()\n\ Ctrl<key>d: delete-next-character()\n\ Ctrl<key>e: end-of-line()\n\ Ctrl<key>f: forward-character()\n\ Ctrl<key>g: beep()\n\ Ctrl<key>h: delete-previous-character()\n\ Ctrl<key>i: cut-primary()\n\ Ctrl<key>j: newline-and-indent()\n\ Ctrl<key>k: set-anchor() end-of-line() key-select() cut-clipboard()\n\ Ctrl<key>l: redraw-display()\n\ Ctrl<key>m: newline()\n\ Ctrl<key>n: next-line()\n\ Ctrl<key>o: newline-and-backup()\n\ Ctrl<key>p: previous-line()\n\ Ctrl<key>v: next-page()\n\ Ctrl<key>w: cut-clipboard()\n\ Ctrl<key>y: paste-clipboard()\n\ Ctrl<key>z: scroll-one-line-up()\n\ Mod1<key>b: backward-word()\n\ Mod1<key>d: delete-next-word()\n\ Mod1<key>f: forward-word()\n\ Mod1<key>h: delete-previous-word()\n\ Mod1<key>i: copy-primary()\n\ Mod1<key>k: delete-to-end-of-line()\n\ Mod1<key>v: previous-page()\n\ Mod1<key>w: copy-clipboard()\n\ Mod1<key>z: scroll-one-line-down()\n\ Mod1 Shift<key>greater: end-of-file()\n\ Mod1<key>less: beginning-of-file()\n\ Mod1<key>]: forward-paragraph()\n\ Mod1<key>[: backward-paragraph()

3.17.11 View Example Program

V1.2

The view program is similar to the DCL command TYPE/PAGE using Motif with internationalization support. It allows you to view files in several languages.

The command file DECW$EXAMPLES:FILEVIEW.COM is provided, which allows you to select a language. Valid languages are French, English, and German. To select a language, perform the following commands:

$ SET DEFAULT DECW$USER_DEFAULTS $ @DECW$EXAMPLES:FILEVIEW language

This command file copies the .UID and .DAT files to the current directory. It sets the appropriate locale and executes the file viewing example program.

When the application is started, a primary top-level shell is created. From the primary top-level shell, you can create secondary shells.

Each top-level shell is a parent of a Main Window, the work area of which is a PanedWindow.

The menu bar has the following entries:

• File---opening and closing files, creating new shells, and exiting
• View---controlling the panes in the pane window

File Menu

The file menu contains the following options:

• Open New File
  A file selection box is mapped to choose the file. If OpenFile is successful, the current file is closed, all existing panes are destroyed, and the new file is displayed.
• Open New Shell
  Creates a secondary shell similar to the primary shell. Files can be viewed in each shell independently.
• Close
  This entry only exists on the secondary windows. It destroys the top-level shell and closes the file.
• Exit
  This entry only exists on the primary shell; it closes the file and the shell.

View Menu

The view menu contains the following options:

• New Pane
  Creates a new pane in the paned window.
• Delete Pane
  Deletes the current pane.
• Search
  Causes a dialog box to pop up for searching text in the file. The OK callback of the dialog box searches the string. If the string is found, it is displayed in the current pane. If the string is not found, then the dialog box pops up.

Opening a second file in a window causes the application to end abruptly. The View options do not work correctly.

3.17.12 Xmpiano Example Program

V1.2

The xmpiano program shows how to write a Motif Interface to Dumb Instruments (MIDI) application. Both a staff, for writing music, and keyboard are provided.

At the bottom of the window is a set of notes that may be used on the staff. Selecting one of these note buttons changes the active note accordingly. The selected note is also displayed as the new mouse cursor.

Though the note selection is limited, it is possible to play sharps as well as naturals. The program interface has not been written to play flats. The staff automatically resizes larger as notes are added past the right side of the staff. To see these notes, scroll the score window as needed.

To use this application, press the right mouse button on a staff that is visible. The following menu items are displayed:

• Add Voice
  Connects another display to a new staff. After selecting this command, you are prompted for the display to connect. Any music written in the new staff plays to this display. Note that pressing the right mouse button on the new staff shows the name of the display in the menu title. In addition, the menu commands in the menu bar relate to the staff that is being displayed.
• Remove Voice
  Removes the staff as well as the connection to the corresponding display. There is no undo for this command---all music written in this staff is deleted.
• Clear Voice
  Erases all notes on the staff. This does not affect the display connection.
• Play Voice
  Plays the voice of the staff in which the right mouse was pressed. If the voice is the same as the local host, the keys on the keyboard that correspond to the notes appear as though they are being pressed as the notes are played. It is possible to make the keyboard play along with all voices at the same time; however, the code must be compiled with the -DCHORDS option. Note that this can slow down the application significantly on many servers.
• Play All
  Plays all voices at the same time on each of the specified displays.
• Save Voice
  Saves the corresponding voice to a file. A FileSelectionDialog is displayed to prompt for the name of the file in which to save the voice. The display connection information is not saved.
• Load Voice
  Loads (appends) a previously saved voice to the corresponding staff.
• Quit
  Exits the example program.

This version does not allow editing of notes. To edit, clear the staff and start again, or read the data from a saved file.

To set the color of the notes, change the foreground color of the application. To do this, use the -fg option on the command line. For example:

$ xmpiano :== $DECW$EXAMPLES:xmpiano $ xmpiano -fg blue

3.17.13 Motif Sample Programs

V1.2

Table 3-10 lists sample programs showing various Motif Toolkit functionality.

Table 3-10 Motif Sample Programs

File Name	Description
xmdialogs.c	dialog sampler
xmfonts.c	font browser
xmeditor.c	text editor
xmlist.c	list example
xmprotocol.c	window manager protocols example
xmter.c	shape & animation example
xmform.c	form attachment example
xmforc.c	form attachment + rowcolumn example
xmmap.c	drawingarea + scrolledwindow example
xmgetres.c	resource fetching example
xmapdef.c	app defined scrolled window example

The following notes apply to these sample programs:

1. The xmfonts program defaults to displaying the fonts whose name length are less than 10 characters. On some systems, the font path contains only long XLFD font names. It may be necessary either to set the resource XMFONTS*maxLen to a larger number (80), or to specify a numColumns resource of 1.
2. If you run the program xmter with a window manager other than Motif Window Manager, that window manager has to remove all the window decorations (for example, borders). The program xmter directs Motif Window Manager to remove the window decorations.
3. The xmform program displays a string made of Motif widgets embedded in a Form. Use the following commands:

   $ xmform :== $DECW$EXAMPLES:xmform $ xmform string

   The variable string is optional. If string is supplied, the available letters for string are F,I,M,O,T. The string of letters that you use must be in uppercase and enclosed in quotation marks. If string is omitted, xmform returns "MOTIF".

4. The xmgetres program is an example of how to use XmGetSecondaryResourceData. Use the following commands to invoke xmgetres:

   $ xmgetres :== $DECW$EXAMPLES:xmgetres $ xmgetres WidgetClass

   The variable WidgetClass is optional. If WidgetClass is omitted, it defaults to a class named "Widget". You can also use the class "All", which displays the resources for all the Xt and the Motif widgets. See the OSF/Motif Programmer's Reference manual for a list of available widget classes.

V1.2

The xmtravel example is a front end to a travel agent client and flight database. The program is designed to illustrate various user-interface design concepts as well as be compliant with the OSF/Motif Style Guide.

The program is just an example, many of the functions are either not implemented or use predefined settings.

3.17.15 Resource Files for Example Programs

V1.2

Many of the example programs have associated resource files for defining various display attributes. To use these files, either copy them from the directory DECW$EXAMPLES to your DECW$USER_DEFAULTS directory, or add their contents to your DECW$XDEFAULTS.DAT file.

The list of example programs and the resource files associated with them is as follows:

Example Program	Resource File
DECW$CDPLAYER.EXE	DECW$CDPLAYER.DAT
FILEVIEW.EXE	FILEVIEW.DAT
PERIODIC.EXE	PERIODIC.DAT
MOTIFANM.EXE	MOTIFANIM.DAT
XMAPDEF.EXE	XMDEMOS.DAT
XMDIALOGS.EXE	XMDEMOS.DAT
XMEDITOR.EXE	XMDEMOS.DAT
XMFONTS.EXE	XMDEMOS.DAT
XMFORC.EXE	XMDEMOS.DAT
XMFORM.EXE	XMDEMOS.DAT
XMGETRES.EXE	XMDEMOS.DAT
XMLIST.EXE	XMDEMOS.DAT
XMMAP.EXE	XMDEMOS.DAT
XMPROTOCOL.EXE	XMDEMOS.DAT
XMTER.EXE	XMDEMOS.DAT
XMTRAVEL.EXE	XMTRAVEL.DAT

If a resource file is not found, the example programs run, but some of the display attributes may be incorrect.

3.17.16 UID Files for Example Programs

V1.2

The UID files used by the example programs must be located in either the current directory or your DECW$USER_DEFAULTS directory. If they are not found, the application fails to start. The UID files can be copied from the DECW$EXAMPLES directory.

3.18 DECwindows Extensions to Motif

This section contains information about the extensions to the Motif Toolkit.

3.18.1 DXmCSText Input Method Support

V1.2

X11 R5 input method support is 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.

3.18.2 SVN---Horizontal Live Scrolling Not Supported

V1.0

Horizontal live scrolling is not supported in the Structured Visual Navigation (SVN) widget.

3.18.3 SVN Horizontal Separator Line

V1.1

When displaying an application that uses the SVN widget on a Sun system running OpenWindows Version 2, the horizontal separator line of the SVN widget is not always displayed due to a problem with the OpenWindows server. The problem does not exist with OpenWindows Version 3.

3.18.4 DXmFormSpaceButtonsEqually Restriction

V1.1

The convenience routine DXmFormSpaceButtonsEqually sizes and spaces all widgets or gadgets equally if they have a subclass of XmLabel or XmLabelGadget. The results are undefined if a widget or gadget is not a subclass of XmLabel or XmLabelGadget.

3.19 Display Server Extensions

This section contains information about the display server extensions.

3.19.1 X Image Extension

V1.1

Starting with DECwindows Motif Version 1.1 for OpenVMS, 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.

The XIE protocol and programming interface are being standardized within the X Consortium for R6, and programs that use XIE will probably have to be modified. You can use the Image Display Services (IDS) component of DECimage Application Services for VMS as an alternative to the XIE library interface. IDS provides a higher level model of image display and automatically uses XIE when it is available and appropriate.

XIE is documented in the DECimage Application Services for VMS X Image Extension Programmer's Reference Manual.

3.19.2 Client Side Extension Library

V1.1

Starting with DECwindows Motif Version 1.1 for OpenVMS, Xlib added a client side library that allows VMS clients to issue Shape, XInput, Multibuffer, and shared memory extension requests to servers that provide these features. (For example, the DECwindows X11 display server for OpenVMS VAX does not support the Shape extension while the DECwindows X11 display server for OpenVMS Alpha system does support Shape.) The name of this library is DECW$XEXTLIBSHR.EXE.

You must modify the linking file options for client applications that issue Shape, XInput, Multibuffer, or shared memory extension requests to link to the Xlib extensions shareable image in SYS$LIBRARY:DECW$XEXTLIBSHR.EXE. Add the following line to your linker options file:

SYS$LIBRARY:DECW$XEXTLIBSHR/SHARE

For more information on Shape, XInput, and Multibuffer extensions, see the following text files in SYS$HELP:

• DECW$SHAPE.TXT
• DECW$XINPUT.TXT
• DECW$MULTIBUFFER.TXT

V1.2

On OpenVMS Alpha systems, shared memory extension support provides the capability to share memory XImages. This is a version of the XImage interface where the actual image data is stored in a shared-memory segment. Consequently, the image does not need to be moved through the Xlib interprocess communication channel. For large images, use of this extension can result in dramatic performance increases.

Support for shared memory pixmaps is also provided. Shared memory pixmaps are two-dimensional arrays of pixels in a format specified by the X server, where the image data is stored in the shared memory segment. Through the use of shared memory pixmaps, you can change the contents of these pixmaps without using any Xlib routines.

These routines are included in the client side extension library. See Section 3.19.2 for details on linking this library.

3.19.3.1 How to Use Shared Memory Extension

Code that uses the shared memory extension must include the following header files:

# include "DECW$INCLUDE:Xlib.h" # include "DECW$INCLUDE:shm.h" # include "DECW$INCLUDE:XShm.h"

Any code that uses the shared memory extension should first check that the server provides the extension. In some cases, such as running over the network, the extension does not work.

To check if the shared memory extension is available on your system, call one of the following routines:

Status XShmQueryExtension (display) Display *display

Status XShmQueryVersion (display, major, minor, pixmaps) Display *display; int *major, *minor; Bool *pixmaps

The following table lists each argument and its description.

Argument	Description
display	The current display. If the shared memory extension is used, the return value from either function is True. Otherwise, your program operates using conventional Xlib calls.
major	Major version number of the extension implementation. Returned by XShmQueryVersion.
minor	Minor version number of the extension implementation. Returned by XShmQueryVersion.
pixmaps	True, if shared memory pixmaps.

3.19.3.2 Using Shared Memory XImages

The following sequence shows the process for creating and using shared memory XImages:

1. Create the shared memory XImage structure.
2. Create a shared memory segment to store the image data.
3. Attach the shared memory segment.
4. Inform the server about the shared memory segment.
5. Use the shared memory XImage.

The following sections explain each step in this process:

Step 1---Creating a Shared Memory XImage Structure

To create a shared memory XImage, use the XShmCreateImage routine, which has the following format:

XImage *XShmCreateImage (display, visual, depth, format, data, shminfo, width, height) Display *display; Visual *visual; unsigned int depth, width, height; int format; char *data; XShmSegmentInfo *shminfo;

Most of the arguments are the same as for XCreateImage (See the X Window System for a description of the XCreateImage routine.) Note that there are no offset, bitmap_pad, or bytes_per_line arguments. These quantities are set by the server, and your code needs to abide by them. Unless you have already allocated the shared memory segment (see step 2), you pass in NULL for the data pointer.

The argument shminfo is a pointer to a structure of type XShmSegmentInfo. Allocate one of these structures so that it has a lifetime at least as long as that of the shared memory XImage. There is no need to initialize this structure before the call to XShmCreateImage.

If successful, an XImage structure is returned, which you can use for the subsequent steps.

Step 2---Creating the Shared Memory Segment

Create the shared memory segment after the creation of the XImage because the XImage returns information that indicates how much memory to allocate.

The following example illustrates how to create the segment:

shminfo.shmid = shmget (IPC_PRIVATE, image->bytes_per_line * image->height, IPC_CREAT|0777);

This example assumes that you called your shared memory XImage structure. A return value of 0 indicates the shared memory allocation has failed. Use the bytes_per_line field, not the width you used to create the XImage, as they may be different.

Note that the shared memory ID returned by the system is stored in the shminfo structure. The server needs that ID to attach itself to the segment.

Step 3---Attaching the Shared Memory Segment

Attach the shared memory segment to your process as in the following example:

shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0);

The address returned by shmat is stored in both the XImage structure and the shminfo structure.

To finish supplying arguments in the shminfo structure, decide how you want the server to attach to the shared memory segment, and set the shminfo.readOnly field as follows:

shminfo.readOnly = False;

If you set the structure to True, the server cannot write to this segment, and XShmGetImage calls fail.

Step 4---Informing the Server About the Shared Memory Segment

Tell the server to attach to your shared memory segment as in the following example:

Status XShmAttach (display, shminfo);

If successful, a nonzero status is returned, and your XImage is ready for use.

Step 5---Using the Shared Memory XImage

To write a shared memory XImage into an X drawable, use the XShmPutImage routine. The XShmPutImage routine uses the following format:

XShmPutImage (display, d, gc, image, src_x, src_y, dest_x, dest_y, width, height, send_event) Display *display; Drawable d; GC gc; XImage *image; int src_x, src_y, dest_x, dest_y; unsigned int width, height; Bool send_event;

The interface is identical to the XPutImage routine (see the X Window System), except for one additional parameter, send_event. If this parameter is passed as True, the server generates a completion event when the image write is complete. This allows your program to know when it is safe to begin manipulating the shared memory segment again.

The completion event is of the type XShmCompletionEvent, which is defined as follows:

typedef struct { inttype; /* of event */ unsigned long serial; /* # of last request processed */ Bool send_event; /* true if came from a SendEvent request */ Display *display; /* Display the event was read from */ Drawable drawable; /* drawable of request */ int major_code; /* ShmReqCode */ int minor_code; /* X_ShmPutImage */ ShmSeg shmseg; /* the ShmSeg used in the request */ unsigned long offset; /* the offset into ShmSeg used */ } XShmCompletionEvent;

To determine the event type value that is used at run time, use the XShmGetEventBase routine as in the following example:

int CompletionType = XShmGetEventBase (display) + ShmCompletion;

To read image data into a shared memory XImage, use the XShmGetImage routine, which uses the following format:

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.