HP OpenVMS Systems Documentation

DECwindows Extensions to Motif

This manual describes the programming extensions Digital provides to supplement the X Window System, Version 11, Release 5 and OSF/Motif Toolkit components included in the OpenVMS DECwindows Motif Version 1.2 software.

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.

Copyright ©1994

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

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

Motif, OSF, OSF/1, and OSF/Motif are registered trademarks and Open Software Foundation is a trademark of the Open Software Foundation, Inc.

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

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

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

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

ZK5635

This document is available on CD-ROM.

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

Intended Audience

This document, which supplements the OSF/Motif Programmer's Reference and the X Window System manuals, contains reference information for programmers who want to write applications that use the DECwindows Motif Version 1.2 interfaces.

Document Structure

This document is organized as follows:

• Chapter 1 describes Xlib routines Digital has added to OpenVMS systems to supplement those provided by X Window System, Version 11, Release 5. These routines are not available for Digital UNIX systems or Windows NT systems.
• Chapter 2 describes Toolkit widget creation and manipulation routines, message routines, font routines, and convenience routines Digital has added to supplement those provided by the OSF/Motif Toolkit.
• Chapter 3 describes how to use extensions that Digital has added to the Motif User Interface Language (UIL), including how to use nested compound strings, new command line qualifiers in the UIL compiler, and the Widget Meta Language (WML) binary databases.
• Appendix A contains UIL built-in tables you can use to make sure that your UIL specification is consistent with the DECwindows Motif Toolkit.
• Appendix B describes the OpenVMS DECwTermPort routine that Digital provides to allow users to create a DECterm window on a local or remote node.
• Appendix C contains information on Structured Visual Navigation (SVN) and compound string text widget translations.

Associated Documents

The following documents contain related information:

• Overview of DECwindows Motif for OpenVMS Documentation provides an overview of all the documents associated with the DECwindows Motif Version 1.2 release.
• OSF/Motif Programmer's Reference provides reference information 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).
• DECwindows Motif Guide to Application Programming describes how to program with the Digital extensions to the Motif Toolkit. It supplements the OSF/Motif Programmer's Guide.
• OSF/Motif Style Guide describes style guidelines for applications based on the Motif Toolkit.
• DECwindows Companion to the OSF/Motif Style Guide provides style guidelines for Digital extensions to Motif and describes topics not addressed in the OSF/Motif Style Guide.
• X Window System provides reference information on Xlib.
• X Window System Toolkit provides reference information on the Intrinsics.
• VMS DECwindows Guide to Xlib (Release 4) Programming: MIT C Binding describes how to program with Xlib using C bindings.
• X and Motif Quick Reference Guide provides quick reference information on Xlib, Intrinsics, and the Motif Toolkit.
• DECwindows Motif for OpenVMS Applications Guide describes how to use the applications bundled with DECwindows Motif.
• Porting XUI Applications to Motif describes how to port an existing DECwindows application to Motif.

Conventions

The following conventions are used in this manual:

Documentation Format of Routines

The routines described in this document use the following formatting conventions:

• Routine Name
  The exact (case-specific) C name of the routine.
• Overview
  A brief statement describing what the routine does.
• Widget Class Hierarchy
  For widget creation routines, a graphic representation of the order in which widgets inherit resources from their superclass widgets. (Exceptions are listed in the Resource Exceptions section.)
• Format
  The C routine declaration. Note the following syntax conventions:

  Element	Syntax Rule
  Routine entry point name	The name of the routine is shown in initial capital letters. The prefix X is used for Xlib routines and the prefix Xm or DXm is used for Toolkit routines. The routine entry point name is required.
  Parentheses	Open and close parentheses (()) surround the argument list in a routine call. They are required.
  Argument names	Argument names, including return arguments, are always shown in lowercase characters. All arguments are required, unless they are enclosed by brackets ([]). Arguments must be listed in the same order in your program as they appear in the format.
  Spaces	One or more spaces are used between the entry point name and the first argument, and between each argument. They are not required.
  Brackets ([])	Brackets surround optional arguments. The brackets are not required.
  Commas	Commas are required between arguments. Commas that appear inside brackets are optional and appear only when the optional argument appears.

• Resource Information
  For widget creation routines, a list of the resources and their corresponding types.
• Return Value
  A description of the possible values that can be returned by the routine.
• Arguments
  Descriptions of the values that are valid for each argument and what those values indicate.
• Resources
  For widget creation routines, detailed descriptions of the widget-specific resources including the default value and access for each. Access is indicated by the following letter codes:

  Letter Code	Type of Access
  C	The resource can be set when the widget is first created.
  S	The resource can be set at any time.
  G	The value for the resource can be retrieved at any time.

  
  

• Resource Exceptions
  Exceptions regarding the use or characteristics of resources that widgets inherit from their superclass widgets. Exceptions include resources that are either not supported or are supported differently by a particular widget.
• Callback Structure
  For widget creation routines, the C format of the callback data structure.
• Callback Field Descriptions
  For widget creation routines, a description of the fields in the callback data structure.
• Callback Reasons
  For widget creation routines, a description of the callback reasons for the widget.
• Description
  A description of how to use the routine, including pointers to additional information.
• Geometry management
  For widget creation routines, a description of how the widget manages the sizing of its children.
• Resizing
  For widget creation routines, a description of how the widget resizes itself.

This chapter describes the Xlib routines Digital provides on OpenVMS systems to supplement those included in X Window System, Version 11, Release 5. (Note that these routines are not available on Digital UNIX systems or Windows NT systems.)

Specifies an action routine and argument to be called when an event occurs.

Format

XSelectAsyncEvent(display, window_id, event_type,
                  ast_routine, ast_userarg)
      Display        *display;
      Window         window_id;
      unsigned long  event_type;
      int            (*ast_routine)();
      unsigned long  ast_userarg;

Arguments

display

The display information originally returned by XOpenDisplay.

window_id

The identifier of the window for which you want to select asynchronous events.

event_type

The type of event for which you want to select asynchronous events.

ast_routine

The particular asynchronous system trap (AST) action routine to use when notifying the client that the specified event has occurred.

ast_userarg

The user-specified argument to use when notifying the client that the specified event has occurred.

Description

Before calling XSelectInput to specify interest in a particular set of events for a window, clients can call XSelectAsyncEvent to specify an action routine and argument to be called when the specified event occurs.

Xlib uses the client's ast_routine and ast_userarg information to deliver an AST whenever it places the specified event on the event queue. The AST acts only as an event notification mechanism; the application uses the standard Xlib event routines to actually retrieve and process the event from the event queue.

When a client calls the ast_routine, the routine passes the ast_userarg argument to the client by value.

Clients can call XSelectAsyncEvent multiple times to specify different routine and argument pairs for different events for a window. The last call always takes precedence. If a client calls XSelectAsyncEvent with the ast_routine argument equal to zero, asynchronous notification is disabled, but the current selection for the specified event is unaffected.

Notification ASTs are queued in the same order as events are placed in the event queue by Xlib. Therefore, clients can assume that they receive notification ASTs in the same order that they find events in the queue.

XSelectAsyncEvent is similar to XSelectAsyncInput except that XSelectAsyncEvent specifies one event type and XSelectAsyncInput specifies an event mask.

Specifies an action routine and arguments to be called when some subset of events occurs.

Format

XSelectAsyncInput(display, window_id, event_mask,
                  ast_routine, ast_userarg)
  Display        *display;
  Window         window_id;
  unsigned long  event_mask;
  int            (*ast_routine)();
  unsigned long  ast_userarg;

Arguments

display

The display information originally returned by XOpenDisplay.

window_id

The identifier of the window for which you want to select asynchronous input.

event_mask

A bitmask that specifies the event types for which you want to remove an event. The mask is an inclusive OR of one or more of the event mask elements described in Table 1-1.

ast_routine

The particular asynchronous system trap (AST) action routine to use when notifying the client that one of the specified events has occurred.

ast_userarg

The user-specified parameter to use when notifying the client that one of the specified events has occurred.

Description

Before calling XSelectInput to specify interest in a particular set of events for a window, clients can call XSelectAsyncInput to specify action routines and arguments to be called when some subset of those events occurs.

Xlib uses the client's ast_routine and ast_userarg information to deliver an AST whenever it places one of the specified events on its event queue. The ast_routine and ast_userarg arguments allow the client to specify the particular action routine and parameter pair to use when notifying the client that one of the specified events has occurred. The AST acts only as an event notification mechanism; the application uses the standard Xlib event routines to actually retrieve and process the event from the event queue.

Clients can call XSelectAsyncInput multiple times to specify different routine and parameter pairs for different sets of events for a window. The last call always takes precedence. If called with ast_routine equal to zero, asynchronous notification is disabled, but the current selection for the specified events is unaffected.

Notification ASTs are queued in the same order as events are placed in the event queue by Xlib. Therefore, clients can assume that they receive notification ASTs in the same order that they find events in the queue.

XSelectAsyncInput is similar to XSelectAsyncEvent except that XSelectAsyncEvent specifies one event type and XSelectAsyncInput specifies an event mask.