HP OpenVMS Systems Documentation
Content starts here

DECwindows Motif for OpenVMS Guide to Non-C Bindings
Previous Contents Index

1.2 Intrinsics, OSF/Motif Toolkit, and Digital Extension Routines Template

This section describes each element in the template that documents the Intrinsics, OSF/Motif Toolkit, and Digital Extension routines.

Routine Name

The generic name of the routine.

Format

The generic routine call format. The bindings file for each language supplies the correct elements for that language. Table 1-5 describes the syntax conventions.

Table 1-5 Syntax Conventions
Element Conventions
Routine entry point name The name is shown in its generic form, mixed case, with the prefixes Xt, Xm or DXm corresponding to Intrinsic, OSF/Motif Toolkit, or Digital Extension Routines. The routine entry point name is required.
Return values If there is a return value, it precedes the entry point name and is in the same font as the arguments. A void is implied when there is no return value.
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, appear in mixed case. Arguments in brackets are optional. In a program, list the arguments in the order they appear in the format.
Spaces One or more spaces are shown between the entry point name and the first argument, and between 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 containing information about each argument follows the format section. Arguments are described in order, beginning with the return value, if any. The table lists each argument name, type, access, and mechanism.

Type

Table 1-6 describes the argument type entries. Type names in all caps are generic types; the bindings files for each language translate them into the conventions of that language. Types in mixed case are defined within the language bindings files and can, in most cases, be used as documented.

Table 1-6 Type Entries
Entry Description
ADDRESS An unsigned longword containing the virtual address of data or code.
ANY An unsigned longword containing either data or a pointer to data.
Arg A structure consisting of two fields: name (the address of a character string) and value (a longword integer containing either data or a pointer to data).
ArgList An array of Arg structures.
Atom An unsigned longword integer interpreted as an X atom.
Boolean A single byte with the predefined values of 1 for true and 0 for false. The language bindings define the constants XtTrue as one and XtFalse as zero for the purpose of setting Boolean values in languages where the native values of true and false do not equate to one and zero.
BYTE A signed byte integer.
BYTE UNSIGNED An unsigned byte integer.
Cardinal An unsigned longword integer.
CHARACTER A byte integer containing an ASCII character value.
Colormap An unsigned longword integer interpreted as an X color map.
Cursor An unsigned longword integer interpreted as an X cursor.
Dimension An unsigned word integer.
Display An unsigned longword integer interpreted as an X display.
DXmColorMixWidget A DXm color mix widget.
DXmCSTextStatus An unsigned longword integer (actually a C enumerated type).
DXmCSTextPosition A signed longword integer.
DxmCSTextWidget A DXm compound string text widget.
Event An X event structure.
EventMask An unsigned longword integer interpreted as an X event mask.
Font An unsigned longword integer interpreted as an X font.
GC An unsigned longword integer interpreted as an X graphics context.
I18nContext Address of an I18nContextRec structure.
KeyCode An unsigned longword integer interpreted as an X keycode.
KeySym An unsigned longword integer interpreted as an X keysym.
LONGWORD A signed longword integer.
LONGWORD UNSIGNED An unsigned longword integer.
Modifiers An unsigned longword integer interpreted as an Intrinsics modifier key mask.
MrmCode A signed word integer.
MrmCount A signed word integer.
MrmHierarchy An address interpreted as an Mrm hierarchy pointer.
MrmOsOpenParamPtr The address of an MrmOsOpenParam structure.
MrmRegisterArg A structure consisting of two fields: name (the address of a character string) and value (of type Opaque).
MrmType A signed word integer.
Opaque A value of type address.
Pixel An unsigned longword integer interpreted as an X pixel.
Pixmap An unsigned longwrd integer interpreted as an X pixmap.
Position A signed word integer.
Region An unsigned longword integer interpreted as an X region.
Screen An unsigned longword integer interpreted as an X screen.
Substitution The address of an Intrinsics Substitution Rec.
Time An unsigned longword integer interpreted as an X timestamp value.
VoidProc An entry mask to a procedure with no return value.
Widget An address interpreted as a widget identifier.
WidgetClass An address interpreted as a widget class pointer.
WidgetList An array of widgets.
Window An unsigned longword integer interpreted as an X window.
WORD UNSIGNED An unsigned word integer.
XEvent An Xlib event structure.
XImage An Xlib XImage structure.
XGCValues An unsigned longword interpreted as a pointer to an Xlib XGCValues structure.
XKeyPressedEvent An X event.
XmClipboardPendingList An array of XmClipboardPendingRec structures.
XmColorProc An entry mask to a procedure with no return value.
XmCutPasteProc A callback procedure.
XmDropSiteVisuals An XmDropSiteVisualsRec structure type.
XmDropTransferEntry An XmDropTransferEntryRec structure type.
XmFontContext An address interpreted as a Motif font context.
XmFontList An address interpreted as a Motif font list.
XmFontListEntry An XmFontListRec structure type.
XmFontType An unsigned longword.
XmHighlightMode An unsigned longword (actually a C enumerated type).
XmOffset A signed longword integer.
XmOffsetPtr The address of a variable of type XmOffset.
XmRepTypeId An unsigned word.
XmRepTypeList An XmRepTypeListRec structure type.
XmString An address interpreted as a Motif compound string.
XmStringCharSet An address interpreted as a Motif character set identifier.
XmStringComponentType An unsigned byte integer.
XmStringContext An address interpreted as a Motif compound string context.
XmStringDirection An unsigned byte integer.
XmStringTable An array of XmStrings.
XmStringTextBlock The address of an XmTextBlockRec.
XmStringTextFormat An unsigned longword integer.
XmTextBlock A structure used to pass text.
XmTextDirection An unsigned longword.
XmTextPosition A signed longword integer.
XmTextSource An address interpreted as a Motif text source.
XmTraversalDirection An unsigned longword that describes traversal direction.
XmVisibility An unsigned longword.
XRectangle An X rectangle structure.
XrmDatabase An unsigned longword integer.
XrmValuePtr An address interpreted as an Xrm value pointer.
XtAddressMode An unsigned longword integer (actually a C enumerated type).
XtAccelerators An address interpreted as a compiled Intrinsics accelerator table.
XtActionHookId A value of Opaque type.
XtActionHookProc An entry mask to a procedure with no return value.
XtActionList An array of Intrinsics XtActionsRec structures.
XtActionProc An entry mask to a procedure with no return value.
XtAppContext An address interpreted as an Intrinsics application context.
XtArgVal A signed longword integer.
XtCallbackList An array of Intrinsics XtCallbackRec structures.
XtCallbackProc An entry mask to a procedure with no return value.
XtCacheRef A value of Opaque type.
XtCacheType A signed longword integer.
XtCancelConvertSelectionProc An entry mask to a procedure with no return value.
XtCaseProc An entry mask to a procedure with no return value.
XtConvertSelectionProc An entry mask to a procedure with a Boolean return value.
XtConverter An entry mask to a procedure with no return value.
XtDestructor An entry mask to a procedure with no return value.
XtErrorHandler An entry mask to a procedure with no return value.
XtErrorMsgHandler An entry mask to a procedure with no return value.
XtEventHandler An entry mask to a procedure with no return value.
XtFilePredicate An entry mask to a procedure with a Boolean return value.
XtGCmask An unsigned longword integer.
XtGeometryMask An unsigned longword integer.
XtGeometryResult An unsigned longword integer (actually a C enumerated type).
XtGrabKind An unsigned longword integer (actually a C enumerated type).
XtIntervalId An unsigned longword integer.
XtInputCallbackProc An entry mask to a procedure with no return value.
XtInputId An unsigned longword integer.
XtInputMask An unsigned longword integer.
XtLanguageProc An entry mask to a procedure that returns a null-terminated string.
XtListPosition An unsigned longword integer.
XtLoseSelectionProc An entry mask to a procedure with no return value.
XtPointer A value of type address.
XtSelectionCallbackProc An entry mask to a procedure with no return value.
XtSelectionDoneProc An entry mask to a procedure with no return value.
XtString A null-terminated string of from 0 to 65,535 8-bit characters.
XtStringArray An array of XtStrings.
XtTimerCallbackProc An entry mask to a procedure with no return value.
XtTranslations An address interpreted as a compiled Intrinsics translation table.
XtTypeConverter An entry mask to a procedure with a Boolean return value.
XtWidgetGeometry An XtWidgetGeometry structure.
XtWorkProc An entry mask to a procedure with a Boolean return value.
XtWorkProcID An unsigned longword integer.

Access

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" and when the argument is returned by the routine, the access is "write only." See Table 1-7 for a list of access entries used.

Table 1-7 Access Entries
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.

Mechanism

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" and when the argument is a pointer to the value, the mechanism is "by reference." See Table 1-8 for a complete list of mechanism entries.

Table 1-8 Mechanism Entries
Entry Description
value The argument contains the actual data to be used by the routine.
reference The argument contains the address of the data to be used by the routine. The argument is a pointer to the actual data.

Previous Next Contents Index