# Compatibility Functions

This appendix is part of the formal Intrinsics Specification.

In prototype versions of the X Toolkit each widget class implemented an Xt<Widget>Create (for example, `XtLabelCreate`) function, in which most of the code was identical from widget to widget. In the Intrinsics, a single generic XtCreateWidget performs most of the common work and then calls the initialize procedure implemented for the particular widget class.

Each Composite class also implemented the procedures Xt<Widget>Add and an Xt<Widget>Delete (for example, `XtButtonBoxAddButton` and `XtButtonBoxDeleteButton`). In the Intrinsics, the Composite generic procedures XtManageChildren and XtUnmanageChildren perform error checking and screening out of certain children. Then they call the change_managed procedure implemented for the widget's Composite class. If the widget's parent has not yet been realized, the call to the change_managed procedure is delayed until realization time.

Old-style calls can be implemented in the X Toolkit by defining one-line procedures or macros that invoke a generic routine. For example, you could define the macro `XtLabelCreate` as:

    #define XtLabelCreate(name, parent, args, num_args) \
       ((LabelWidget) XtCreateWidget(name, labelWidgetClass, parent, args, num_args))

Pop-up shells in some of the prototypes automatically performed an XtManageChild on their child within their insert_child procedure. Creators of pop-up children need to call XtManageChild themselves.

XtAppInitialize and XtVaAppInitialize have been replaced by XtOpenApplication and XtVaOpenApplication.

To initialize the Intrinsics internals, create an application context, open and initialize a display, and create the initial application shell instance, an application may use XtAppInitialize or XtVaAppInitialize.

    Widget XtAppInitialize
       XtAppContext *app_context_return
       const char * application_class
       XrmOptionDescList options
       Cardinal num_options
       int *argc_in_out
       char ** argv_in_out
       String * fallback_resources
       ArgList args
       Cardinal num_args

app_context_return

- Returns the application context, if non-NULL.

application_class

- Specifies the class name of the application.

options

- Specifies the command line options table.

num_options

- Specifies the number of entries in options.

argc_in_out

- Specifies a pointer to the number of command line arguments.

argv_in_out

- Specifies a pointer to the command line arguments.

fallback_resources

- Specifies resource values to be used if the application class resource file cannot be opened or read, or NULL.

args

- Specifies the argument list to override any other resource specifications for the created shell widget.

num_args

- Specifies the number of entries in the argument list.

The XtAppInitialize function calls XtToolkitInitialize followed by XtCreateApplicationContext, then calls XtOpenDisplay with display_string NULL and application_name NULL, and finally calls XtAppCreateShell with application_name NULL, widget_class `applicationShellWidgetClass`, and the specified args and num_args and returns the created shell. The modified argc and argv returned by XtDisplayInitialize are returned in argc_in_out and argv_in_out. If app_context_return is not NULL, the created application context is also returned. If the display specified by the command line cannot be opened, an error message is issued and XtAppInitialize terminates the application. If fallback_resources is non-NULL, XtAppSetFallbackResources is called with the value prior to calling XtOpenDisplay.

    Widget XtVaAppInitialize
       XtAppContext *app_context_return
       const char * application_class
       XrmOptionDescList options
       Cardinal num_options
       int *argc_in_out
       char ** argv_in_out
       String * fallback_resources
       ...

app_context_return

- Returns the application context, if non-NULL.

application_class

- Specifies the class name of the application.

options

- Specifies the command line options table.

num_options

- Specifies the number of entries in options.

argc_in_out

- Specifies a pointer to the number of command line arguments.

argv_in_out

- Specifies the command line arguments array.

fallback_resources

- Specifies resource values to be used if the application class resource file cannot be opened, or NULL.

...

- Specifies the variable argument list to override any other resource specifications for the created shell.

The XtVaAppInitialize procedure is identical in function to XtAppInitialize with the args and num_args parameters replaced by a varargs list, as described in Section 2.5.1.

As a convenience to people converting from earlier versions of the toolkit without application contexts, the following routines exist: XtInitialize, XtMainLoop, XtNextEvent, XtProcessEvent, XtPeekEvent, XtPending, XtAddInput, XtAddTimeOut, XtAddWorkProc, XtCreateApplicationShell, XtAddActions, XtSetSelectionTimeout, and XtGetSelectionTimeout.

    Widget XtInitialize
       const char * shell_name
       const char * application_class
       XrmOptionDescRec * options
       Cardinal num_options
       int * argc
       char ** argv

shell_name

- This parameter is ignored; therefore, you can specify NULL.

application_class

- Specifies the class name of this application.

options

- Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to `XrmParseCommand`.

num_options

- Specifies the number of entries in the options list.

argc

- Specifies a pointer to the number of command line parameters.

argv

- Specifies the command line parameters.

XtInitialize calls XtToolkitInitialize to initialize the toolkit internals, creates a default application context for use by the other convenience routines, calls XtOpenDisplay with display_string NULL and application_name NULL, and finally calls XtAppCreateShell with application_name NULL and returns the created shell. The semantics of calling XtInitialize more than once are undefined. This routine has been replaced by XtOpenApplication.

    void XtMainLoop
       void

XtMainLoop first reads the next alternate input, timer, or X event by calling XtNextEvent. Then it dispatches this to the appropriate registered procedure by calling XtDispatchEvent. This routine has been replaced by XtAppMainLoop.

    void XtNextEvent
       XEvent *event_return

event_return

- Returns the event information to the specified event structure.

If no input is on the X input queue for the default application context, XtNextEvent flushes the X output buffer and waits for an event while looking at the alternate input sources and timeout values and calling any callback procedures triggered by them. This routine has been replaced by XtAppNextEvent. XtInitialize must be called before using this routine.

    void XtProcessEvent
       XtInputMask mask

mask

- Specifies the type of input to process.

XtProcessEvent processes one X event, timeout, or alternate input source (depending on the value of mask), blocking if necessary. It has been replaced by XtAppProcessEvent. XtInitialize must be called before using this function.

    Boolean XtPeekEvent
       XEvent *event_return

event_return

- Returns the event information to the specified event structure.

If there is an event in the queue for the default application context, XtPeekEvent fills in the event and returns a nonzero value. If no X input is on the queue, XtPeekEvent flushes the output buffer and blocks until input is available, possibly calling some timeout callbacks in the process. If the input is an event, XtPeekEvent fills in the event and returns a nonzero value. Otherwise, the input is for an alternate input source, and XtPeekEvent returns zero. This routine has been replaced by XtAppPeekEvent. XtInitialize must be called before using this routine.

    Boolean XtPending
      void

XtPending returns a nonzero value if there are events pending from the X server or alternate input sources in the default application context. If there are no events pending, it flushes the output buffer and returns a zero value. It has been replaced by XtAppPending. XtInitialize must be called before using this routine.

    XtInputId XtAddInput
       int source
       XtPointer condition
       XtInputCallbackProc proc
       XtPointer client_data

source

- Specifies the source file descriptor on a POSIX-based system or other operating-system-dependent device specification.

condition

- Specifies the mask that indicates either a read, write, or exception condition or some operating-system-dependent condition.

proc

- Specifies the procedure called when input is available.

client_data

- Specifies the parameter to be passed to proc when input is available.

The XtAddInput function registers in the default application context a new source of events, which is usually file input but can also be file output. (The word file should be loosely interpreted to mean any sink or source of data.) XtAddInput also specifies the conditions under which the source can generate events. When input is pending on this source in the default application context, the callback procedure is called. This routine has been replaced by XtAppAddInput. XtInitialize must be called before using this routine.

    XtIntervalId XtAddTimeOut
          unsigned long interval
       XtTimerCallbackProc proc
       XtPointer client_data

interval

- Specifies the time interval in milliseconds.

proc

- Specifies the procedure to be called when time expires.

client_data

- Specifies the parameter to be passed to proc when it is called.

The XtAddTimeOut function creates a timeout in the default application context and returns an identifier for it. The timeout value is set to interval. The callback procedure will be called after the time interval elapses, after which the timeout is removed. This routine has been replaced by XtAppAddTimeOut. XtInitialize must be called before using this routine.

    XtWorkProcId XtAddWorkProc
       XtWorkProc proc
       XtPointer client_data

proc

- Procedure to call to do the work.

client_data

- Client data to pass to proc when it is called.

This routine registers a work procedure in the default application context. It has been replaced by XtAppAddWorkProc. XtInitialize must be called before using this routine.

    Widget XtCreateApplicationShell
       const char * name
       WidgetClass widget_class
       ArgList args
       Cardinal num_args

name

- This parameter is ignored; therefore, you can specify NULL.

widget_class

- Specifies the widget class pointer for the created application shell widget. This will usually be `topLevelShellWidgetClass` or a subclass thereof.

args

- Specifies the argument list to override any other resource specifications.

num_args

- Specifies the number of entries in args.

The procedure XtCreateApplicationShell calls XtAppCreateShell with application_name NULL, the application class passed to XtInitialize, and the default application context created by XtInitialize. This routine has been replaced by XtAppCreateShell.

An old-format resource type converter procedure pointer is of type XtConverter.

    typedef void (*XtConverter)

       XrmValue *args
       Cardinal *num_args
       XrmValue *from
       XrmValue *to

args

- Specifies a list of additional `XrmValue` arguments to the converter if additional context is needed to perform the conversion, or NULL.

num_args

- Specifies the number of entries in args.

from

- Specifies the value to convert.

to

- Specifies the descriptor to use to return the converted value.

Type converters should perform the following actions:

- Check to see that the number of arguments passed is correct.

- Attempt the type conversion.

- If successful, return the size and pointer to the data in the to argument; otherwise, call XtWarningMsg and return without modifying the to argument.

Most type converters just take the data described by the specified from argument and return data by writing into the specified to argument. A few need other information, which is available in the specified argument list. A type converter can invoke another type converter, which allows differing sources that may convert into a common intermediate result to make maximum use of the type converter cache.

Note that the address returned in to->addr cannot be that of a local variable of the converter because this is not valid after the converter returns. It should be a pointer to a static variable.

The procedure type XtConverter has been replaced by XtTypeConverter.

The XtStringConversionWarning function is a convenience routine for old-format resource converters that convert from strings.

    void XtStringConversionWarning
       const char * src
       const char * dst_type

src

- Specifies the string that could not be converted.

dst_type

- Specifies the name of the type to which the string could not be converted.

The XtStringConversionWarning function issues a warning message with name “conversionError”, type “string”, class “XtToolkitError”, and the default message string “Cannot convert "src" to type dst_type”. This routine has been superseded by XtDisplayStringConversionWarning.

To register an old-format converter, use XtAddConverter or XtAppAddConverter.

    void XtAddConverter
       const char * from_type
       const char * to_type
       XtConverter converter
       XtConvertArgList convert_args
       Cardinal num_args

from_type

- Specifies the source type.

to_type

- Specifies the destination type.

converter

- Specifies the type converter procedure.

convert_args

- Specifies how to compute the additional arguments to the converter, or NULL.

num_args

- Specifies the number of entries in convert_args.

XtAddConverter is equivalent in function to XtSetTypeConverter with cache_type equal to `XtCacheAll` for old-format type converters. It has been superseded by XtSetTypeConverter.

    void XtAppAddConverter
       XtAppContext app_context
       const char * from_type
       const char * to_type
       XtConverter converter
       XtConvertArgList convert_args
       Cardinal num_args

app_context

- Specifies the application context.

from_type

- Specifies the source type.

to_type

- Specifies the destination type.

converter

- Specifies the type converter procedure.

convert_args

- Specifies how to compute the additional arguments to the converter, or NULL.

num_args

- Specifies the number of entries in convert_args.

XtAppAddConverter is equivalent in function to XtAppSetTypeConverter with cache_type equal to `XtCacheAll` for old-format type converters. It has been superseded by XtAppSetTypeConverter.

To invoke resource conversions, a client may use XtConvert or, for old-format converters only, XtDirectConvert.

    void XtConvert
       Widget w
       const char * from_type
       XrmValuePtr from
       const char * to_type
       XrmValuePtr to_return

w

- Specifies the widget to use for additional arguments, if any are needed.

from_type

- Specifies the source type.

from

- Specifies the value to be converted.

to_type

- Specifies the destination type.

to_return

- Returns the converted value.

    void XtDirectConvert
       XtConverter converter
       XrmValuePtr args
       Cardinal num_args
       XrmValuePtr from
       XrmValuePtr to_return

converter

- Specifies the conversion procedure to be called.

args

- Specifies the argument list that contains the additional arguments needed to perform the conversion (often NULL).

num_args

- Specifies the number of entries in args.

from

- Specifies the value to be converted.

to_return

- Returns the converted value.

The XtConvert function looks up the type converter registered to convert from_type to to_type, computes any additional arguments needed, and then calls XtDirectConvert or XtCallConverter. The XtDirectConvert function looks in the converter cache to see if this conversion procedure has been called with the specified arguments. If so, it returns a descriptor for information stored in the cache; otherwise, it calls the converter and enters the result in the cache.

Before calling the specified converter, XtDirectConvert sets the return value size to zero and the return value address to NULL. To determine if the conversion was successful, the client should check to_return.addr for non-NULL. The data returned by XtConvert must be copied immediately by the caller, as it may point to static data in the type converter.

XtConvert has been replaced by XtConvertAndStore, and XtDirectConvert has been superseded by XtCallConverter.

To deallocate a shared GC when it is no longer needed, use XtDestroyGC.

    void XtDestroyGC
       Widget w
       GC gc

w

- Specifies any object on the display for which the shared GC was created. Must be of class Object or any subclass thereof.

gc

- Specifies the shared GC to be deallocated.

References to shareable GCs are counted and a free request is generated to the server when the last user of a given GC destroys it. Note that some earlier versions of XtDestroyGC had only a gc argument. Therefore, this function is not very portable, and you are encouraged to use XtReleaseGC instead.

To declare an action table in the default application context and register it with the translation manager, use XtAddActions.

    void XtAddActions
       XtActionList actions
       Cardinal num_actions

actions

- Specifies the action table to register.

num_actions

- Specifies the number of entries in actions.

If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. The Intrinsics register an action table for XtMenuPopup and XtMenuPopdown as part of X Toolkit initialization. This routine has been replaced by XtAppAddActions. XtInitialize must be called before using this routine.

To set the Intrinsics selection timeout in the default application context, use XtSetSelectionTimeout.

    void XtSetSelectionTimeout
          unsigned long timeout

timeout

- Specifies the selection timeout in milliseconds. This routine has been replaced by XtAppSetSelectionTimeout. XtInitialize must be called before using this routine.

To get the current selection timeout value in the default application context, use XtGetSelectionTimeout.

    unsigned long XtGetSelectionTimeout
          void

The selection timeout is the time within which the two communicating applications must respond to one another. If one of them does not respond within this interval, the Intrinsics abort the selection request.

This routine has been replaced by XtAppGetSelectionTimeout. XtInitialize must be called before using this routine.

To obtain the global error database (for example, to merge with an application- or widget-specific database), use XtGetErrorDatabase.

    XrmDatabase *XtGetErrorDatabase
          void

The XtGetErrorDatabase function returns the address of the error database. The Intrinsics do a lazy binding of the error database and do not merge in the database file until the first call to `XtGetErrorDatabaseText`. This routine has been replaced by XtAppGetErrorDatabase.

An error message handler can obtain the error database text for an error or a warning by calling XtGetErrorDatabaseText.

    void XtGetErrorDatabaseText
       const char * name
       const char * type
       const char * class
       const char * default
       char * buffer_return
       int nbytes

name

type

- Specify the name and type that are concatenated to form the resource name of the error message.

class

- Specifies the resource class of the error message.

default

- Specifies the default message to use if an error database entry is not found.

buffer_return

- Specifies the buffer into which the error message is to be returned.

nbytes

- Specifies the size of the buffer in bytes.

The XtGetErrorDatabaseText returns the appropriate message from the error database associated with the default application context or returns the specified default message if one is not found in the error database. To form the full resource name and class when querying the database, the name and type are concatenated with a single “.” between them and the class is concatenated with itself with a single “.” if it does not already contain a “.”. This routine has been superseded by XtAppGetErrorDatabaseText.

To register a procedure to be called on fatal error conditions, use XtSetErrorMsgHandler.

    void XtSetErrorMsgHandler
       XtErrorMsgHandler msg_handler

msg_handler

- Specifies the new fatal error procedure, which should not return.

The default error handler provided by the Intrinsics constructs a string from the error resource database and calls XtError. Fatal error message handlers should not return. If one does, subsequent Intrinsics behavior is undefined. This routine has been superseded by XtAppSetErrorMsgHandler.

To call the high-level error handler, use XtErrorMsg.

    void XtErrorMsg
       const char * name
       const char * type
       const char * class
       const char * default
       String *params
       Cardinal *num_params

name

- Specifies the general kind of error.

type

- Specifies the detailed name of the error.

class

- Specifies the resource class.

default

- Specifies the default message to use if an error database entry is not found.

params

- Specifies a pointer to a list of values to be stored in the message.

num_params

- Specifies the number of entries in params.

This routine has been superseded by XtAppErrorMsg.

To register a procedure to be called on nonfatal error conditions, use XtSetWarningMsgHandler.

    void XtSetWarningMsgHandler
       XtErrorMsgHandler msg_handler

msg_handler

- Specifies the new nonfatal error procedure, which usually returns.

The default warning handler provided by the Intrinsics constructs a string from the error resource database and calls XtWarning. This routine has been superseded by XtAppSetWarningMsgHandler.

To call the installed high-level warning handler, use XtWarningMsg.

    void XtWarningMsg
       const char * name
       const char * type
       const char * class
       const char * default
       String *params
       Cardinal *num_params

name

- Specifies the general kind of error.

type

- Specifies the detailed name of the error.

class

- Specifies the resource class.

default

- Specifies the default message to use if an error database entry is not found.

params

- Specifies a pointer to a list of values to be stored in the message.

num_params

- Specifies the number of entries in params.

This routine has been superseded by XtAppWarningMsg.

To register a procedure to be called on fatal error conditions, use XtSetErrorHandler.

    void XtSetErrorHandler
       XtErrorHandler handler

handler

- Specifies the new fatal error procedure, which should not return.

The default error handler provided by the Intrinsics is `_XtError`. On POSIX-based systems, it prints the message to standard error and terminates the application. Fatal error message handlers should not return. If one does, subsequent X Toolkit behavior is undefined. This routine has been superseded by XtAppSetErrorHandler.

To call the installed fatal error procedure, use XtError.

    void XtError
       const char * message

message

- Specifies the message to be reported.

Most programs should use XtAppErrorMsg, not XtError, to provide for customization and internationalization of error messages. This routine has been superseded by XtAppError.

To register a procedure to be called on nonfatal error conditions, use XtSetWarningHandler.

    void XtSetWarningHandler
       XtErrorHandler handler

handler

- Specifies the new nonfatal error procedure, which usually returns.

The default warning handler provided by the Intrinsics is `_XtWarning`. On POSIX-based systems, it prints the message to standard error and returns to the caller. This routine has been superseded by XtAppSetWarningHandler.

To call the installed nonfatal error procedure, use XtWarning.

    void XtWarning
       const char * message

message

- Specifies the nonfatal error message to be reported.

Most programs should use XtAppWarningMsg, not XtWarning, to provide for customization and internationalization of warning messages. This routine has been superseded by XtAppWarning.