HP OpenVMS Systems Documentation

Porting XUI Applications to Motif

This guide describes how to convert XUI applications to OSF/Motif applications.

Revision/Update Information: This is a new manual.

Operating System and Version: ULTRIX Version 4.2
VMS Version 5.4

Software Version: ULTRIX Worksystem Software
Version 4.2
VMS DECwindows Motif Version 1.0

Digital Equipment Corporation
Maynard, Massachusetts

The information in this document is subject to change without notice and should not be construed as a commitment by Compaq Computer Corporation. Compaq Computer Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Compaq Computer Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

Copyright ©1991

The following are trademarks of Compaq Computer Corporation: Bookreader, CDA, DEC, DECnet, DECwindows, DECwrite, Digital, LinkWorks, LiveLink, LN03, PrintServer, ReGIS, ULTRIX, ULTRIX Worksystem Software, VAX, VAXcluster, VAXserver, VAXstation, VMS, VT, XUI, and the DIGITAL logo.

Open Software Foundation, OSF, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc.

UNIX is a registered trademark of UNIX System Laboratories, Inc.

ZK5640

This document was prepared using DECdocument, Version V3.3-1e.

This guide is intended for application and widget programmers who want to port their XUI applications and custom widgets to OSF/Motif Version 1.1. Programmers should have experience writing applications for the X Window System; this manual is not a tutorial on writing Motif applications.

Related Documents

You will find the following documents useful during the porting process:

• OSF/Motif Style Guide
• OSF/Motif Programmer's Guide
• OSF/Motif Programmer's Reference
• DECwindows Companion to the OSF/Motif Style Guide
• DECwindows Motif Guide to Application Programming
• DECwindows Extensions to Motif
• X Window System, Second Edition
• X Window System Toolkit: The Complete Programmer's Guide and Specification

Conventions

This manual uses the following conventions:

Abbreviations and Acronyms

The following abbreviations and acronyms are used throughout this manual:

OSF/Motif is an industry-standard, cross-platform graphical user interface that features three-dimensional visuals and consistent operation and style. Porting your XUI application to Motif is a four-step process, as shown in the following figure:

Follow these steps, in order, to ensure a complete and efficient port of your application.

This chapter is the porting overview, and describes the following Motif features and how these features affect your application:

• Name changes
• Toolkit
• Motif window manager (MWM)
• User Interface Language (UIL)
• User interface style
• Interoperability

Motif provides new, consistent names for the following:

• Widget classes
• Create functions
• Resource manager (Mrm) functions
• Resources
• Enumeration literals
• Callback reasons
• String functions
• Fontlist functions
• Clipboard functions

You must change each instance in your application. Digital provides a set of porting filters to make this process easier, automatically changing the XUI names to Motif names.

1.2 Toolkit

The Motif Toolkit features Motif widgets and Digital Extended Motif widgets, as well as changes to the following:

• Include files
• Custom widget creation
• Callbacks
• Compound string memory use
• Resolution independence
• Scroll bars
• Widget layout

1.3 Motif Window Manager

• Window manager-client interaction
• Keyboard focus
• Key bindings and mouse bindings

1.4 User Interface Language

• Controls (widgets and gadgets)
• Arguments (widget attributes)
• Reasons (callbacks)

Digital provides a set of porting filters to make this process easier, automatically changing the XUI names to Motif names.

1.5 User Interface Style

The OSF/Motif Style Guide specifies the user interface appearance and behavior of Motif applications. This includes the following:

• Client area design
• Menus
• Controls
• Dialog boxes
• Keyboard traversal

See the OSF/Motif Style Guide and DECwindows Companion to the OSF/Motif Style Guide for guidelines on designing and implementing a Motif user interface.

1.6 Interoperability

Motif applications are intended to run with the Motif window manager. These same applications can also run with the older XUI window manager. However, Digital recommends that you run the applications with the MWM in order to take full advantage of the function and appearance of Motif.

If your application users run Motif applications with the XUI window manager, modal widgets will no longer be modal. In fact, application shell windows might be unmapped from the window manager, resulting in transparent windows.

Digital provides a set of porting filters to assist you in converting your XUI files written in C or UIL to Motif files. The filters replace occurrences of XUI names in the input source file with the Motif names. The XUI names can be in the actual code, within quotation marks, or in comments; the filters make the replacement without checking context.

2.1 Before Converting Your Files

Also decide how you will create the user interface. If your application uses toolkit calls to create the user interface and you are planning to convert to User Interface Language (UIL), convert to UIL before converting your source files. The main reason is the porting filters themselves: they convert UIL files more efficiently. Converting to UIL could reduce the time required to port your application, especially if your application is written in a language other than C.

2.2 Interpreting Output from the Filters

In most cases, the filters translate XUI names to Motif names. However, if the filters find an XUI name they cannot translate or an XUI name with multiple possible translations, the filters write a message in the output file identifying the problem. Review these messages and any suggestions in the output file and decide whether they are appropriate for your application.

For example, one filter translates high level XUI subroutine calls to Motif low-level creation calls, writing new low-level code directly into the input source file. In this case, you would look over the new code, check the description and syntax against the OSF/Motif Programmer's Reference, and decide whether it is appropriate for your application.

As the last step in the porting process, you need to give your application users information about the application and OSF/Motif. This involves updating the application and system documentation.

4.1 Updating the Documentation

After you are finished testing your application and making any changes, update the following:

• Application build procedures --- Change the include files and other file names, if you have not already done it.
• Application user manual --- Remove any reference to XUI or XUI operations; change the description of how the application works, if necessary; change routine names; and change any screen pictures to reflect the Motif look.
• Installation procedures and manual --- You might want to change the file names, so you do not overwrite the XUI files for the application; the location of the installed files, to keep them separate from the XUI files; and any screen pictures, to reflect the Motif look.
• Release notes --- If you use release notes, list any behavior changes, routine name changes, and new restrictions.

This appendix summarizes the differences between XUI and OSF/Motif for the following in the following areas: