Order Number: AA--PGZ8B--TE
This guide supplies non-C bindings for programmers developing DECwindows Motif for OpenVMS applications in languages other than C. Pascal and Fortran are supported. Programmers can choose from among OSF/Motif and ancillary widgets supplied by Digital.
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.
The following are trademarks of Compaq Computer Corporation: Alpha AXP, AXP, Bookreader, DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, and the DIGITAL logo.
The following are third-party trademarks:
Open Software Foundation is a trademark, and OSF/Motif and Motif are registered trademarks of the Open Software Foundation, Inc.
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.
ZK5636
This document is available on CD-ROM.
This document was prepared using DECdocument, Version V3.3-1e.
| Contents | Index |
This manual is intended for programmers who develop DECwindows Motif applications in languages other than C. Use this guide in conjunction with the following reference manuals:
The bindings are presented in alphabetical order, followed by the associated routines in a separate chapter. This guide is divided into four parts and contains the following chapters:
Chapter 1---Introduction
Part 1 contains the following:
Chapter 2---Xlib Routines
Chapter 3---Xlib Data Structures and Error Codes
Part 2 contains the following:
Chapter 4---Intrinsics Routines
Chapter 5---Intrinsics Data Structures
Part 3 contains the following:
Chapter 6---OSF/Motif Toolkit Routines
Chapter 7---OSF/Motif Toolkit Data Structures
Part 4 contains the following:
Chapter 8---DECwindows Toolkit Extensions Routines
Chapter 9---DECwindows Toolkit Extensions Data Structures
In addition to the reference information, see also:
The following conventions are used in this manual:
In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.
In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating system, every use of OpenVMS VAX means the OpenVMS VAX operating system, and every use of OpenVMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system.
| Ctrl/ x | A sequence such as 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 and then press and release another key or a pointing device button. |
| GOLD x |
A sequence such as GOLD
x indicates that you must first press and release the key
defined as GOLD and then press and release another key. GOLD key
sequences can also have a slash (/), dash (--), or underscore (_) as a
delimiter in EVE commands.
The GOLD key definition is often mapped to the PF1 key on the keypad. |
| [Return] | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) |
| ... |
Horizontal ellipsis points in examples indicate one of the following
possibilities:
|
|
.
. . |
Vertical ellipsis points indicate 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. |
| ( ) | In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. |
| [ ] | In command format descriptions, brackets indicate optional elem You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.) |
| { } | In command format descriptions, braces surround a required choice of options; you must choose one of the options listed. |
| boldface text |
Boldface text represents the introduction of a new term or the name of
an argument, an attribute, or a reason (user action that triggers a
callback).
Boldface text is also used to show user input in Bookreader versions of the manual. |
| italic text | Italic text emphasizes important information and indicates complete titles of manuals and variables. Variables include information that varies in system messages (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters). |
| UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
| struct | Monospace type in text identifies the following C programming language elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example. |
| - | A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows. |
| numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, oc hexadecimal---are explicitly indicated. |
| mouse | The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus. |
| MB1, MB2, MB3 | MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The user can redefine the buttons.) |
| PB1, PB2, PB3, PB4 | PB1, PB2, PB3, and PB4 indicate buttons on the puck. |
| SB1, SB2, SB3 | SB1, SB2, and SB3 indicate buttons on the stylus. |
This manual provides OpenVMS documentation required by DECwindows programmers using languages other than C. This chapter outlines each section and element in the routine templates.
There are two separate routine templates, one for each binding format:
This section describes each element in the Xlib Routine template.
The generic name of the routine.
The OpenVMS routine call format. The format syntax is summarized in Table 1-1.
| Element | Syntax Rule |
|---|---|
| Routine entry point name | The name is shown in all capital letters with the prefix X. The routine entry point name is required. |
| Equal sign | For specific return values, the equal sign is required. |
| Parentheses | Open and close parentheses surround the argument list in a routine call. Parentheses are required. |
| Argument names | Argument names, including names of return arguments, are always shown in lowercase characters. All arguments not enclosed by brackets ([]) are required. Argument names must be listed in the same order in your program as they appear in the format. |
| Spaces | A line break follows the entry point name and the arguments. A comma, followed by a space separate each argument. Spaces are not required. |
| Brackets | Brackets ([]) surround optional arguments. Commas that appear inside brackets are optional and appear only when the optional argument appears. Brackets are not required. |
| Commas | Commas must appear between required arguments. When commas appear inside brackets ([]), they appear only when the optional argument appears. |
A table follows the OpenVMS format listing. The table lists, in order, each argument name, usage, data type, access, and mechanism.
The Usage column specifies the general OpenVMS binding argument type. For example, if the argument is a resource identifier, the Usage field is "identifier." This field provides additional information about the argument that is helpful when declaring the argument within a program. See Table 1-2 for a list of usage entries used in Xlib routines.
| Entry | Description |
|---|---|
| address | An unsigned longword containing the virtual address of data or code, but not of a procedure entry mask (which is a procedure entry). |
| any | An unsigned longword containing either data or a pointer to data. |
| array | An array with the specific description of its elements provided in the argument description. |
| Boolean | An unsigned longword with the predefined values of 1 for true and 0 for false. |
| byte | A signed byte integer. |
| uns byte | An unsigned byte integer. |
| char string | A string of 0 to 65,535 8-bit characters. |
| cond value |
Unsigned longword specifying that a predefined condition value will be
returned in R0.
The cond value status return is SS$_NORMAL for success; the return value can be either zero or an OpenVMS condition code for failure. |
| identifier | A value used to refer to a resource. It is originally returned by the system. In the OpenVMS binding, an identifier is a longword integer (unsigned). |
| longword | A signed longword integer. |
| uns longword | An unsigned longword integer. |
| mask longword | An unsigned longword interpreted as a bit mask. |
| procedure | An entry mask to a procedure. |
| record | A data structure with the specific description of the structure provided in the argument description. |
| word | A signed word integer. |
| uns word | An unsigned word integer. |
The Data Type column specifies the standard OpenVMS data type of the argument. For example, if the argument is a resource identifier, the data type is "longword (unsigned)." If the argument has a predefined value, it is provided in the description of the argument.
The following OpenVMS data type entries are used in the Xlib routines:
| x$any_event | x$keyboard_control |
| x$arc | x$keyboard_state |
| x$button_event | x$keymap_event |
| x$char_2b | x$map_event |
| x$char_struct | x$map_request_event |
| x$circ_request_event | x$mapping_event |
| x$circulate_event | x$modifier_keymap |
| x$class_hint | x$motion_event |
| x$clie_message_event | x$no_expose_event |
| x$color | x$point |
| x$colormap_event | x$property_event |
| x$compose_status | x$rectangle |
| x$conf_request_event | x$reparent_event |
| x$configure_event | x$resource_req |
| x$creat_window_event | x$resz_request_event |
| x$crossing_event | x$rm_value |
| x$depth | x$screen |
| x$destr_window_event | x$screen_format |
| x$display | x$segment |
| x$error_event | x$sel_request_event |
| x$event | x$select_clear_event |
| x$expose_event | x$selection_event |
| x$ext_codes | x$set_win_attributes |
| x$ext_data | x$size_hints |
| x$focus_change_event | x$standard_colormap |
| x$font_prop | x$text_item |
| x$font_struct | x$text_item_16 |
| x$frame | x$text_property |
| x$gc_struct | x$time_coord |
| x$gc_values | x$unmap_event |
| x$graph_expose_event | x$visibility_event |
| x$gravity_event | x$visual |
| x$host_address | x$visual_info |
| x$icon_size | x$window_attributes |
| x$image | x$window_changes |
| x$key_event | x$wm_hints |
The Access column specifies the way in which the called routine accesses the argument. For example, when the argument is passed as input, the access is "read only" for both bindings and when the argument is returned by the routine, the access is "write only" for both bindings. See Table 1-3 for a list of access entries used in the Xlib routines.
| Entry | Description |
|---|---|
| read | Input data required by the routine to perform its operation must be readable. When an argument specifies input data, the access entry is readable. The routine cannot write data back to this argument. |
| write | Output data returned by the routine to a specific location. When an argument specifies output data, the access entry is writable. The routine does not read the contents of the location either before or after it writes into the location. |
| modify | The routine reads the input data, which it uses in its operation, and then overwrites the input data with the results (the output data) of the operation. Thus, when the routine completes execution, the input data specified by the argument is lost. |
The Mechanism column specifies the passing mechanism used by the called routine. For example, when the argument is the value itself, the mechanism is "by value"; when the argument is a pointer to the value, the mechanism is "by reference." See Table 1-4 for a complete list of mechanism entries used in the Xlib routines.
| Entry | Description |
|---|---|
| value | The argument contains the actual data to be used by the routine. Note that because an argument is only one longword in length, only data that can be represented in one longword can be passed by value. |
| reference | The argument contains the address of the data to be used by the routine. The argument is a pointer to the actual data. |
| descriptor | The argument contains the address of a descriptor. A descriptor consists of two or more longwords (depending on the type of descriptor used), which describes the location, length, and the OpenVMS standard data type of the data to be used by the called routine. The argument is a pointer to a descriptor that itself is a pointer to the actual data. |
| Next | Contents | Index |