OSF/Motif Release 1.2 has the following new functions for managing representation types:

• XmRepTypeRegister
• XmRepTypeAddReverse
• XmRepTypeValidValue
• XmRepTypeGetRegistered
• XmRepTypeGetId
• XmRepTypeGetNameList
• XmRepTypeGetRecord

These functions are useful for developers who want to define new resource converters that use an enumerated set of values.

A.3.19 Changes for CUA and Windows Compliance

In OSF/Motif Release 1.2, pressing the Return key or using the key bound to osfActivate (usually the Enter key on the numeric keypad) no longer activates a button that is outside a menu. For example, pressing such a key no longer pops up an OptionMenu or activates a ToggleButton in a dialog box.

If your application has a default button associated with an XmBulletinBoard, pressing Return (except in a multiline XmText), Ctrl/Return, or the key bound to osfActivate while the focus is in the XmBulletinBoard now activates the default button.

A.4 Changes and Enhancements to Specific Widgets

This section summarizes the changes to specific widgets that were made in OSF/Motif Release 1.2.

A.4.1 XmClipboard

OSF made several corrections to the XmClipboard function parameters. These changes are binary compatible with earlier releases of Motif. However, in some instances, you might see warning messages when you recompile your applications. The modifications involved changing (char *) to XtPointer, int to long, and (int *) to (long *). The related functions affected by these modifications are:

• XmClipboardCopy
• XmClipboardCopyByName
• XmClipboardInquireCount
• XmClipboardInquireFormat
• XmClipboardRegisterFormat
• XmClipboardRetrieve
• XmClipboardStartCopy
• XmClipboardWithdrawFormat

In OSF/Motif Release 1.2, a correction was made to XmCommandGetChild so that it now accepts XmDIALOG_WORK_AREA as a value for the child argument.

A.4.3 XmList

To enhance its capabilities for managing lists, OSF/Motif Release 1.2 includes the following new functions:

• XmListAddItemsUnselected
• XmListDeletePositions
• XmListGetKbdItemPos
• XmListIsPosSelected
• XmListPosToBounds
• XmListReplaceItemsUnselected
• XmListReplaceItemsPosUnselected
• XmListReplacePositions
• XmListSetKbdItemPos
• XmListUpdateSelectedList
• XmListYToPos

The XmList widget includes a new translation:

• <Copy>
  Copies the selection to the clipboard.

XmList includes a new action:

• ListScrollCursorVertically()
  Scrolls the cursor vertically based on an input percentage or a y position.

The XmNvisibleItemCount resource has been modified so that the default value is dynamic, and is based on the item count and the height.

In OSF/Motif Release 1.2, if the selectedItems and selectedItemCount resources for a list are set in a resource file, the location cursor appears over the last item in the selectedItems list, not the first selected item.

A.4.4 XmMessageBox

In OSF/Motif Release 1.2, MessageBox supports the addition of one MenuBar, one work area, and multiple PushButton children.

A new dialog type, XmDIALOG_TEMPLATE, creates a MessageBox that contains only a Separator. The application provides additional children.

XmCreateTemplateDialog creates an XmDIALOG_TEMPLATE XmMessageBox inside a DialogShell.

A.4.5 XmRowColumn and Menus

OSF/Motif Release 1.2 adds a new resource, XmNentryVerticalAlignment, that specifies the vertical alignment style.

Another resource, XmNunpostBehavior has been added to the XmScreen object. This resource can be set to enable external button events to be replayed after a menu is unposted.

A.4.6 XmScrollBar

In OSF/Motif Release 1.2, XmScrollBar includes a new translation:

• <Cancel>
  Cancels the current slider drag.

OSF/Motif Release 1.2 adds the function, XmScrollVisible, that scrolls an automatic scrolled window to make a partially or completely obscured widget visible.

Another resource, XmNtraverseObscuredCallback, has been added that specifies a list of callbacks that are called when a traversal event is requested to a nonvisible widget. A new callback structure, XmTraverseObscuredCallbackStruct, has been added to support this callback.

A.4.8 XmSelectionBox, XmFileSelectionBox

In OSF/Motif Release 1.2, the XmSelectionBox and XmFileSelectionBox widgets support the addition of MenuBar and PushButton children, as well as a work area child.

A new resource, XmNchildPlacement, controls the location of the work area child.

The value, XmDIALOG_TEMPLATE, has been added to the XmNdialogType resource.

By default, XmSelectionBoxDialog and its subclasses use XmTextField instead of XmText. You can revert to the earlier behavior by defining USE_TEXT_IN_DIALOGS when your application builds XmSelectionBox or any of its subclasses.

A.4.9 XmText

OSF/Motif Release 1.2 has added two functions to XmText for making update changes to the widget: XmTextDisableRedisplay and XmTextEnableRedisplay.

Two other functions facilitate string manipulation: XmTextFindString and XmTextGetSubstring.

In Release 1.2, the destination cursor now follows the insert cursor and is no longer independently drawn.

XmText includes three new translations:

• <Backspace>
  Deletes any non-null primary selection.
• <Delete>
  Deletes any non-null primary selection.
• <LeaveWindow>
  Continues a selection action by scrolling after a time delay.

XmText includes two new actions:

• scroll-cursor-vertically()
  Scrolls the cursor vertically based on a y position.
• toggle-overstrike()
  Switches between insert and overstrike modes.

OSF/Motif Release 1.2, the XmTextField widget has a new resource, XmNfocusCallback, that specifies the callbacks to be called when the widget accepts input focus.

Another new function, XmTextFieldGetSubstring, gets a substring by length from a widget.

In Release 1.2, the destination cursor now follows the insert cursor and is no longer independently drawn.

XmTextField includes two new translations:

• <Backspace>
  Deletes any non-null primary selection.
• <Delete>
  Deletes any non-null primary selection.

In OSF/Motif Release 1.2, setting XmNfillOnSelect to be true when XmNindicatorOn is false now causes the background of a set XmToggleButton to be filled with XmNselectColor.

The default value for XmNfillOnSelect is dynamic so that it matches the state of XmNindicatorOn.

A.5 Motif Window Manager Enhancements

This section highlights the enhancements to the Motif Window Manager (MWM).

A.5.1 Changes to MWM

OSF/Motif Release 1.2 incorporates the following enhancements to MWM:

• An internationalized .mwmrc file
• Internationalized dialog messages
• A built-in default root menu
• Support for the <Return> continuation character (\) in the .mwmrc file
• Search capability with XBMLANGPATH for bitmap files
• Support for pop-down and replay event behavior in mwm menus
• Documentation of the widget names used by mwm
• Support for scrolled window traversal to scrolled-off children in the icon box
• Support for treating the <Alt> and <Meta> key modifiers as two distinct modifiers
• Support for the SHAPE nonrectangular window extension

The OSF/Motif Release 1.2 window manager includes the following new or enhanced resources:

• feedbackGeometry
  Sets the position of the move/resize feedback window. The default position is the center of the screen.
• frameBorderWidth
  Now bases its default value on the size and resolution of the screen.
• iconPlacement
  Now takes the addition value, tight, which specifies automatic icon placement with no gaps between icons.
• maximumClientSize
  Can now take the values vertical and horizontal.
• moveOpaque
  Controls whether an image of the window or just an outline of the window is moved.
• resizeBorderWidth
  Now bases its default value on the size and resolution of the screen.
• usePPosition
  Uses the values of on, off, or nonzero to control whether program-specified positions are used.

OSF/Motif Release 1.2 has the following new and enhanced MWM functions:

• f.lower
  Includes a within argument to move the window within the application stacking order, but retains the parent window below the children rule. The function also includes a freeFamily argument to move the window absolutely without regard to its local family stack. Both modifiers move the window within the local family stack, but do not move the family stack.
• f.minimize
  Can now be used from an icon in an icon box.
• f.raise
  Includes a within argument to move the window within the application stacking order, but retains the parent window below the children rule. The function also includes a freeFamily argument to move the window absolutely without regard to its local family stack. Both modifiers move the window within the local family stack, but do not move the family stack.
• f.raise_lower
  Includes a within argument to move the window within the application stacking order, but retains the parent window below the children rule. The function also includes a freeFamily argument to move the window absolutely without regard to its local family stack. Both modifiers move the window within the local family stack, but do not move the family stack.
• f.restore
  Restores a window to its previous state. Double clicking on a root icon is bound to this function rather than to f.normalize.
• f.restore_and_raise
  Restores a window to its previous state and raises it to the top of the window stack. Double clicking on an icon in an icon box is bound to this function rather than to f.normalize.
• f.screen
  Traverses to the screen specified by arg. Legal values for arg are: next, prev, last, or a specific screen number.

OSF/Motif Release 1.2 has one new MWM action:

• <Alt> <Esc>
  This key combination behaves similarly to f.next_key, except that the window is always raised, regardless of the value of focusAutoRaise.

OSF/Motif Release 1.2 has the following changes in the User Interface Language (UIL):

• There is a new command flag, -s, that enables the use of setlocale and the creation of localized Compound Strings.

  Note There is a serious problem in parsing double quoted strings with the -s flag. If you need to use this flag for parsing double quoted strings, you must obtain a patch from the OSF.

• New UIL syntax now supports font sets and font tables.
• New UIL syntax now supports wide character strings.
• Support has been added for using widget references as callback tags.
• New UIL syntax specifies the resources of automatically created children.
• Syntax changes to the Widget Meta-Language (WML) allow for the definition of automatically created children of composite widgets.
• UIL can now use the -wmd file flag to read binary databases (WML files) that contain WML information.
• Mrm includes two new functions:
  • MrmOpenHierarchyPerDisplay
    This function is the same as the old MrmOpenHierarchy function, except that in the new function, the display is passed as an explicit argument. This function replaces MrmOpenHierarchy.
  • MrmFetchBitmapLiteral
    This function fetches a bitmap literal with a depth of 1.

This appendix contains information about notes, restrictions, and corrections related to the OSF/Motif and DECwindows OSF/Motif Toolkits.

B.1 OSF/Motif Release 1.2.2 and X11 Release 5 Shareable Libraries

V1.2

Because the OSF/Motif Release 1.2.2 Toolkit and the OSF/Motif Release 1.1.3 Toolkit are not binary compatible, applications must link with one toolkit or the other. Applications based on OSF/Motif Release 1.2.2 can only link against OSF/Motif 1.2.2-based and X11 R5-based shareable libraries. Applications based on OSF/Motif Release 1.1.3 can only link against OSF/Motif 1.1.3-based and X11 R4-based shareable libraries.

To provide both OSF/Motif Release 1.2.2-based and OSF/Motif Release 1.1.3-based shareable libraries, the Release 1.1.3-based libraries have the same file names as in DECwindows Motif Version 1.1, and the Release 1.2.2-based libraries contain a suffix of either "R5" or "12".

Shareable libraries that work with either the OSF/Motif Release 1.1.3 Toolkit or the OSF/Motif Release 1.2.2 Toolkit do not have a suffix. These libraries are as follows:

V1.2--6

• CDA$ACCESS.EXE
• DECW$D2DXLIBSHR.EXE
• DECW$XEXTLIBSHR.EXE
• DECW$XLIBSHR.EXE
• XIE$SHRLIB.EXE

Shareable libraries that are linked with Release 5 (R5) of the Xt Toolkit have a suffix of "R5". Libraries based on the XUI Toolkit have no R5 equivalent libraries and should not be included in a linker options file based on X11 R5 or OSF/Motif Release 1.2.2. Table B-1 lists these file names.

Table B-1 Names of Shareable Libraries Based on R5

Names of Files Based on R4	Names of Files Based on R5
DECW$DWTLIBSHR.EXE	(None)
DECW$DWTSHR.EXE	(None)
DECW$XMULIBSHR.EXE	DECW$XMULIBSHRR5.EXE
DECW$XTRAPLIBSHR.EXE	DECW$XTRAPLIBSHRR5.EXE
DECW$XTSHR.EXE	DECW$XTLIBSHRR5.EXE

Release 5 does not provide an equivalent file for DECW$DWTLIBSHR.EXE or DECW$DWTSHR.EXE. Applications that are built for Release 5 cannot link against these files.

Shareable libraries that are linked with OSF/Motif Release 1.2.2 have a suffix of "12". They should be linked only with libraries compatible with R5 and OSF/Motif Release 1.2.2. Table B-2 lists these file names.

Table B-2 Names of Shareable Libraries Based on OSF/Motif Release 1.2.2

Names of Files Based on Release 1.1.3	Names of Files Based on Release 1.2.2
DDIF$VIEWSHR.EXE	DDIF$VIEWSHR12.EXE
DECW$BKRSHR.EXE	DECW$BKRSHR12.EXE
DECW$DXMLIBSHR.EXE	DECW$DXMLIBSHR12.EXE
DECW$MAILSHR.EXE	DECW$MAILSHR12.EXE
(None)	DECW$MRMLIBSHR12.EXE
DECW$PRINTWGTSHR.EXE	(None)
DECW$TERMINALSHR.EXE	DECW$TERMINALSHR12.EXE
DECW$XMLIBSHR.EXE	DECW$XMLIBSHR12.EXE
DGIT$LIBSHR.EXE	DGIT$LIBSHR12.EXE
IMG$SHRLIB.EXE	IMG$SHRLIB12.EXE
LWK$DXMSHR.EXE	LWK$DXMSHR12.EXE
XNL$SHR.EXE	XNL$SHR12.EXE

There is no DECW$PRINTWGTSHR12.EXE file; the Print Widget is part of the DECW$DXMLIBSHR12.EXE file.

The DECW$MRMLIBSHR12.EXE file is a new image that includes Motif Resource Manager (Mrm) routines that were formerly part of the DECW$XMLIBSHR.EXE file. Any program based on OSF/Motif Release 1.2.2 that calls Mrm routines to access .UID files should link with this library.

For example, a typical linker options file for a program based on OSF/Motif Release 1.1.3 might be as follows:

SYS$SHARE:DECW$XLIBSHR/SHARE SYS$SHARE:DECW$XTSHR/SHARE SYS$SHARE:DECW$DWTLIBSHR/SHARE SYS$SHARE:DECW$XMLIBSHR/SHARE SYS$SHARE:DECW$DXMLIBSHR/SHARE

To link this program with OSF/Motif Release 1.2.2, the linker options file should be changed to:

SYS$SHARE:DECW$XLIBSHR/SHARE SYS$SHARE:DECW$XTLIBSHRR5/SHARE SYS$SHARE:DECW$XMLIBSHR12/SHARE SYS$SHARE:DECW$MRMLIBSHR12/SHARE SYS$SHARE:DECW$DXMLIBSHR12/SHARE

These changes eliminate the reference to the XUI Toolkit (DECW$DWTLIBSHR.EXE) and links with the Motif Resource Manager (DECW$MRMLIBSHR12.EXE).

B.2 OSF/Motif Release 1.1.3 Programming Support and XUI

V1.2--3

Restrictions

• Problem:
  You will encounter problems if you save the previous (Release 1.1.3) programming environment and attempt to run an OSF/Motif Release 1.1.3 (Xlib Release 4) program that is created on a DECwindows Motif Version 1.2 or Version 1.2--3 system by running the executable on a DECwindows Motif Version 1.1 target system. That is, if you build an application on a DECwindows Motif Version 1.2 or Version 1.2--3 for OpenVMS system, the image is linked with Xlib Release 5, by default. If you attempt to run that executable on a system where OSF/Motif Release 1.1.3 is installed, the result is an ident mismatch fatal error.
  In addition, the OSF/Motif Release 1.1.3 and the Release 1.2.2 files produce different output; they have different structures and are therefore not compatible. Use the appropriate UIL compiler to produce the correct UID file.
• Resolution:
  1. Rename the DECwindows Motif Version Version 1.1 executable compiler, DECW$UILMOTIF.EXE, to DECW$UILMOTIF113.EXE and keep the file in the SYS$COMMON directory. By doing this, the name of the new Version 1.2--3 compiler, DECW$UILMOTIF.EXE, does not conflict with the previous compiler.
  2. Copy the DECW$XLIBSHR.EXE file (Xlib Release 4) to the SYS$COMMON:[SYSEXE.DECW$113] directory.
     The Xlib Release 5 version of Xlib has the same name; however, a logical name is defined to use the Release 4 version when the programs are linked. The changes in minor ident of DECW$XLIBSHR.EXE between DECwindows Motif Version 1.1 and DECwindows Motif Version 1.2 for OpenVMS caused a loss of backward compatibility with DECwindows Motif Version 1.1 systems.

  3. If you save the previous programming environment during installation, create the following two files and copy them to the SYS$COMMON:[SYSEXE.DECW$113] directory:
     • DECW$UILCOMPILER113.CLD
       This file enables UIL/OSF Motif and UIL/XUI to function for either XUI or OSF/Motif Release 1.1.3 if you select DECW$UILMOTIF113.EXE for OSF/Motif Release 1.1.3 or DECW$UILCOMPILER.EXE for XUI.
     • DECW$DEFINE113_LOGICALS.COM
       This file points to the saved header files, which in turn point to the Xlib Release 4 version of the DECW$XLIBSHR.EXE file.
  4. An application must be run on the same version (or higher) of the operating system as the version where it is linked. For example, an application that is linked on a VMS Version 5.4--3 system must be run on a VMS Version 5.4--3 (or higher) system.
     DECwindows Motif Version 1.1 applications that are compiled for OpenVMS Version 6.1 systems will run only on OpenVMS Version 6.1 systems and not on systems prior to Version 6.1.

V1.2

The X Window and OSF/Motif libraries that are shipped with DECwindows Motif Version 1.2 for OpenVMS software are incompatible with those shipped with previous versions. Run-time compatibility has been preserved, but the programming environment is not compatible.

Programming in the XUI or Motif Release 1.1.3 environment that is provided in previous versions of DECwindows Motif is no longer supported in DECwindows Motif Version 1.2 for OpenVMS. However, the installation procedure gives you the option of saving the programming files that already exist on your system. If you choose to save these programming files, they are moved to subdirectories where you can access them for programming. Specifically, the installation creates a subdirectory called [.DECW$113] in each of the directories listed in Table B-3 and moves the previous files into the new subdirectory.

For more information about saving the programming files, see the DECwindows Motif Version 1.2 for OpenVMS Installation Guide.

Table B-3 Directories for Previous XUI or Motif Programming Environment

Directory	Contents	New Location
DECW$INCLUDE	C header files	SYS$SYSROOT:[DECW$INCLUDE.DECW$113]
SYS$SYSTEM	UIL compiler	SYS$SYSROOT:[SYSEXE.DECW$113]
SYS$LIBRARY	Non-C language bindings	SYS$SYSROOT:[SYSLIB.DECW$113]

To program with these files, include the new [.DECW$113] subdirectories in the search path for each of the logical names. For example, perform the following:

• Change the definition of DECW$INCLUDE as follows:

  $ SHOW LOGICAL DECW$INCLUDE "DECW$INCLUDE" = "SYS$SYSROOT:[DECW$INCLUDE]" (DECW$LOGICAL_NAMES) = "SYS$SYSROOT:[DECW$INCLUDE.EXTENSIONS]" $ DEFINE/EXECUTIVE/TABLE=DECW$LOGICAL_NAMES DECW$INCLUDE - SYS$SYSROOT:[DECW$INCLUDE.DECW$113], - SYS$SYSROOT:[DECW$INCLUDE], - SYS$SYSROOT:[DECW$INCLUDE.EXTENSIONS]

Place the new [.DECW$113] subdirectory first in the search list, since many of the files that have been updated for this release have the same name as the files that were moved to the [.DECW$113] subdirectory. Thus, the files in [.DECW$113] are used for software development.

If DECW$INCLUDE is redefined in the SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM command procedure, then modify the previous instructions accordingly.

To use the UIL compiler for XUI or OSF/Motif Release 1.1.3, perform the following steps:

1. Create a file called
   SYS$SYSROOT:[SYSEXE.DECW$113]DECW$UILCOMPILER.CLD that contains the following text:

   define type trace_keywords keyword tokens keyword symbols define type warning_keywords keyword nowarnings keyword noinformationals define type version_keywords keyword V1, syntax=xui_uil keyword V2, syntax=xui_uil, default keyword MOTIF11, syntax=motif_uil define syntax xui_uil image decw$uilcompiler define syntax motif_uil image decw$uilmotif define verb uil image decw$uilcompiler parameter p1, label=source_file, prompt="File", value(required,noconcatenate,type=$infile) qualifier trace, label=trace_qual, value(list,noconcatenate,type=trace_keywords), nonnegatable qualifier warnings, label=warnings_qual, value(list,noconcatenate,type=warning_keywords) qualifier list, label=listing_file, batch, value(type=$outfile) qualifier machine, label=machine_qual, qualifier output, label=resource_file, default, value(type=$outfile) qualifier version, label=version_qual, default, value(type=version_keywords), nonnegatable qualifier XUI, default, nonnegatable, syntax=xui_uil qualifier MOTIF, nonnegatable, syntax=motif_uil qualifier widget_meta_description, label=widget_qual, value(required, noconcatenate, type=$infile) disallow XUI and MOTIF

2. Set the DCL command table to use the XUI UIL compiler as follows:

   $ SET COMMAND SYS$SYSROOT:[SYSEXE.DECW$113]DECW$UILCOMPILER.CLD