Porting XUI Applications to Motif

Document revision date: 10 November 2000

Porting XUI Applications to Motif

Order Number: AA--PGZFA--TE

August 1991

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

August 1991

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.

Contents Index

Preface

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.

Conventions

This manual uses the following conventions:

italics In syntax and function descriptions, italic type indicates terms that are variable.

[Return] Unless otherwise specified, every command line is terminated by pressing the Return key.

... In examples, a horizontal ellipsis indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

Abbreviations and Acronyms

The following abbreviations and acronyms are used throughout this manual:

MWM Motif Window Manager

UIL User Interface Language

UWS ULTRIX Worksystem Software

XUI X User Interface

Chapter 1
Introduction to Porting

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

1.1 Name Changes

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

Motif features a new window manager, with changes in the following areas:

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

1.4 User Interface Language

The Motif User Interface Language (UIL) features changes for each object in the Motif Toolkit. These changes include new names, consistent with the Toolkit, for the following:

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.

Chapter 2
Converting Your XUI Files

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

Before you convert your XUI files, set up two directories: one for XUI and one for Motif. This will make it easier to keep track of the original files and aid in verifying the changes after the conversion. Also, if you are going to support both Motif and XUI on your system, separate directories reduce user and programmer confusion about which files to use.

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.

Chapter 3
After Converting Your Files

Chapter 4
Giving Information to Application Users

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.

Appendix A
Summary of XUI and OSF/Motif Differences

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

Appendix B
Porting Filter Summary

Appendix C
Intrinsics Routine Summary

Index

Contents

privacy and legal statement

5640PRO.HTML

italics	In syntax and function descriptions, italic type indicates terms that are variable.
`[Return]`	Unless otherwise specified, every command line is terminated by pressing the Return key.
...	In examples, a horizontal ellipsis indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

MWM	Motif Window Manager
UIL	User Interface Language
UWS	ULTRIX Worksystem Software
XUI	X User Interface