HP OpenVMS Systems Documentation

Content starts here

DECwindows Motif Guide to Application Programming

DECwindows Motif Guide to Application Programming

January 1994

This document describes the programming interface for widgets provided by Digital in the DECwindows Motif Version 1.2 Toolkit. This document also includes tutorial programming information for the DECwindows Motif Version 1.2 Toolkit.

Revision/Update Information: This is a revised manual.

Operating System: OpenVMS AXP Version 1.5
VMS Version 5.5--2

Software Version: DECwindows Motif Version 1.2 for OpenVMS AXP
DECwindows Motif Version 1.2 for OpenVMS VAX

Digital Equipment Corporation
Maynard, Massachusetts

January 1994

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 ©1994

The following are trademarks of Compaq Computer Corporation: Alpha AXP, AXP, Bookreader, DEC, DECpaint, DECterm, DECwindows, DECwrite, Digital, eXcursion, OpenVMS, VAX, VAX DOCUMENT, VMS, XUI, and the DIGITAL logo.

The following are third-party trademarks:

Adobe, Display Postscript, and PostScript are registered trademarks of Adobe Systems Incorporated.

Helvetica and Times are registered trademarks of Allied Corporation.

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

ITC Avant Garde Gothic is a registered trademark of International Typeface Corporation.

UNIX is a registered trademark licensed exclusively by the X/Open Company Limited.

Windows is a trademark, and Windows NT and NT are registered trademarks of Microsoft Corporation.

X Window System is a trademark of the Massachusetts Institute of Technology.

All other trademarks and registered trademarks are the property of their respective holders.


This document is available on CD-ROM.

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

Contents Index


Intended Audience

This document is intended for programmers who need information about the DECwindows Motif Toolkit.

This document assumes that you are familiar with the overall design of the DECwindows implementation.

Document Structure

  • Chapter 1 describes the DECwindows Motif Toolkit. You should read this chapter to become familiar with the DECwindows Motif Toolkit implementation. The chapter is intended to complement the introductory chapters in the OSF/Motif Programmer's Guide.
  • Chapter 2 describes how to use the Toolkit to design a DECwindows application interface. The chapter includes a description of the DECburger application interface. (Note that the DECburger demo application is available only on OpenVMS systems.)
  • Chapter 3 describes helpful programming hints on a variety of topics.
  • Chapter 4 describes how to use the help widget in an application.
  • Chapter 5 describes how to use the DECwindows Help System in an application.
  • Chapter 6 describes how to use the color mixing widget in an application.
  • Chapter 7 describes how to use the print widget in an application.
  • Chapter 8 describes how to use the compound string widget in an application.
  • Chapter 9 describes how to use the structured visual navigation widget in an application.
  • Chapter 10 describes a set of interoperability coding recommendations that you should follow if you are writing DECwindows applications for multiple hardware platforms.
  • Appendix A describes how to use the DECwTermPort routine to create a DECterm window on OpenVMS systems.

Associated Documents

For more information about the DECwindows product, see the following documentation:

  • DECwindows Extensions to Motif provides reference information on the Digital extensions to Motif.
  • DECwindows Motif for OpenVMS Guide to Non-C Bindings describes non-C bindings for Xlib, Intrinsics, Motif Toolkit, and Digital extension routines.
  • DECwindows Companion to the OSF/Motif Style Guide covers style issues for Digital extensions to Motif and topics not addressed in the OSF/Motif Style Guide.
  • VMS DECwindows Guide to Xlib Programming: MIT C Binding describes how to program with Xlib using C bindings.
  • VMS DECwindows Guide to Xlib (Release 4) Programming: VAX Binding describes how to program with Xlib using VAX bindings.
  • Porting XUI Applications to Motif describes how to port an existing XUI DECwindows application to Motif.
  • X Window System, Third Edition (from Digital Press), provides reference information on Xlib.
  • X Window System Toolkit (from Digital Press) provides reference information on the Intrinsics.
  • X and Motif Quick Reference Guide (from Digital Press) provides quick reference information on Xlib, Intrinsics, and the Motif Toolkit.
  • OSF/Motif Style Guide describes style guidelines for applications based on the Motif Toolkit.
  • OSF/Motif Programmer's Guide describes how to program with the Motif Window Manager, Motif Toolkit, and the Motif User Interface Language (UIL).
  • OSF/Motif Programmer's Reference provides reference information on the Motif Toolkit.


The following conventions are used in this manual:

mouse The term mouse is used to refer to any pointing device, such as a mouse, a puck, or a stylus.
MB1 (Select)
MB2 (Drag)
MB3 (Menu)
MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)
Ctrl+x A sequence such as Ctrl+x (or Ctrl/x) indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button.
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.
boldface text Boldface text represents the introduction of a new term or the name of an argument, a field, a resource, or a reason.

Boldface text is also used to show user input in online versions of the book.

italic text Italic text represents information that can vary in system messages (for example, Internal error number).
UPPERCASE TEXT Uppercase letters indicate that you must enter a command (for example, enter OPEN/READ), or they indicate the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege.
- Hyphens in coding examples indicate that additional arguments to the request are provided on the line that follows.
numbers Unless otherwise noted, all numbers in the text are assumed to be decimal. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1

This chapter describes the DECwindows Motif Toolkit, including overviews of the following topics:

  • DECwindows Motif Toolkit
  • Basic DECwindows Motif Toolkit programming concepts

You should read this chapter to become familiar with the DECwindows Motif Toolkit implementation.


This chapter is intended to complement the introductory chapters in the OSF/Motif Programmer's Guide, which is the definitive source of programming information for the Motif Toolkit.

The DECwindows Motif Toolkit on OpenVMS systems includes an example application called DECburger. DECburger is based on the OSF/Motif Motifburger application and demonstrates the use of widgets provided by Digital. Section 1.5 describes how to compile, link, and run the DECburger application. (Note that the DECburger application is unavailable on Digital UNIX or Windows NT systems.)

1.1 Overview of DECwindows Motif Toolkit

The DECwindows Motif Toolkit, hereinafter called the Toolkit, is a set of application development tools and run-time routines you can use to create and manage a DECwindows application user interface.

The Toolkit is based on the OSF/Motif Toolkit and the X Toolkit Intrinsics, Release 5, and includes widgets and support routines added by Digital. The widgets and support routines provided by Digital have the prefix DXm. In the case of the Structured Visual Navigation (SVN) widget, the prefix is DXmSvn.

Using the Toolkit, you can:

  • Open a connection to a display device
  • Create a complete user interface for your application
  • Perform output operations to windows
  • Receive input from windows

The Toolkit consists of the following components:

  • A set of user interface objects, with run-time routines to create them
  • A pair of application development tools, called the User Interface Language (UIL) and the Motif Resource Manager (MRM)
  • A set of run-time routines to manipulate the widgets, called X Toolkit intrinsics. The intrinsics routines have the prefix Xt.

1.1.1 Toolkit Building Blocks: Widgets and Gadgets

The Toolkit provides a set of user interface objects called widgets. Widgets are the building blocks for the user interface of an application.

From a user's perspective, widgets are the interface for an application; users use menus, push buttons, scroll bars, and text widgets to make selections, view output, enter input, and so forth. Because the Toolkit implements widgets with a consistent appearance and behavior, users can move between DECwindows applications without having to learn how to use a new interface.

From a programmer's perspective, widgets are windows that are logically connected to application functions. When a user interacts with a widget (for example, by making a menu selection), information in the widget makes the application respond appropriately.

A Toolkit widget is made up of a window packaged with input and output capabilities. Some widgets display information, such as text or graphics. Others are merely containers for other widgets. Some widgets are for output only and do not react to pointer or keyboard input. Others change their display in response to input and can invoke functions that an application has attached to them.

Each widget supports a set of attributes---such as width, height, font, color, and border width---that you can use to customize the widget's appearance and function. The Toolkit assigns default values to widget attributes to create widgets that conform to the recommendations of the OSF/Motif Style Guide.

Some widgets in the Toolkit have variants, called gadgets. Gadgets have the same general appearance as their widget counterparts but have restricted capabilities. Gadgets use fewer system resources and can offer improved application performance. For example, gadgets do not have an associated window, thus eliminating the processing involved with creating a window. On the other hand, gadgets do not provide access to all the attributes supported by their widget counterparts.

To build a user interface using widgets (or gadgets), you create instances of the widgets in your application program. When you create a widget, you specify its parent/child relationship, its initial appearance, and other characteristics by assigning values to widget attributes.

When you create widgets in an application, you specify the following:

  • The hierarchy of widgets
    For example, an interface object might consist of a box (parent) with buttons (children) inside the box. Both the box and buttons are widgets; specifying the hierarchy of widgets entails establishing the relationship between the box and buttons.
  • The characteristics of each widget
    For example, you specify the height, width, and position of a widget.
  • The routines your application executes when a user provides input to the interface

1.1.2 Widget Types

There are three main types of widgets in the Toolkit:

  • Input/output widgets
    These widgets provide the basic input and output capabilities of a user interface, such as displaying text or graphics, allowing text editing, and enabling user input to your application. The widgets that provide these functions are the XmLabel, XmPushButton, XmToggleButton, XmScale, XmScrollBar, and XmText widgets.
  • Container widgets
    These widgets act as containers for other widgets. You use these widgets to gather together the widgets that provide access to the functions of your application. The widgets that provide these functions include the XmBulletinBoard, XmForm, and XmMainWindow widgets. The Toolkit includes container widgets that are preconfigured to perform commonly needed functions such as presenting caution messages.
  • Choice widgets
    These widgets present choices to the user of your application. The widgets that provide these functions include the XmList widget.

1.1.3 Widgets in the OSF/Motif Toolkit

As described in Section 1.1, the DECwindows Motif Toolkit is based on the OSF/Motif Toolkit. The OSF/Motif Toolkit widgets are described in the OSF/Motif Programmer's Guide.

The OSF/Motif demonstration program Periodic demonstrates the use and appearance of many of the OSF/Motif widgets. The Periodic main window is shown in Figure 1-1.

Figure 1-1 The OSF/Motif Periodic Demonstration Program

1.1.4 Widgets Provided by Digital

In addition to the standard OSF/Motif widgets, the DECwindows Motif Toolkit includes the following widgets provided by Digital:

  • Help widget
  • Print widget
  • Color mixing widget
  • Compound string text widget
  • SVN widget

Using these widgets can save you considerable programming time, while allowing your application to comply with the DECwindows Companion to the OSF/Motif Style Guide. The programming interface to these widgets, with examples, is documented in subsequent chapters.

1.1.5 Toolkit Widget and Gadget Routines

The Toolkit routines let you create and manipulate all of the Toolkit widgets, including those provided by Digital. To use these routines, you assign values to widget attributes in a data structure called an argument list. You then pass this argument list to the Toolkit routine, as shown in Example 1-1.

Example 1-1 Passing an Argument List

static void create_help (topic)
            XmString   topic;

     unsigned int    ac;
     (1)Arg         arglist[10];
     XmString        appname, glossarytopic, overviewtopic, libspec;
     static Widget   help_widget = NULL;

      if (!help_widget) {
      ac = 0;
      appname = XmStringCreateLtoR("Toolkit Help", XmSTRING_ISO8859_1);
      glossarytopic = XmStringCreateLtoR("glossary", XmSTRING_ISO8859_1);
      overviewtopic = XmStringCreateLtoR("overview", XmSTRING_ISO8859_1);
      libspec = XmStringCreateLtoR("decburger.hlb", XmSTRING_ISO8859_1);

      (2)XtSetArg(arglist[ac], DXmNapplicationName, appname); ac++;
      XtSetArg(arglist[ac], DXmNglossaryTopic, glossarytopic); ac++;
      XtSetArg(arglist[ac], DXmNoverviewTopic, overviewtopic); ac++;
      XtSetArg(arglist[ac], DXmNlibrarySpec, libspec); ac++;
      XtSetArg(arglist[ac], DXmNfirstTopic, topic); ac++;

      (3)help_widget = DXmCreateHelpDialog (toplevel_widget,
                                         "Toolkit Help",
                                          arglist, ac);
  1. Declare an array of 10 Arg data structures.
  2. Call XtSetArg to set values into the argument list.
  3. Create the widget, passing in the argument list and the count of argument data structures.

Although you can use widget manipulation routines to access the complete set of widget attributes after a widget has been created, it is more efficient to assign values to widget attributes when you create the widget.

The Toolkit routines common to the OSF/Motif Toolkit are described in the OSF/Motif Programmer's Reference. The routines provided by Digital are described in DECwindows Extensions to Motif.

1.1.6 Application Development Tools

The Toolkit provides routines for creating a widget hierarchy and specifying the complete set of attributes of a widget. Moreover, the Toolkit includes additional tools that simplify the process further---the User Interface Language (UIL) Compiler and the Motif Resource Manager (MRM) routines.

UIL is a user interface definition language. Using UIL, you specify the "form" of the application---that is, the user interface---in a text file called a UIL specification file and compile this specification file using the UIL compiler.

The UIL specification file defines the following characteristics of the user interface:

  • The widgets that comprise the interface
  • The hierarchy of widgets in the application
  • The characteristics of the specified widgets
  • The callback routines for each widget

Because you compile the specification file separately from the functional routines, you separate form and function in an application. For example, you can use UIL to create an OK XmPushButton without having to specify what happens when a user presses this button. The application's functional routines determine what happens when a user presses the OK push button.

When you define widgets in a UIL specification file, you can access the complete set of widget attributes. The UIL compiler checks that the values you assign to attributes are of the data type expected by the widget. At run time, your application retrieves the compiled interface specification, called a UID file, using MRM routines.

MRM routines enable you to open the UID specification file, retrieve the widget definitions from the file, create the widgets, and build the user interface at run time.

1.1.7 Internationalization Using UIL and MRM

Using UIL and MRM, you can change the user interface specification without making major changes to your main application program. This feature of UIL and MRM is particularly important for applications developed for international markets. For example, you can create user interfaces in several languages for a single application.

1.1.8 Toolkit Intrinsic Routines

X Toolkit routines, called intrinsics, let you manipulate widgets at run time. The X Toolkit Intrinsics is a standard routine library layered on the X Window System, Version 11, R5.

Intrinsics are the basis of every application. You use intrinsics to do the following:

  • Initialize the Toolkit
  • Map and unmap widgets to the screen
  • Process input from an application end user

1.2 Toolkit Routines Contrasted with UIL

You can use either UIL or the Toolkit routines to create the initial instance of each widget for your application. You will probably find that it is much more convenient to use UIL because of the separation between form and function that UIL allows. For example, you can dramatically change the user interface for an application, recompile the UIL module into the UID file, and not make any changes to your application source code.

However, once you have created the initial user interface, you must use the Toolkit routines to make changes to widget resources in response to user actions. For example, assume that you create a Color Mixing widget through UIL. You can set the initial red, green, and blue colors for the widget through UIL. If you then need to change these colors in response to a user action, you must use the Toolkit routines.

Next Contents Index