Order Number: AA--PGZEB--TE
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
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.
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.
ZK5639
This document is available on CD-ROM.
This document was prepared using DECdocument, Version V3.3-1e.
| Contents | Index |
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.
For more information about the DECwindows product, see the following documentation:
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. |
This chapter describes the DECwindows Motif Toolkit, including overviews of the following topics:
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:
The Toolkit consists of the following components:
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:
There are three main types of widgets in the 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
In addition to the standard OSF/Motif widgets, the DECwindows Motif Toolkit includes the following widgets provided by Digital:
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);
XmStringFree(appname);
XmStringFree(glossarytopic);
XmStringFree(overviewtopic);
XmStringFree(libspec);
|
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:
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:
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 |