Porting XUI Applications to Motif
Porting XUI Applications to Motif
This guide describes how to convert XUI applications to OSF/Motif
This is a new manual.
Operating System and Version:
ULTRIX Version 4.2
VMS Version 5.4
ULTRIX Worksystem Software
VMS DECwindows Motif Version 1.0
Digital Equipment Corporation
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
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Compaq Computer Corporation or its
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.
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
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.
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
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
This manual uses the following conventions:
In syntax and function descriptions, italic type indicates terms that
Unless otherwise specified, every command line is terminated by
pressing the Return key.
In examples, a horizontal ellipsis indicates one of the following
- 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
Motif Window Manager
User Interface Language
ULTRIX Worksystem Software
X User Interface
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
- Motif window manager (MWM)
- User Interface Language (UIL)
- User interface style
1.1 Name Changes
Motif provides new, consistent names for the following:
- Widget classes
- Create functions
- Resource manager (Mrm) functions
- 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.
The Motif Toolkit features Motif widgets and Digital Extended Motif
widgets, as well as changes to the following:
- Include files
- Custom widget creation
- 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
- 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
- Client area design
- 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.
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
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
After Converting Your Files
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
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
- Release notes --- If you use release notes, list
behavior changes, routine name changes, and new restrictions.
Summary of XUI and OSF/Motif Differences
This appendix summarizes the differences between XUI and OSF/Motif for
the following in the following areas:
Porting Filter Summary
Intrinsics Routine Summary