This section contains information about DECterm programming.

3.15.1 Page-Movement Escape Sequences

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.

V1.2

DECterm supports the DECCRA (Copy Rectangular Area) sequence in a limited way. The entire page needs to be copied at once, and either the source or the destination page must be the current page (for example, you cannot copy from one off-screen page to another).

3.15.3 DECLFKC Sequence

V1.2

Since DECterm does not have a user interface to redefine the F5 (Break) key, the DECLFKC (Local Function Key Control) sequence redefines the F5 key when "0" (all keys) is used to select which key is to be modified.

3.15.4 ReGIS Input Cursors

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 3-7 shows the values of n.

Table 3-7 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

This section contains information about notes, restrictions, and corrections for the DECwindows OSF/Motif Toolkit.

3.16.1 Motif Text Widget Translations

V1.0

To implement virtual bindings, it is necessary for Compaq to modify the default XmText and XmTextField translation manager syntax. Specifically, the following syntax line is removed:

Shift ~Ctrl ~Meta ~Alt <Key>osfDelete: cut-clipboard()

If you use virtual bindings in which the osfCut virtual keysym is not bound, no key sequence is bound to the cut-clipboard action by default. To work around this limitation, override the XmText and XmTextField translations in your DECW$XDEFAULTS.DAT file.

3.16.2 Upward Compatibility

V1.0

The combination of DECW$DWTLIBSHR, DECW$DWTSHR, and DECW$XTSHR shareable images is intended to be binary and upwardly compatible with the previous DECW$DWTLIBSHR shareable image. A possible exception is applications that dynamically activate the image DECW$DWTLIBSHR using LIB$FIND_IMAGE_SYMBOL. The problem with dynamic image activation is that the semantics of the Intrinsics have changed in places between the X Toolkit Intrinsics Release 3 to the MIT X11 Release 4 Intrinsics. A previously linked XUI application calls through entries in the XUI transfer vector that use the X Toolkit Intrinsics Release 3 semantics of the Intrinsics. However, as soon as that application relinks (or dynamically activates DECW$DWTLIBSHR), it uses the MIT X Toolkit Intrinsics Release 4 semantics of the Intrinsics.

Applications that dynamically activate DECW$DWTLIBSHR should be changed to link directly against DECW$DWTLIBSHR. DECW$DWTLIBSHR is now a small, thin-layer, shareable image that dynamically activates automatically the majority of the toolkit code only when necessary. There is no reason for applications to continue to dynamically activate DECW$DWTLIBSHR.

In addition, Compaq cannot guarantee binary upward compatibility in the future for applications that dynamically activate the toolkit shareable images. DECwindows toolkits (XUI and Motif) are based upon standards that Compaq does not control. When the standards make an incompatible change, Compaq will change the toolkit to follow it. However, the intent is to add code that allows existing executable images to run unchanged.

3.16.2.1 Restrictions on Mixing Motif and XUI Widgets

V1.0

Mixing Motif and XUI widgets is restricted. The problem results from the fact that both XUI and Motif have their own Vendor Shell widget class. If an application is linked against XUI and not Motif, the XUI Vendor Shell widget class is used in order to maintain compatibility with DECwindows XUI. If an application is linked against Motif, the Motif Vendor Shell widget class is used. Motif widgets require the Motif Vendor Shell; XUI widgets are compatible with the Motif Vendor Shell. The problem occurs when an XUI-only application dynamically activates (using LIB$FIND_IMAGE_SYMBOL) a shareable image that uses Motif. The toolkit makes the decision to use the XUI Vendor Shell when the toolkit is initialized and the Motif widgets in the dynamically activated shareable image do not work.

The workaround is to add the application image name to the DECW$USE_XM_VENDOR_SHELL logical name. This logical name contains a comma-separated list of image names for which the toolkit is to use the Motif Vendor Shell. The value of DECW$USE_XM_VENDOR_SHELL logical name defaults to NOTES$MAIN. To add additional image names to this logical name, enter the following:

$ DEFINE DECW$USE_XM_VENDOR_SHELL "NOTES$MAIN,- _$ yourimage1,yourimage2,..."

Note that DECW$USE_XM_VENDOR_SHELL does not affect applications that use Motif since they are already using the Motif Vendor Shell.

3.16.3 Compile-Time Incompatibilities in Motif Header Files

V1.2--3

Several macro definitions are removed from the Motif header files in the OSF/Motif programming support. The changes affect the following header files:

• DECW$INCLUDE:XMP.H
  The following definitions are removed:
  • #define XmLONGBITS sizeof(Cardinal)*8
  • #define XmHALFLONGBITS (XmLONGBITS/2)
  
  These macros are replaced in the same header file with the following macro:
  • XmOFFSETBITS
  
  Update the code to call the XmOFFSETBITS macro.
• DECW$INCLUDE:TEXTP.H
  The following definitions are removed:
  • #define MAXINT 2147483647
    /* Biggest number that can fit in long */
  • #define NODELTA MAXINT
  
  The definition of MAXINT is operating-system dependent. Include this definition in applications in one of the following ways:
  • Include the appropriate system-header file
  • Define the constant

This section describes example programs from the Open Softare Foundation (OSF) that are included in the DECwindows Motif Version 1.2 for OpenVMS software.

3.17.1 Cut and Paste Example Program

V1.2

This example demonstrates the use of the Motif Clipboard. You can cut and paste application-defined data formats using the XmClipboard API.

Run two cut/paste clients and transfer graph values using the pull-down and pop-up menus.

3.17.2 DNDDemo Example Program

V1.2

This example illustrates a typical use of the drag-and-drop feature.

When the example starts, it does not have any valid drop sites. It starts with different color rectangles that act as drag sources for dragging the colors around. Create the drop sites as follows:

• Move the pointer into the drawing area (with white background).
• Press MB1 and drag. You see the "rubber-banding" effect.
• Release MB1 after dragging a desired distance.
  A black rectangle appears. You can create as many rectangles as you like.

The rectangles inside the drawing area that you created act as valid drop sites for colors. You can test this by initiating the drag from the yellow color rectangle and dragging over to one of the rectangles inside the drawing area and releasing MB2.

To initiate a drag, move the pointer over to the drag source, press BTransfer (which is MB2 by default), and start to drag. Notice that the cursor changes to a painter's palette in the same color as the color rectangle from which the drag is initiated.

While you are dragging, notice the following:

• When dragging over the root window, the drag icon consists of only the painter's palette.
• When dragging over parts of the drawing area where there are no rectangles, the drag icon changes to include a "DO NOT ENTER!" sign on top of the painter's palette.
• When dragging over any of the rectangles inside the drawing area, the "DO NOT ENTER!" sign is replaced with a painter's brush.

To perform a drop, release MB2. If you release MB2 with the pointer over any part of the drawing area outside of the rectangles, or anywhere on the root window, the drag icon snaps back to the point of drag initiation and disappears. This is an indication that the drop you attempted failed. If you release MB2 with the pointer over any of the rectangles inside the drawing area, the drag icon disappears into the background; this indicates that the drop was a success. The rectangle on which the drop was attempted, becomes filled in with the color that was dragged.

The rectangles inside the drawing area act as drag sources. Initiate the drag with the pointer on any rectangle, and the cursor changes to a rectangle (either of the same size or a smaller size depending on the X cursor size constraints). Drag the rectangle from one place and drop it onto a new place inside the drawing area. The rectangle is physically moved to the new position.

If you want to copy the rectangle to a new position, use the appropriate modifier key while dragging, or at the time you attempt the drop (Ctrl is the modifier key for copy in the current implementation). When you drag a rectangle with no modifier key pressed or with the Shift key pressed, the solid rectangle from where the drag was initiated is replaced by a hollow rectangle with dotted-line borders. It continues this way for the duration of the drag or until you press the Ctrl key, which changes the operation to Copy. At that time it regains its original solid form.

V1.1

This example uses the dog and square widgets. It shows how to incorporate new widgets into the UIL source by using the user-defined function.

The dogs example program allows you to change the DogNwagTime and SquareNmakeSquare resources dynamically.

If you have a system with sound generation features, you might want to change the bark callback to something other than XBell().

3.17.3.1 Dog Widget

V1.1

The dog widget (DogWidget) demonstrates how to subclassify a primitive widget that remains binary compatible with future versions of Motif. It uses XmResolvePartOffsets() and associated macros and implements all the recommendations in the XmResolvePartOffsets manpage.

The dog widget is a subclass of XmPrimitive. It can bark and wag its tail. If you want more advanced tricks, you must subclassify it, or replace up.bm, down.bm, and bark.bm with more advanced bitmaps.

The dog widget has the following resources:

• DogNwagTime: Time in milliseconds between each wag
• DogNbarkTime: Time in milliseconds the bark graphic is displayed
• DogNbarkCallback: Callback called by the bark action

The dog widget has the following translations:

• osfActivate/Return/Space/MB1 = Bark
• W/MB2 = Wag tail
• S/Shift-MB2 = Stop wagging tail
• osfHelp = Help

V1.1

The square widget (SquareWidget) demonstrates how to subclassify a constraint widget that remains binary compatible with future versions of Motif. It uses XmResolveAllPartOffsets() and associated macros and implements all the recommendations in the XmResolveAllPartOffsets manpage.

The square Widget is a subclass of XmBulletinBoard. It forces its children to be square using a constraint resource.

The square widget has the resource SquareNmajorDimension. This resource determines which dimension is used for the new size of the child. Values are SquareWIDTH or SquareHEIGHT.

The square widget has the constraint resource SquareNmakeSquare. This resource determines whether the child is forced to be square or set to its preferred shape.

3.17.4 Helloint Example Program

V1.2

This example is a simple UIL/Xm program with a label and a push button.

With this version, you can choose a Kanji, Hebrew, French, or English interface at run time.

The program uses the file LOCALSTRINGS.UID for all language-specific interfaces. To change languages, copy one of the LOCALSTRINGS_*.UID files to DECW$USER_DEFAULTS:LOCALSTRINGS.UID. Then, use the logical name LANG or the xnlLanguage resource to set the locale. Set the LOCALSTRINGS suffix and the locale name to one of the following:

Locale	Interface Type
Japan	Kanji
Hebrew	Hebrew
French	French
English	Standard English

To define the xnlLanguage resource, add the following line to your DECW$XDEFAULTS.DAT file:

*xnlLanguage:locale

The following fonts are needed for the helloint example program:

Locale	Font Name
French	-adobe-helvetica-medium-r-normal--12-120-75-75-p-67-iso8859-1
English	-adobe-times-medium-r-normal--14-100-100-100-p-74-iso8859-1
Hebrew	-Misc-Fixed-Medium-R-Normal--13-120-75-75-C-80-ISO8859-8
Japan	-*-JISX0208.1983-1
	-*-JISX0201.1976-0

If you do not have these fonts installed on your system, either change the UIL files to reference other fonts or install the *.DECW$BDF fonts provided in the DECW$EXAMPLES directory. See Managing DECwindows Motif for OpenVMS Systems for instructions on how to install new fonts.

3.17.5 Hellomotif Example Program

V1.2

This example is a simple UIL/Xm program with a label and a push button.

3.17.6 Motifanim Example Program

V1.1

The motifanim program demonstrates the following OSF/Motif features:

• Declaration of icon/bitmap using UIL for portability across visuals
• Exchange of value between UIL and C using Mrm
• Use of the Motif form widget
• Background procedure running while the client process is waiting for input (Xt intrinsics feature)

This example lets you animate a set of pixmaps in an X window. The pixmaps are not fixed by motifanim but are read at startup from existing UID files.

The syntax of all the animation.uid files can add a new set of pixmaps to be animated using motifanim. Some tree examples of animation data files include:

• dog.uil
• plane.uil

The default animation is dog. To run the example with the other animations, use the following commands:

$ SET DEFAULT DECW$EXAMPLES $ motifanim := "$DECW$EXAMPLES:motifanim" $ motifanim -anim plane

The files motiflogo.uil, motifanim.uil, and motifanim.c are the core components of the program.

3.17.7 Motifgif and Pict Viewing Programs

V1.2

The following .gif files are provided:

• TOUCAN.GIF, which is a picture of a tropical bird.
• CHALLENGER.GIF, which is a picture of the space shuttle Challenger.

V1.1

The motifgif and pict programs work together to display a .gif formatted picture. The motifgif program displays a .gif file within Motif constructs. The motifgif program looks for .gif files in the current directory.

The motifgif program has three significant components:

• motifgif The source and executable code in this directory is a Motif program driving the display of a .gif picture.
• pict The program called by motifgif that displays a bitmap of a .gif picture file. This program used to be xgif but has since been converted to Motif.

The following problems exist with motifgif:

• Resizing a picture does not work.
• The -d option is not used when calling pict, so remote displays must set the DISPLAY environment variable.

V1.2

The motifshell program is an example of an environment created using Motif. The purpose of the example is to show how Motif may be used as a standalone environment for dispatching other programs and utilities.

The motifshell program is written in C code. There are no UIL references.

V1.2

The periodic example is a demonstration of the displayable widgets in Motif. The program displays Motif widgets in a periodic chart format.

3.17.10 Textedit Example Program

V1.2

The textedit program is a primitive text editor based on the Motif XmText widget that makes use of its XmNsource resource to allow multiple views of the same underlying text.

Table 3-8 describes the View menu options.

Table 3-8 View Menu Options

Option	Description
Split Pane	Adds a new independently scrollable view of the text.
Remove Pane	Removes a designated pane.
One Pane	Removes all panes except the designated pane.

The designated pane is determined in the following way:

• If using an explicit focus policy, it is the last view which had focus.
• If using a pointer focus policy, it is the last view with which the user interacted.

The designated pane is also the one whose clipboard contents are pasted when Paste is selected from the Edit Menu.

The textedit sources are separated into independent layers. Textedit contains the source files listed in Table 3-9.

Table 3-9 Textedit Source Files

File Name	Description
tfile.c	The code to read, write, and remove files. Hides any operating system or filesystem dependencies.
app.c	Uses tfile.c to provide all the code to manipulate files and their related buffers. This is toolkit-dependent.
tk.c	Isolates dependencies on the Xm Toolkit. The first half of the file provides utility routines and a toolkit-independent (but application-specific) interface that can be used by the toolkit-independent dialog layer of the application. The second half of the file defines all the callback routines. Many of these update state internal to this layer; others perform additional actions. Those actions unambiguously correspond to toolkit-specific action routines defined in the first half of the file. Otherwise, an upcall is made to the toolkit-independent dialog layer to decide what to do.
dlg.c	Uses tk.c to manage dialog with the user. The code is toolkit-independent.
textedit.c	Initializes the application and instantiates widget hierarchies. The code hides the use of UIL and Mrm from the rest of the application.